eo-tides 0.4.0__tar.gz → 0.6.0__tar.gz

{eo_tides-0.4.0 → eo_tides-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: eo-tides
-Version: 0.4.0
+Version: 0.6.0
 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
@@ -16,12 +16,11 @@ 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.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: <4.0,>=3.9
+Requires-Python: <4.0,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: colorama>=0.4.3
@@ -31,11 +30,11 @@ Requires-Dist: numpy>=1.26.0
 Requires-Dist: odc-geo>=0.4.7
 Requires-Dist: pandas>=2.2.0
 Requires-Dist: psutil>=5.8.0
-Requires-Dist: pyogrio>=0.7.0
-Requires-Dist: pyproj>=3.6.1
-Requires-Dist: pyTMD==2.2.0
+Requires-Dist: pyogrio>=0.10.0
+Requires-Dist: pyproj>=3.7.0
+Requires-Dist: pyTMD==2.2.1
 Requires-Dist: scikit-learn>=1.4.0
-Requires-Dist: scipy>=1.11.2
+Requires-Dist: scipy>=1.14.1
 Requires-Dist: shapely>=2.0.6
 Requires-Dist: tqdm>=4.55.0
 Requires-Dist: xarray>=2022.3.0
@@ -55,13 +54,13 @@ 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/>
 - 🐍 **PyPI**: <https://pypi.org/project/eo-tides/>
 
-> [!CAUTION]
-> This package is a work in progress, and not currently ready for operational use.
+<br>
 
 `eo-tides` provides powerful parallelized tools for integrating satellite Earth observation data with tide modelling. 🛠️🌊🛰️
 
@@ -89,6 +88,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.4.0 → eo_tides-0.6.0}/README.md

@@ -7,13 +7,13 @@
 [![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/>
 - 🐍 **PyPI**: <https://pypi.org/project/eo-tides/>
 
-> [!CAUTION]
-> This package is a work in progress, and not currently ready for operational use.
+<br>
 
 `eo-tides` provides powerful parallelized tools for integrating satellite Earth observation data with tide modelling. 🛠️🌊🛰️
 
@@ -41,6 +41,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.4.0 → eo_tides-0.6.0}/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.model.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.model.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-0.4.0 → eo_tides-0.6.0}/eo_tides/model.py

@@ -416,6 +416,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 +445,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.model.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 +736,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.model.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-0.4.0 → eo_tides-0.6.0}/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.model.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.model.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-0.4.0 → eo_tides-0.6.0}/eo_tides.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: eo-tides
-Version: 0.4.0
+Version: 0.6.0
 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
@@ -16,12 +16,11 @@ 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.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: <4.0,>=3.9
+Requires-Python: <4.0,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: colorama>=0.4.3
@@ -31,11 +30,11 @@ Requires-Dist: numpy>=1.26.0
 Requires-Dist: odc-geo>=0.4.7
 Requires-Dist: pandas>=2.2.0
 Requires-Dist: psutil>=5.8.0
-Requires-Dist: pyogrio>=0.7.0
-Requires-Dist: pyproj>=3.6.1
-Requires-Dist: pyTMD==2.2.0
+Requires-Dist: pyogrio>=0.10.0
+Requires-Dist: pyproj>=3.7.0
+Requires-Dist: pyTMD==2.2.1
 Requires-Dist: scikit-learn>=1.4.0
-Requires-Dist: scipy>=1.11.2
+Requires-Dist: scipy>=1.14.1
 Requires-Dist: shapely>=2.0.6
 Requires-Dist: tqdm>=4.55.0
 Requires-Dist: xarray>=2022.3.0
@@ -55,13 +54,13 @@ 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/>
 - 🐍 **PyPI**: <https://pypi.org/project/eo-tides/>
 
-> [!CAUTION]
-> This package is a work in progress, and not currently ready for operational use.
+<br>
 
 `eo-tides` provides powerful parallelized tools for integrating satellite Earth observation data with tide modelling. 🛠️🌊🛰️
 
