eo-tides 0.4.0__py3-none-any.whl → 0.6.0__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.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/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/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.dist-info → eo_tides-0.6.0.dist-info}/METADATA

@@ -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.6.0.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=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.4.0.dist-info → eo_tides-0.6.0.dist-info}/WHEEL

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

eo_tides-0.4.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-eo_tides/__init__.py,sha256=pGvVlxMKiYjm_273G-oYcOgVuPra7uEdNZv0oN1i69c,1693
-eo_tides/eo.py,sha256=d4zFs_uhuTekJDDqiX7oIzvS1iP6nEr0rG2Yy4xbsEU,22746
-eo_tides/model.py,sha256=X_nuYkBbzq3cLgJc0dUknlL6w_90O9rz_2BOqX5uxsg,34585
-eo_tides/stats.py,sha256=-nL6Ay6TvA5GSdnglHoLMu5JZf6-YjQKERBGLjAZs34,22993
-eo_tides/utils.py,sha256=9xJ1q-b-TVHg5zFyLy6AT_srrPQDvmFdWJmlGSPaJF0,26563
-eo_tides/validation.py,sha256=KP8WLT5z7KLFjQ9oDla7VJOyLQAK4SVbcz2ySAbsbwI,11882
-eo_tides-0.4.0.dist-info/LICENSE,sha256=owxWsXViCL2J6Ks3XYhot7t4Y93nstmXAT95Zf030Cc,11350
-eo_tides-0.4.0.dist-info/METADATA,sha256=cqO3zJGPj-l5Xzi-cfPtkd7pzUUTt5ENVvCRM16HXFQ,8045
-eo_tides-0.4.0.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
-eo_tides-0.4.0.dist-info/top_level.txt,sha256=lXZDUUM1DlLdKWHRn8zdmtW8Rx-eQOIWVvt0b8VGiyQ,9
-eo_tides-0.4.0.dist-info/RECORD,,