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

eo_tides/eo.py

@@ -15,7 +15,7 @@ from odc.geo.geobox import GeoBox
 if TYPE_CHECKING:
     from odc.geo import Shape2d
 
-from .model import model_tides
+from .model import model_phases, model_tides
 from .utils import DatetimeLike, _standardise_time
 
 
@@ -168,26 +168,28 @@ def tag_tides(
     directory: str | os.PathLike | None = None,
     tidepost_lat: float | None = None,
     tidepost_lon: float | None = None,
+    return_phases: bool = False,
     **model_tides_kwargs,
-) -> xr.DataArray:
+) -> xr.DataArray | xr.Dataset:
     """
-    Model tide heights for every timestep in a multi-dimensional
-    dataset, and return a new `tide_height` array that can
-    be used to "tag" each observation with tide heights.
+    Model tide heights and tide phases for every timestep in a
+    multi-dimensional dataset, and return a new array that can
+    be used to "tag" each observation with tide information.
 
     The function models tides at the centroid of the dataset
-    by default, but a custom tidal modelling location can
-    be specified using `tidepost_lat` and `tidepost_lon`.
+    by default, but a custom tidal modelling location can be
+    specified using `tidepost_lat` and `tidepost_lon`.
 
-    This function uses the parallelised `model_tides` function
-    under the hood. It supports all tidal models supported by
-    `pyTMD`, including:
+    This function uses the parallelised `model_tides` and
+    `model_phases` functions under the hood. It supports all tidal
+    models supported by `pyTMD`, including:
 
     - Empirical Ocean Tide model (EOT20)
     - Finite Element Solution tide models (FES2022, FES2014, FES2012)
     - TOPEX/POSEIDON global tide models (TPXO10, TPXO9, TPXO8)
     - Global Ocean Tide models (GOT5.6, GOT5.5, GOT4.10, GOT4.8, GOT4.7)
     - Hamburg direct data Assimilation Methods for Tides models (HAMTIDE11)
+    - Technical University of Denmark tide models (DTU23)
 
     Parameters
     ----------
@@ -209,7 +211,7 @@ def tag_tides(
         added to the `xarray.DataArray` outputs. Defaults to "EOT20";
         specify "all" to use all models available in `directory`.
         For a full list of available and supported models, run
-        `eo_tides.utils.list_models`.
+        `from eo_tides.utils import list_models; list_models()`.
     directory : str, optional
         The directory containing tide model data files. If no path is
         provided, this will default to the environment variable
@@ -221,6 +223,10 @@ def tag_tides(
         Optional coordinates used to model tides. The default is None,
         which uses the centroid of the dataset as the tide modelling
         location.
+    return_phases : bool, optional
+        Whether to model and return tide phases in addition to tide heights.
+        If True, outputs will be returned as an xr.Dataset containing both
+        "tide_height" and "tide_phase" variables.
     **model_tides_kwargs :
         Optional parameters passed to the `eo_tides.model.model_tides`
         function. Important parameters include `cutoff` (used to
@@ -230,10 +236,12 @@ def tag_tides(
 
     Returns
     -------
-    tides_da : xr.DataArray
-        A one-dimensional tide height array. This will contain either
-        tide heights for every timestep in `data`, or for every time in
-        `times` if provided.
+    tides_da : xr.DataArray or xr.Dataset
+        If `return_phases=False`: a one-dimensional "tide_height" xr.DataArray.
+        If `return_phases=True`: a one-dimensional xr.Dataset containing
+        "tide_height" and "tide_phase" variables.
+        Outputs will contain values for every timestep in `data`, or for
+        every time in `times` if provided.
     """
     # Standardise data inputs, time and models
     gbox, time_coords = _standardise_inputs(data, time)