@@ -89,6 +88,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.4.0 → eo_tides-0.6.0}/eo_tides.egg-info/requires.txt

@@ -5,11 +5,11 @@ numpy>=1.26.0
 odc-geo>=0.4.7
 pandas>=2.2.0
 psutil>=5.8.0
-pyogrio>=0.7.0
-pyproj>=3.6.1
-pyTMD==2.2.0
+pyogrio>=0.10.0
+pyproj>=3.7.0
+pyTMD==2.2.1
 scikit-learn>=1.4.0
-scipy>=1.11.2
+scipy>=1.14.1
 shapely>=2.0.6
 tqdm>=4.55.0
 xarray>=2022.3.0

{eo_tides-0.4.0 → eo_tides-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "eo-tides"
-version = "0.4.0"
+version = "0.6.0"
 description = "Tide modelling tools for large-scale satellite earth observation analysis"
 authors = [
     { name = "Robbi Bishop-Taylor" },
@@ -28,13 +28,12 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Visualization",
     "Topic :: Scientific/Engineering :: Image Processing",
     "License :: OSI Approved :: Apache Software License",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
 ]
-requires-python = ">=3.9,<4.0"
+requires-python = ">=3.10,<4.0"
 dependencies = [
     "colorama>=0.4.3",
     "geopandas>=0.10.0",
@@ -43,11 +42,11 @@ dependencies = [
     "odc-geo>=0.4.7",
     "pandas>=2.2.0",
     "psutil>=5.8.0",
-    "pyogrio>=0.7.0",
-    "pyproj>=3.6.1",
-    "pyTMD==2.2.0",
+    "pyogrio>=0.10.0",
+    "pyproj>=3.7.0",
+    "pyTMD==2.2.1",
     "scikit-learn>=1.4.0",
-    "scipy>=1.11.2",
+    "scipy>=1.14.1",
     "shapely>=2.0.6",
     "tqdm>=4.55.0",
     "xarray>=2022.3.0",
@@ -90,6 +89,9 @@ dev = [
 requires = ["setuptools >= 61.0"]
 build-backend = "setuptools.build_meta"
 
+[tool.setuptools]
+packages = ["eo_tides"]
+
 [tool.mypy]
 files = ["eo_tides"]
 python_version = "3.10"

{eo_tides-0.4.0 → eo_tides-0.6.0}/tests/test_eo.py

@@ -47,6 +47,39 @@ def test_tag_tides(satellite_ds, measured_tides_ds, tidepost_lat, tidepost_lon):
     assert abs(val_stats["Bias"]) < 0.20
 
 
+def test_tag_tides_phases(satellite_ds, measured_tides_ds):
+    # Use tag_tides to model both phases and tide heights
+    tagged_tides_ds = tag_tides(
+        satellite_ds,
+        return_phases=True,
+    )
+
+    # Verify output is an xarray.Dataset
+    assert isinstance(tagged_tides_ds, xr.Dataset)
+
+    # Verify vars are as expected
+    expected_vars = ["tide_height", "tide_phase"]
+    assert set(expected_vars) == set(tagged_tides_ds.data_vars)
+
+    # Verify tide_phase values
+    expected_phases = ["low-flow", "high-flow", "low-ebb", "low-flow", "low-ebb", "low-flow", "high-flow"]
+    assert tagged_tides_ds.tide_phase.values.tolist() == expected_phases
+
+    # Assert tide_model dim has been squeezed out
+    assert "tide_model" not in tagged_tides_ds.dims
+
+    # Model two models at once
+    tagged_tides_ds = tag_tides(
+        satellite_ds,
+        model=["EOT20", "GOT5.5"],
+        return_phases=True,
+    )
+
+    # Assert that output now has a tide_model dimension
+    assert "tide_model" in tagged_tides_ds.dims
+    assert len(tagged_tides_ds["tide_model"]) == 2
+
+
 def test_tag_tides_multiple(satellite_ds):
     # Model multiple models at once
     tagged_tides_da = tag_tides(satellite_ds, model=["EOT20", "HAMTIDE11"], ebb_flow=True)