eo-tides 0.6.1__py3-none-any.whl → 0.6.2__py3-none-any.whl

eo_tides/model.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import os
 import textwrap
+import warnings
 from concurrent.futures import ProcessPoolExecutor
 from concurrent.futures.process import BrokenProcessPool
 from functools import partial
@@ -83,6 +84,7 @@ def _model_tides(
     cutoff,
     crop,
     crop_buffer,
+    append_node,
 ):
     """Worker function applied in parallel by `model_tides`. Handles the
     extraction of tide modelling constituents and tide modelling using
@@ -104,12 +106,12 @@ def _model_tides(
             lon,
             lat,
             type=pytmd_model.type,
-            crop=crop,
+            crop=True if crop == "auto" else crop,
             buffer=crop_buffer,
             method=method,
             extrapolate=extrapolate,
             cutoff=cutoff,
-            append_node=False,
+            append_node=append_node,
         )
 
         # TODO: Return constituents
@@ -117,16 +119,45 @@ def _model_tides(
         # print(amp.shape, ph.shape, c)
         # print(pd.DataFrame({"amplitude": amp}))
 
-    # Raise error if constituent files no not cover analysis extent
+    except ValueError:
+        # If on-the-fly cropping is auto, try again with crop turned off
+        if crop == "auto":
+            warnings.warn(
+                "On-the-fly cropping is not compatible with the provided "
+                "clipped model files; running with `crop=False`."
+            )
+
+            # Read tidal constants and interpolate to grid points
+            amp, ph, c = pytmd_model.extract_constants(
+                lon,
+                lat,
+                type=pytmd_model.type,
+                crop=False,
+                buffer=crop_buffer,
+                method=method,
+                extrapolate=extrapolate,
+                cutoff=cutoff,
+                append_node=append_node,
+            )
+
+        # Otherwise, raise error if cropping if set to True
+        else:
+            error_msg = (
+                "On-the-fly cropping (e.g. `crop=True`) is not compatible with your "
+                "provided clipped model files. Please set `crop=False` or `crop='auto'`, "
+                "or run your analysis on unclipped global model files to avoid this error."
+            )
+            raise Exception(error_msg) from None
+
+    # Raise error if constituent files do not cover analysis extent
     except IndexError:
-        error_msg = f"""
-        The {model} tide model constituent files do not cover the analysis extent
-        ({min(lon):.2f}, {max(lon):.2f}, {min(lat):.2f}, {max(lat):.2f}).
-        This can occur if you are using clipped model files to improve run times.
-        Consider using model files that cover your entire analysis area, or set `crop=False`
-        to reduce the extent of tide model constituent files that is loaded.
-        """
-        raise Exception(textwrap.dedent(error_msg).strip()) from None
+        error_msg = (
+            f"The {model} tide model constituent files do not cover the analysis extent "
+            f"({min(lon):.2f}, {max(lon):.2f}, {min(lat):.2f}, {max(lat):.2f}). "
+            "This can occur if you are using clipped model files to improve run times. "
+            "Consider using model files that cover your entire analysis area."
+        )
+        raise Exception(error_msg) from None
 
     # Calculate complex phase in radians for Euler's
     cph = -1j * ph * np.pi / 180.0
@@ -397,8 +428,9 @@ def model_tides(
     method: str = "linear",
     extrapolate: bool = True,
     cutoff: float | None = None,
-    crop: bool = True,
+    crop: bool | str = "auto",
     crop_buffer: float | None = 5,
+    append_node: bool = False,
     parallel: bool = True,
     parallel_splits: int | str = "auto",
     parallel_max: int | None = None,
@@ -431,10 +463,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
@@ -466,7 +503,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
@@ -488,26 +525,37 @@ 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
         valid tide modelling domain.
-    crop : bool, optional
+    crop : bool or str, optional
         Whether to crop tide model constituent files on-the-fly to
-        improve performance. Defaults to True; use `crop_buffer`
-        to customise the buffer distance used to crop the files.
+        improve performance. Defaults to "auto", which will attempt to
+        apply on-the-fly cropping where possible (some clipped model
+        files restricted entirely to the western hemisphere are not
+        suitable for on-the-fly cropping). Set `crop_buffer` to
+        customise the buffer distance used to crop the files.
     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.
+    append_node: bool, optional
+        Apply adjustments to harmonic constituents to allow for periodic
+        modulations over the 18.6-year nodal period (lunar nodal tide).
+        Default is False.
     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,
@@ -591,6 +639,7 @@ def model_tides(
         cutoff=np.inf if cutoff is None else cutoff,
         crop=crop,
         crop_buffer=crop_buffer,
+        append_node=append_node,
     )
 
     # If automatic parallel splits, calculate optimal value
@@ -722,11 +771,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-0.6.1.dist-info → eo_tides-0.6.2.dist-info}/METADATA

@@ -1,28 +1,27 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: eo-tides
-Version: 0.6.1
+Version: 0.6.2
 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,7 +31,7 @@ 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.2
+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
@@ -40,11 +39,12 @@ 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.2.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=EqulqgiqwzOOtBSqgPHDIX1tW3w6e-lkjF6nsjWFG1U,37173
+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.2.dist-info/METADATA,sha256=sbboJeyayqLIonkWQjjwWT5Svh8jKfTNfeotp7V-fsw,8184
+eo_tides-0.6.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+eo_tides-0.6.2.dist-info/licenses/LICENSE,sha256=owxWsXViCL2J6Ks3XYhot7t4Y93nstmXAT95Zf030Cc,11350
+eo_tides-0.6.2.dist-info/RECORD,,

{eo_tides-0.6.1.dist-info → eo_tides-0.6.2.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.1.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=XqgV3Arvkr3Z8PR6EvTMZbg8WnnpYCDOjFL2-sOXeF0,34695
-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.dist-info/LICENSE,sha256=owxWsXViCL2J6Ks3XYhot7t4Y93nstmXAT95Zf030Cc,11350
-eo_tides-0.6.1.dist-info/METADATA,sha256=sl9C1TQIgpC6ZDLeHAJOm0Ea9tyDyZU4zvJg4fd2OBE,8184
-eo_tides-0.6.1.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-eo_tides-0.6.1.dist-info/top_level.txt,sha256=lXZDUUM1DlLdKWHRn8zdmtW8Rx-eQOIWVvt0b8VGiyQ,9
-eo_tides-0.6.1.dist-info/RECORD,,

eo_tides-0.6.1.dist-info/top_level.txt

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