@@ -247,16 +255,31 @@ def tag_tides(
         lon, lat = tidepost_lon, tidepost_lat
         print(f"Using tide modelling location: {lon:.2f}, {lat:.2f}")
 
-    # Model tide heights for each observation:
-    tide_df = model_tides(
-        x=lon,  # type: ignore
-        y=lat,  # type: ignore
-        time=time_coords,
-        model=model,
-        directory=directory,
-        crs="EPSG:4326",
-        **model_tides_kwargs,
-    )
+    # Either model both tides and phases, or model only tides
+    if return_phases:
+        # Model tide phases and heights for each observation
+        tide_df = model_phases(
+            x=lon,  # type: ignore
+            y=lat,  # type: ignore
+            time=time_coords,
+            model=model,
+            directory=directory,
+            crs="EPSG:4326",
+            return_tides=True,
+            **model_tides_kwargs,
+        )
+
+    else:
+        # Model tide heights for each observation
+        tide_df = model_tides(
+            x=lon,  # type: ignore
+            y=lat,  # type: ignore
+            time=time_coords,
+            model=model,
+            directory=directory,
+            crs="EPSG:4326",
+            **model_tides_kwargs,
+        )
 
     # If tides cannot be successfully modeled (e.g. if the centre of the
     # xarray dataset is located is over land), raise an exception
@@ -269,8 +292,9 @@ def tag_tides(
             f"`tidepost_lat` and `tidepost_lon` parameters."
         )
 
-    # Convert to xarray format
-    tides_da = tide_df.reset_index().set_index(["time", "tide_model"]).drop(["x", "y"], axis=1).tide_height.to_xarray()
+    # Convert to xarray format, squeezing to return an xr.DataArray if
+    # dataframe contains only one "tide_height" column
+    tides_da = tide_df.reset_index().set_index(["time", "tide_model"]).drop(["x", "y"], axis=1).squeeze().to_xarray()
 
     # If only one tidal model exists, squeeze out "tide_model" dim
     if len(tides_da.tide_model) == 1:
@@ -313,6 +337,7 @@ def pixel_tides(
     - TOPEX/POSEIDON global tide models (TPXO10, TPXO9, TPXO8)
     - Global Ocean Tide models (GOT5.6, GOT5.5, GOT4.10, GOT4.8, GOT4.7)
     - Hamburg direct data Assimilation Methods for Tides models (HAMTIDE11)
+    - Technical University of Denmark tide models (DTU23)
 
     This function requires access to tide model data files.
     These should be placed in a folder with subfolders matching
@@ -340,7 +365,7 @@ def pixel_tides(
         added to the `xarray.DataArray` outputs. Defaults to "EOT20";
         specify "all" to use all models available in `directory`.
         For a full list of available and supported models, run
-        `eo_tides.utils.list_models`.
+        `from eo_tides.utils import list_models; list_models()`.
     directory : str, optional
         The directory containing tide model data files. If no path is
         provided, this will default to the environment variable

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),
     )
@@ -416,6 +417,7 @@ def model_tides(
     - TOPEX/POSEIDON global tide models (TPXO10, TPXO9, TPXO8)
     - Global Ocean Tide models (GOT5.6, GOT5.5, GOT4.10, GOT4.8, GOT4.7)
     - Hamburg direct data Assimilation Methods for Tides models (HAMTIDE11)
+    - Technical University of Denmark tide models (DTU23)
 
     This function requires access to tide model data files.
     These should be placed in a folder with subfolders matching
@@ -444,7 +446,7 @@ def model_tides(
         The tide model (or list of models) to use to model tides.
         Defaults to "EOT20"; specify "all" to use all models available
         in `directory`. For a full list of available and supported models,
-        run `eo_tides.utils.list_models`.
+        run `from eo_tides.utils import list_models; list_models()`.
     directory : str, optional
         The directory containing tide model data files. If no path is
         provided, this will default to the environment variable
@@ -735,7 +737,7 @@ def model_phases(
         The tide model (or list of models) to use to model tides.
         Defaults to "EOT20"; specify "all" to use all models available
         in `directory`. For a full list of available and supported models,
-        run `eo_tides.utils.list_models`.
+        run `from eo_tides.utils import list_models; list_models()`.
     directory : str, optional
         The directory containing tide model data files. If no path is
         provided, this will default to the environment variable

eo_tides/stats.py

@@ -243,10 +243,11 @@ def tide_stats(
     model : str or list of str, optional
         The tide model (or list of models) to use to model tides.
         If a list is provided, the resulting statistics will be
-        returned as a `pandas.Dataframe`; otherwise a `pandas.Series`.
-        Defaults to "EOT20"; specify "all" to use all models available
-        in `directory`. For a full list of available and supported
-        models, run `eo_tides.utils.list_models`.
+        returned as a `pandas.Dataframe`; otherwise a `pandas.Series`
+        will be returned. Defaults to "EOT20"; specify "all" to use
+        all models available in `directory`. For a full list of
+        available and supported models, run
+        `from eo_tides.utils import list_models; list_models()`.
     directory : str, optional
         The directory containing tide model data files. If no path is
         provided, this will default to the environment variable
@@ -453,7 +454,7 @@ def pixel_stats(
         added to the `xarray.Dataset` output. Defaults to "EOT20";
         specify "all" to use all models available in `directory`.
         For a full list of available and supported models, run
-        `eo_tides.utils.list_models`.
+        `from eo_tides.utils import list_models; list_models()`.
     directory : str, optional
         The directory containing tide model data files. If no path is
         provided, this will default to the environment variable

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.5.0.dist-info → eo_tides-0.6.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: eo-tides
-Version: 0.5.0
+Version: 0.6.1
 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
@@ -32,10 +32,11 @@ 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.0
+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
@@ -54,6 +55,7 @@ Requires-Dist: planetary_computer>=1.0.0; extra == "notebooks"
 [![Python Version from PEP 621 TOML](https://img.shields.io/pypi/pyversions/eo-tides)](https://github.com/GeoscienceAustralia/eo-tides/blob/main/pyproject.toml)
 [![codecov](https://codecov.io/gh/GeoscienceAustralia/eo-tides/branch/main/graph/badge.svg)](https://codecov.io/gh/GeoscienceAustralia/eo-tides)
 [![License](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)
+[![status](https://joss.theoj.org/papers/b5680c39bf831c1159c41a2eb7ec9c5e/status.svg)](https://joss.theoj.org/papers/b5680c39bf831c1159c41a2eb7ec9c5e)
 
 - ⚙️ **Github repository**: <https://github.com/GeoscienceAustralia/eo-tides/>
 - 📘 **Documentation**: <https://GeoscienceAustralia.github.io/eo-tides/>
@@ -87,6 +89,7 @@ These tools can be applied to petabytes of freely available satellite data (e.g.
 - [TOPEX/POSEIDON global tide models](https://www.tpxo.net/global) (TPXO10, TPXO9, TPXO8)
 - [Global Ocean Tide models](https://doi.org/10.1002/2016RG000546) (GOT5.6, GOT5.5, GOT4.10, GOT4.8, GOT4.7)
 - [Hamburg direct data Assimilation Methods for Tides models](https://doi.org/10.1002/2013JC009766) (HAMTIDE11)
+- [Technical University of Denmark tide models](https://doi.org/10.11583/DTU.23828874) (DTU23)
 
 For instructions on how to set up these models for use in `eo-tides`, refer to [Setting up tide models](setup.md).
 

eo_tides-0.6.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+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.5.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-eo_tides/__init__.py,sha256=pGvVlxMKiYjm_273G-oYcOgVuPra7uEdNZv0oN1i69c,1693
-eo_tides/eo.py,sha256=nuaOppYJCVL8mbFyaL9e4ahHB_LBGBrr5XfnAopmW5M,22746
-eo_tides/model.py,sha256=xpKaVO1_cLLwbODpffqDL80Hw7Yv9JchH42tKhX1oto,34585
-eo_tides/stats.py,sha256=RXs3J3YZH3yOrzDibEDp3-7wjkleOEFzO33lp27ATuE,22993
-eo_tides/utils.py,sha256=9xJ1q-b-TVHg5zFyLy6AT_srrPQDvmFdWJmlGSPaJF0,26563
-eo_tides/validation.py,sha256=KP8WLT5z7KLFjQ9oDla7VJOyLQAK4SVbcz2ySAbsbwI,11882
-eo_tides-0.5.0.dist-info/LICENSE,sha256=owxWsXViCL2J6Ks3XYhot7t4Y93nstmXAT95Zf030Cc,11350
-eo_tides-0.5.0.dist-info/METADATA,sha256=CtP3dQKJAbs1bEZaJz0egfina4OD4jba4TGDlLxxIPg,7906
-eo_tides-0.5.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-eo_tides-0.5.0.dist-info/top_level.txt,sha256=lXZDUUM1DlLdKWHRn8zdmtW8Rx-eQOIWVvt0b8VGiyQ,9
-eo_tides-0.5.0.dist-info/RECORD,,