eo-tides 0.6.0__py3-none-any.whl → 0.6.1.dev6__py3-none-any.whl

eo_tides/model.py

@@ -19,6 +19,7 @@ import numpy as np
 import pandas as pd
 import pyproj
 import pyTMD
+import timescale.time
 from tqdm import tqdm
 
 from .utils import DatetimeLike, _set_directory, _standardise_models, _standardise_time, idw
@@ -95,7 +96,7 @@ def _model_tides(
     lon, lat = transformer.transform(x.flatten(), y.flatten())
 
     # Convert datetime
-    timescale = pyTMD.time.timescale().from_datetime(time.flatten())
+    ts = timescale.time.Timescale().from_datetime(time.flatten())
 
     try:
         # Read tidal constants and interpolate to grid points
@@ -136,10 +137,10 @@ def _model_tides(
     # Compute delta times based on model
     if pytmd_model.corrections in ("OTIS", "ATLAS", "TMD3", "netcdf"):
         # Use delta time at 2000.0 to match TMD outputs
-        deltat = np.zeros_like(timescale.tt_ut1)
+        deltat = np.zeros_like(ts.tt_ut1)
     else:
         # Use interpolated delta times
-        deltat = timescale.tt_ut1
+        deltat = ts.tt_ut1
 
     # In "one-to-many" mode, extracted tidal constituents and timesteps
     # are repeated/multiplied out to match the number of input points and
@@ -149,7 +150,7 @@ def _model_tides(
     points_repeat = len(x) if mode == "one-to-many" else 1
     time_repeat = len(time) if mode == "one-to-many" else 1
     t, hc, deltat = (
-        np.tile(timescale.tide, points_repeat),
+        np.tile(ts.tide, points_repeat),
         hc.repeat(time_repeat, axis=0),
         np.tile(deltat, points_repeat),
     )
@@ -430,10 +431,15 @@ def model_tides(
 
     Parameters
     ----------
-    x, y : float or list of float
-        One or more x and y coordinates used to define
-        the location at which to model tides. By default these
-        coordinates should be lat/lon; use "crs" if they
+    x : float or list of float
+        One or more x coordinates used to define the location at
+        which to model tides. By default these coordinates should
+        be in "EPSG:4326" WGS84 degrees longitude; use "crs" if they
+        are in a custom coordinate reference system.
+    y : float or list of float
+        One or more y coordinates used to define the location at
+        which to model tides. By default these coordinates should
+        be in "EPSG:4326" WGS84 degrees latitude; use "crs" if they
         are in a custom coordinate reference system.
     time : DatetimeLike
         Times at which to model tide heights (in UTC). Accepts
@@ -465,7 +471,7 @@ def model_tides(
         multiple spatial points (e.g. for the same set of satellite
         acquisition times at various locations across your study area).
         - "one-to-one": Model tides using a unique timestep for each
-        set of x and y coordinates. In this mode, the number of x and
+        x and y coordinate pair. In this mode, the number of x and
         y points must equal the number of timesteps provided in "time".
     output_format : str, optional
         Whether to return the output dataframe in long format (with
@@ -487,8 +493,12 @@ def model_tides(
         - "spline": scipy bivariate spline interpolation
         - "bilinear": quick bilinear interpolation
     extrapolate : bool, optional
-        Whether to extrapolate tides into x and y coordinates outside of
-        the valid tide modelling domain using nearest-neighbor.
+        Whether to extrapolate tides into x and y coordinates outside
+        of the valid tide modelling domain using nearest-neighbor
+        interpolation. The default of True ensures that modelled tides
+        will be returned even if there is no underlying tide model
+        data for a location (e.g. inside estuaries far from the
+        coastline). However, this can also produce unreliable results.
     cutoff : float, optional
         Extrapolation cutoff in kilometers. The default is None, which
         will extrapolate for all points regardless of distance from the
@@ -500,13 +510,13 @@ def model_tides(
     crop_buffer : int or float, optional
         The buffer distance in degrees used to crop tide model
         constituent files around the modelling area. Defaults to 5,
-        which will crop constituents using a five degree buffer on either
-        side of the analysis extent.
+        which will crop constituents using a five degree buffer on
+        either side of the analysis extent.
     parallel : bool, optional
-        Whether to parallelise tide modelling. If multiple tide models are
-        requested, these will be run in parallel using `concurrent.futures`.
-        If enough workers are available, the analysis will also be split
-        into spatial chunks for additional parallelisation (see "parallel_splits"
+        Whether to parallelise tide modelling. If multiple tide models
+        are requested, these will be run in parallel. If enough workers
+        are available, the analysis will also be split into spatial
+        chunks for additional parallelisation (see "parallel_splits"
         below). Default is True.
     parallel_splits : str or int, optional
         Whether to split the input x and y coordinates into smaller,
@@ -721,11 +731,16 @@ def model_phases(
 
     Parameters
     ----------
-    x, y : float or list of float
-        One or more x and y coordinates used to define
-        the location at which to model tide phases. By default
-        these coordinates should be lat/lon; use "crs" if they
-        are in a custom coordinate reference system.
+    x : float or list of float
+        One or more x coordinates used to define the location at
+        which to model tide phases. By default these coordinates
+        should be in "EPSG:4326" WGS84 degrees longitude; use "crs"
+        if they are in a custom coordinate reference system.
+    y : float or list of float
+        One or more y coordinates used to define the location at
+        which to model tide phases. By default these coordinates
+        should be in "EPSG:4326" WGS84 degrees latitude; use "crs"
+        if they are in a custom coordinate reference system.
     time : DatetimeLike
         Times at which to model tide phases (in UTC). Accepts
         any format that can be converted by `pandas.to_datetime()`;

eo_tides/utils.py

@@ -181,9 +181,9 @@ def _clip_model_file(
     """
     Clips tide model netCDF datasets to a bounding box.
 
-    If the bounding box crosses 0 degrees longitude (e.g. Greenwich),
-    the function will clip the dataset into two parts and concatenate
-    them along the x-dimension to create a continuous result.
+    If the bounding box crosses 0 degrees longitude (e.g. Greenwich prime
+    meridian), the dataset will be clipped into two parts and concatenated
+    along the x-dimension to create a continuous result.
 
     Parameters
     ----------
@@ -226,20 +226,22 @@ def _clip_model_file(
     xcoords = nc[xcoord].compute()
     ycoords = nc[ycoord].compute()
 
-    # If data falls within 0-360 degree bounds, then clip directly
-    if (bbox.left >= 0) & (bbox.right <= 360):
+    # Convert longitudes to 0-360 convention
+    left = bbox.left % 360
+    right = bbox.right % 360
+
+    # If left coordinate is smaller than right, bbox does not cross
+    # zero longitude and can be clipped directly
+    if left <= right:  # bbox does not cross 0
         nc_clipped = nc.sel({
             ydim: (ycoords >= bbox.bottom) & (ycoords <= bbox.top),
-            xdim: (xcoords >= bbox.left) & (xcoords <= bbox.right),
+            xdim: (xcoords >= left) & (xcoords <= right),
         })
 
-    # If bbox crosses zero longitude, extract left and right
-    # separately and then combine into one concatenated dataset
-    elif (bbox.left < 0) & (bbox.right > 0):
-        # Convert longitudes to 0-360 range
-        left = bbox.left % 360
-        right = bbox.right % 360
-
+    # If left coordinate is larger than right, bbox crosses zero longitude.
+    # If so, extract left and right separately and then combine into one
+    # concatenated dataset
+    elif left > right:  # bbox crosses 0
         # Extract data from left of 0 longitude, and convert lon
         # coords to -180 to 0 range to enable continuous interpolation
         # across 0 boundary
@@ -357,7 +359,7 @@ def clip_models(
         model_files = model_database[m].get("model_file", [])
         grid_file = model_database[m].get("grid_file", [])
 
-        # Convert to list if strings and combine
+        # Convert to list of strings and combine
         model_files = model_files if isinstance(model_files, list) else [model_files]
         grid_file = grid_file if isinstance(grid_file, list) else [grid_file]
         all_files = model_files + grid_file

{eo_tides-0.6.0.dist-info → eo_tides-0.6.1.dev6.dist-info}/METADATA

@@ -1,28 +1,27 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: eo-tides
-Version: 0.6.0
+Version: 0.6.1.dev6
 Summary: Tide modelling tools for large-scale satellite earth observation analysis
-Author: Robbi Bishop-Taylor, Stephen Sagar, Claire Phillips, Vanessa Newey
-Author-email: Robbi.BishopTaylor@ga.gov.au
 Project-URL: Homepage, https://GeoscienceAustralia.github.io/eo-tides/
 Project-URL: Repository, https://github.com/GeoscienceAustralia/eo-tides
 Project-URL: Documentation, https://GeoscienceAustralia.github.io/eo-tides/
-Keywords: earth observation,tide modelling,tide modeling,satellite data,coastal analysis,oceanography,remote sensing
+Author: Robbi Bishop-Taylor, Stephen Sagar, Claire Phillips, Vanessa Newey
+Author-email: Robbi.BishopTaylor@ga.gov.au
+License-File: LICENSE
+Keywords: coastal analysis,earth observation,oceanography,remote sensing,satellite data,tide modeling,tide modelling
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
-Classifier: Topic :: Scientific/Engineering
-Classifier: Topic :: Scientific/Engineering :: GIS
-Classifier: Topic :: Scientific/Engineering :: Oceanography
-Classifier: Topic :: Scientific/Engineering :: Visualization
-Classifier: Topic :: Scientific/Engineering :: Image Processing
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Oceanography
+Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: <4.0,>=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
 Requires-Dist: colorama>=0.4.3
 Requires-Dist: geopandas>=0.10.0
 Requires-Dist: matplotlib>=3.8.0
@@ -32,18 +31,20 @@ Requires-Dist: pandas>=2.2.0
 Requires-Dist: psutil>=5.8.0
 Requires-Dist: pyogrio>=0.10.0
 Requires-Dist: pyproj>=3.7.0
-Requires-Dist: pyTMD==2.2.1
+Requires-Dist: pytmd>=2.2.2
 Requires-Dist: scikit-learn>=1.4.0
 Requires-Dist: scipy>=1.14.1
 Requires-Dist: shapely>=2.0.6
+Requires-Dist: timescale>=0.0.3
 Requires-Dist: tqdm>=4.55.0
 Requires-Dist: xarray>=2022.3.0
 Provides-Extra: notebooks
-Requires-Dist: odc-stac>=0.3.10; extra == "notebooks"
-Requires-Dist: odc-geo[tiff,warp]>=0.4.7; extra == "notebooks"
-Requires-Dist: pystac-client>=0.8.3; extra == "notebooks"
-Requires-Dist: folium>=0.16.0; extra == "notebooks"
-Requires-Dist: planetary_computer>=1.0.0; extra == "notebooks"
+Requires-Dist: folium>=0.16.0; extra == 'notebooks'
+Requires-Dist: odc-geo[tiff,warp]>=0.4.7; extra == 'notebooks'
+Requires-Dist: odc-stac>=0.3.10; extra == 'notebooks'
+Requires-Dist: planetary-computer>=1.0.0; extra == 'notebooks'
+Requires-Dist: pystac-client>=0.8.3; extra == 'notebooks'
+Description-Content-Type: text/markdown
 
 # `eo-tides`: Tide modelling tools for large-scale satellite earth observation analysis
 

eo_tides-0.6.1.dev6.dist-info/RECORD

@@ -0,0 +1,10 @@
+eo_tides/__init__.py,sha256=pGvVlxMKiYjm_273G-oYcOgVuPra7uEdNZv0oN1i69c,1693
+eo_tides/eo.py,sha256=TuFt9SSiO9Z2o8Kr1g-wFPzofp0HTcgkfhT83zu03kc,23983
+eo_tides/model.py,sha256=JjlT5TgylqKTAw-WQ-BC4zhDL7B_QNP0fwtDyZmX9Y4,35553
+eo_tides/stats.py,sha256=ELQpqIH86442IYgjrGrIK3mi0-pu2ZijFw53arA2FYg,23072
+eo_tides/utils.py,sha256=T19OuPLHzaUKcovCVGANvmOiRu-L8VuDXSTzmNlA6Bo,26647
+eo_tides/validation.py,sha256=KP8WLT5z7KLFjQ9oDla7VJOyLQAK4SVbcz2ySAbsbwI,11882
+eo_tides-0.6.1.dev6.dist-info/METADATA,sha256=HaLaT7M4sXeNOKVG6OvMWxc1Yv4T-M-tw3_YcI5nquU,8189
+eo_tides-0.6.1.dev6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+eo_tides-0.6.1.dev6.dist-info/licenses/LICENSE,sha256=owxWsXViCL2J6Ks3XYhot7t4Y93nstmXAT95Zf030Cc,11350
+eo_tides-0.6.1.dev6.dist-info/RECORD,,

{eo_tides-0.6.0.dist-info → eo_tides-0.6.1.dev6.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.8.0)
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any
-

eo_tides-0.6.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-eo_tides/__init__.py,sha256=pGvVlxMKiYjm_273G-oYcOgVuPra7uEdNZv0oN1i69c,1693
-eo_tides/eo.py,sha256=TuFt9SSiO9Z2o8Kr1g-wFPzofp0HTcgkfhT83zu03kc,23983
-eo_tides/model.py,sha256=C1KLX-Zd26tghGN-GcOo6J_EXYb6G6LDe_jFgV6dVNM,34697
-eo_tides/stats.py,sha256=ELQpqIH86442IYgjrGrIK3mi0-pu2ZijFw53arA2FYg,23072
-eo_tides/utils.py,sha256=9xJ1q-b-TVHg5zFyLy6AT_srrPQDvmFdWJmlGSPaJF0,26563
-eo_tides/validation.py,sha256=KP8WLT5z7KLFjQ9oDla7VJOyLQAK4SVbcz2ySAbsbwI,11882
-eo_tides-0.6.0.dist-info/LICENSE,sha256=owxWsXViCL2J6Ks3XYhot7t4Y93nstmXAT95Zf030Cc,11350
-eo_tides-0.6.0.dist-info/METADATA,sha256=nyHw0zHLG-a-gvk4WUf2KHLplabBH12LSN-8uOjTC0M,8152
-eo_tides-0.6.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-eo_tides-0.6.0.dist-info/top_level.txt,sha256=lXZDUUM1DlLdKWHRn8zdmtW8Rx-eQOIWVvt0b8VGiyQ,9
-eo_tides-0.6.0.dist-info/RECORD,,

eo_tides-0.6.0.dist-info/top_level.txt

@@ -1 +0,0 @@
-eo_tides