eo-tides 0.0.17__tar.gz → 0.0.19__tar.gz

eo_tides-0.0.19/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.1
+Name: eo-tides
+Version: 0.0.19
+Summary: Tide modelling tools for large-scale satellite earth observation analysis
+Author-email: Robbi Bishop-Taylor <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: python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: geopandas>=1.0.0
+Requires-Dist: numpy
+Requires-Dist: odc-geo[xr]
+Requires-Dist: pandas
+Requires-Dist: pyproj
+Requires-Dist: pyTMD==2.1.6
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Requires-Dist: shapely
+Requires-Dist: tqdm
+Provides-Extra: notebooks
+Requires-Dist: odc-stac; extra == "notebooks"
+Requires-Dist: pystac-client; extra == "notebooks"
+Requires-Dist: folium; extra == "notebooks"
+Requires-Dist: matplotlib; extra == "notebooks"
+
+# `eo-tides:` Tide modelling tools for large-scale satellite earth observation analysis
+
+[![Release](https://img.shields.io/github/v/release/GeoscienceAustralia/eo-tides)](https://pypi.org/project/eo-tides/)
+[![Build status](https://img.shields.io/github/actions/workflow/status/GeoscienceAustralia/eo-tides/main.yml?branch=main)](https://github.com/GeoscienceAustralia/eo-tides/actions/workflows/main.yml?query=branch%3Amain)
+[![codecov](https://codecov.io/gh/GeoscienceAustralia/eo-tides/branch/main/graph/badge.svg)](https://codecov.io/gh/GeoscienceAustralia/eo-tides)
+[![Commit activity](https://img.shields.io/github/commit-activity/m/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/commit-activity/m/GeoscienceAustralia/eo-tides)
+[![License](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)
+
+- **Github repository**: <https://github.com/GeoscienceAustralia/eo-tides/>
+- **Documentation** <https://GeoscienceAustralia.github.io/eo-tides/>
+
+> [!CAUTION]
+> This package is a work in progress, and not currently ready for operational use.
+
+The `eo-tides` package provides powerful, parallelized tools for seamlessly integrating satellite Earth observation data with tide modelling.
+
+`eo-tides` combines advanced tide modelling functionality from the [`pyTMD`](https://pytmd.readthedocs.io/en/latest/) package and integrates it with [`pandas`](https://pandas.pydata.org/docs/index.html), [`xarray`](https://docs.xarray.dev/en/stable/) and [`odc-geo`](https://odc-geo.readthedocs.io/en/latest/), providing a suite of flexible tools for efficient analysis of coastal and ocean earth observation data – from regional, continental, to global scale.
+
+These tools can be applied to petabytes of freely available satellite data (e.g. from [Digital Earth Australia](https://knowledge.dea.ga.gov.au/) or [Microsoft Planetary Computer](https://planetarycomputer.microsoft.com/)) loaded via Open Data Cube's [`odc-stac`](https://odc-stac.readthedocs.io/en/latest/) or [`datacube`](https://opendatacube.readthedocs.io/en/latest/) packages, supporting coastal and ocean earth observation analysis for any time period or location globally.
+
+## Highlights
+
+- 🌊 Model tides from multiple global ocean tide models in parallel, and return tide heights in standardised `pandas.DataFrame` format for further analysis
+- 🛰️ "Tag" satellite data with tide height and stage based on the exact moment of image acquisition
+- 🌐 Model tides for every individual satellite pixel, producing three-dimensional "tide height" `xarray`-format datacubes that can be combined with satellite data
+- 🎯 Combine multiple tide models into a single locally-optimised "ensemble" model informed by satellite altimetry and satellite-observed patterns of tidal inundation
+- 📈 Calculate statistics describing local tide dynamics, as well as biases caused by interactions between tidal processes and satellite orbits
+- 🛠️ Validate modelled tides using measured sea levels from coastal tide gauges (e.g. [GESLA Global Extreme Sea Level Analysis](https://gesla.org/))
+
+## Supported tide models
+
+`eo-tides` supports [all ocean tide models supported by `pyTMD`](https://pytmd.readthedocs.io/en/latest/getting_started/Getting-Started.html#model-database). These include:
+
+- [Empirical Ocean Tide model](https://doi.org/10.5194/essd-13-3869-2021) (`EOT20`)
+- [Finite Element Solution tide models](https://doi.org/10.5194/os-2020-96) (`FES2022`, `FES2014`, `FES2012`)
+- [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`)
+
+For instructions on how to set up these models for use in `eo-tides`, refer to [Setting up tide models](https://geoscienceaustralia.github.io/eo-tides/setup/).
+
+## Citing `eo-tides`
+
+To cite `eo-tides` in your work, please use the following citation:
+
+```
+Bishop-Taylor, R., Sagar, S., Phillips, C., & Newey, V. (2024). eo-tides: Tide modelling tools for large-scale satellite earth observation analysis [Computer software]. https://github.com/GeoscienceAustralia/eo-tides
+```

eo_tides-0.0.19/README.md

@@ -0,0 +1,48 @@
+# `eo-tides:` Tide modelling tools for large-scale satellite earth observation analysis
+
+[![Release](https://img.shields.io/github/v/release/GeoscienceAustralia/eo-tides)](https://pypi.org/project/eo-tides/)
+[![Build status](https://img.shields.io/github/actions/workflow/status/GeoscienceAustralia/eo-tides/main.yml?branch=main)](https://github.com/GeoscienceAustralia/eo-tides/actions/workflows/main.yml?query=branch%3Amain)
+[![codecov](https://codecov.io/gh/GeoscienceAustralia/eo-tides/branch/main/graph/badge.svg)](https://codecov.io/gh/GeoscienceAustralia/eo-tides)
+[![Commit activity](https://img.shields.io/github/commit-activity/m/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/commit-activity/m/GeoscienceAustralia/eo-tides)
+[![License](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)
+
+- **Github repository**: <https://github.com/GeoscienceAustralia/eo-tides/>
+- **Documentation** <https://GeoscienceAustralia.github.io/eo-tides/>
+
+> [!CAUTION]
+> This package is a work in progress, and not currently ready for operational use.
+
+The `eo-tides` package provides powerful, parallelized tools for seamlessly integrating satellite Earth observation data with tide modelling.
+
+`eo-tides` combines advanced tide modelling functionality from the [`pyTMD`](https://pytmd.readthedocs.io/en/latest/) package and integrates it with [`pandas`](https://pandas.pydata.org/docs/index.html), [`xarray`](https://docs.xarray.dev/en/stable/) and [`odc-geo`](https://odc-geo.readthedocs.io/en/latest/), providing a suite of flexible tools for efficient analysis of coastal and ocean earth observation data – from regional, continental, to global scale.
+
+These tools can be applied to petabytes of freely available satellite data (e.g. from [Digital Earth Australia](https://knowledge.dea.ga.gov.au/) or [Microsoft Planetary Computer](https://planetarycomputer.microsoft.com/)) loaded via Open Data Cube's [`odc-stac`](https://odc-stac.readthedocs.io/en/latest/) or [`datacube`](https://opendatacube.readthedocs.io/en/latest/) packages, supporting coastal and ocean earth observation analysis for any time period or location globally.
+
+## Highlights
+
+- 🌊 Model tides from multiple global ocean tide models in parallel, and return tide heights in standardised `pandas.DataFrame` format for further analysis
+- 🛰️ "Tag" satellite data with tide height and stage based on the exact moment of image acquisition
+- 🌐 Model tides for every individual satellite pixel, producing three-dimensional "tide height" `xarray`-format datacubes that can be combined with satellite data
+- 🎯 Combine multiple tide models into a single locally-optimised "ensemble" model informed by satellite altimetry and satellite-observed patterns of tidal inundation
+- 📈 Calculate statistics describing local tide dynamics, as well as biases caused by interactions between tidal processes and satellite orbits
+- 🛠️ Validate modelled tides using measured sea levels from coastal tide gauges (e.g. [GESLA Global Extreme Sea Level Analysis](https://gesla.org/))
+
+## Supported tide models
+
+`eo-tides` supports [all ocean tide models supported by `pyTMD`](https://pytmd.readthedocs.io/en/latest/getting_started/Getting-Started.html#model-database). These include:
+
+- [Empirical Ocean Tide model](https://doi.org/10.5194/essd-13-3869-2021) (`EOT20`)
+- [Finite Element Solution tide models](https://doi.org/10.5194/os-2020-96) (`FES2022`, `FES2014`, `FES2012`)
+- [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`)
+
+For instructions on how to set up these models for use in `eo-tides`, refer to [Setting up tide models](https://geoscienceaustralia.github.io/eo-tides/setup/).
+
+## Citing `eo-tides`
+
+To cite `eo-tides` in your work, please use the following citation:
+
+```
+Bishop-Taylor, R., Sagar, S., Phillips, C., & Newey, V. (2024). eo-tides: Tide modelling tools for large-scale satellite earth observation analysis [Computer software]. https://github.com/GeoscienceAustralia/eo-tides
+```

{eo_tides-0.0.17 → eo_tides-0.0.19}/eo_tides/model.py

@@ -9,11 +9,73 @@ import odc.geo.xr
 import pandas as pd
 import pyproj
 import pyTMD
+from pyTMD.io.model import load_database, model
 from tqdm import tqdm
 
 from eo_tides.utils import idw
 
 
+def available_models(directory=None, show_supported=True):
+    """
+    Prints a list of all tide models available for tide
+    modelling using `eo-tides`.
+
+    This function scans the specified tide model directory
+    for tide models supported by the `pyTMD` package, and
+    prints a list of models that are available in the
+    directory as well as the full list of supported models.
+
+    For instructions on setting up tide models, see:
+    <https://geoscienceaustralia.github.io/eo-tides/setup/>
+
+    Parameters
+    ----------
+    directory : str
+        Path to the directory containing tide model files.
+
+    Returns
+    -------
+    available_m : list
+        A list of all available tide models within
+        `directory`.
+    """
+    # TODO: Pull directory code into re-usable function
+
+    # Set tide modelling files directory. If no custom path is provided,
+    # first try global environmental var, then "/var/share/tide_models"
+    if directory is None:
+        if "EO_TIDES_TIDE_MODELS" in os.environ:
+            directory = os.environ["EO_TIDES_TIDE_MODELS"]
+        else:
+            directory = "/var/share/tide_models"
+
+    # Verify path exists
+    directory = pathlib.Path(directory).expanduser()
+    if not directory.exists():
+        raise FileNotFoundError("Invalid tide directory")
+
+    # Get full list of supported models from the database
+    supported_models = load_database()["elevation"].keys()
+
+    # Print list of supported models, marking available and
+    # unavailable models and appending available to list
+    print(f"Tide models available in `{directory}`:")
+    available_m = []
+    for m in supported_models:
+        try:
+            model(directory=directory).elevation(m=m)
+            # Mark available models with a green tick
+            print(f" ✅ {m}")
+            available_m.append(m)
+        except:
+            if show_supported:
+                # Mark unavailable models with a red cross
+                print(f" ❌ {m}")
+
+    # Return list of available models
+    return available_m
+
+
 def _model_tides(
     model,
     x,
@@ -207,16 +269,16 @@ def _model_tides(
         "x": np.repeat(x, time_repeat),
         "y": np.repeat(y, time_repeat),
         "tide_model": model,
-        "tide_m": tide,
+        "tide_height": tide,
     }).set_index(["time", "x", "y"])
 
     # Optionally convert outputs to integer units (can save memory)
     if output_units == "m":
-        tide_df["tide_m"] = tide_df.tide_m.astype(np.float32)
+        tide_df["tide_height"] = tide_df.tide_height.astype(np.float32)
     elif output_units == "cm":
-        tide_df["tide_m"] = (tide_df.tide_m * 100).astype(np.int16)
+        tide_df["tide_height"] = (tide_df.tide_height * 100).astype(np.int16)
     elif output_units == "mm":
-        tide_df["tide_m"] = (tide_df.tide_m * 1000).astype(np.int16)
+        tide_df["tide_height"] = (tide_df.tide_height * 1000).astype(np.int16)
 
     return tide_df
 
@@ -261,7 +323,7 @@ def _ensemble_model(
         to ensure that interpolations are performed in the correct CRS.
     tide_df : pandas.DataFrame
         DataFrame containing tide model predictions with columns
-        `["time", "x", "y", "tide_m", "tide_model"]`.
+        `["time", "x", "y", "tide_height", "tide_model"]`.
     ensemble_models : list
         A list of models to include in the ensemble modelling process.
         All values must exist as columns with the prefix "rank_" in
@@ -298,7 +360,7 @@ def _ensemble_model(
     pandas.DataFrame
         DataFrame containing the ensemble model predictions, matching
         the format of the input `tide_df` (e.g. columns `["time", "x",
-        "y", "tide_m", "tide_model"]`. By default the 'tide_model'
+        "y", "tide_height", "tide_model"]`. By default the 'tide_model'
         column will be labeled "ensemble" for the combined model
         predictions (but if a custom dictionary of ensemble functions is
         provided via `ensemble_func`, each ensemble will be named using
@@ -362,7 +424,7 @@ def _ensemble_model(
             # Add temp columns containing weightings and weighted values
             .assign(
                 weights=ensemble_f,  # use custom func to compute weights
-                weighted=lambda i: i.tide_m * i.weights,
+                weighted=lambda i: i.tide_height * i.weights,
             )
             # Groupby is specified in a weird order here as this seems
             # to be the easiest way to preserve correct index sorting
@@ -374,7 +436,7 @@ def _ensemble_model(
             # Calculate weighted mean and convert back to dataframe
             grouped.weighted.sum()
             .div(grouped.weights.sum())
-            .to_frame("tide_m")
+            .to_frame("tide_height")
             # Label ensemble model and ensure indexes are in expected order
             .assign(tide_model=ensemble_n)
             .reorder_levels(["time", "x", "y"], axis=0)
@@ -405,47 +467,25 @@ def model_tides(
     ensemble_models=None,
     **ensemble_kwargs,
 ):
-    """Compute tides at multiple points and times using tidal harmonics.
+    """
+    Compute tide heights from multiple tide models and for
+    multiple coordinates and/or timesteps.
 
-    This function supports all tidal models supported by `pyTMD`,
-    including FES Finite Element Solution models, TPXO TOPEX/POSEIDON
-    models, EOT Empirical Ocean Tide models, GOT Global Ocean Tide
-    models, and HAMTIDE Hamburg direct data Assimilation Methods for
-    Tides models.
+    This function is parallelised to improve performance, and
+    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`)
 
     This function requires access to tide model data files.
     These should be placed in a folder with subfolders matching
-    the formats specified by `pyTMD`:
+    the structure required by `pyTMD`. For more details:
+    <https://geoscienceaustralia.github.io/eo-tides/setup/>
     <https://pytmd.readthedocs.io/en/latest/getting_started/Getting-Started.html#directories>
 
-    For FES2014 (<https://www.aviso.altimetry.fr/es/data/products/auxiliary-products/global-tide-fes/description-fes2014.html>):
-
-    - `{directory}/fes2014/ocean_tide/`
-
-    For FES2022 (<https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html>):
-
-    - `{directory}/fes2022b/ocean_tide/`
-
-    For TPXO8-atlas (<https://www.tpxo.net/tpxo-products-and-registration>):
-
-    - `{directory}/tpxo8_atlas/`
-
-    For TPXO9-atlas-v5 (<https://www.tpxo.net/tpxo-products-and-registration>):
-
-    - `{directory}/TPXO9_atlas_v5/`
-
-    For EOT20 (<https://www.seanoe.org/data/00683/79489/>):
-
-    - `{directory}/EOT20/ocean_tides/`
-
-    For GOT4.10c (<https://earth.gsfc.nasa.gov/geo/data/ocean-tide-models>):
-
-    - `{directory}/GOT4.10c/grids_oceantide_netcdf/`
-
-    For HAMTIDE (<https://www.cen.uni-hamburg.de/en/icdc/data/ocean/hamtide.html>):
-
-    - `{directory}/hamtide/`
-
     This function is a modification of the `pyTMD` package's
     `compute_tide_corrections` function. For more info:
     <https://pytmd.readthedocs.io/en/stable/user_guide/compute_tide_corrections.html>
@@ -514,9 +554,10 @@ def model_tides(
         want to model tides for a specific list of timesteps across
         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 different timestep for each
-        x and y coordinate point. In this mode, the number of x and
+        - "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
         y points must equal the number of timesteps provided in "time".
+
     parallel : boolean, optional
         Whether to parallelise tide modelling using `concurrent.futures`.
         If multiple tide models are requested, these will be run in
@@ -538,7 +579,7 @@ def model_tides(
         for millimetres.
     output_format : str, optional
         Whether to return the output dataframe in long format (with
-        results stacked vertically along "tide_model" and "tide_m"
+        results stacked vertically along "tide_model" and "tide_height"
         columns), or wide format (with a column for each tide model).
         Defaults to "long".
     ensemble_models : list, optional
@@ -734,7 +775,7 @@ def model_tides(
     if output_format == "wide":
         # Pivot into wide format with each time model as a column
         print("Converting to a wide format dataframe")
-        tide_df = tide_df.pivot(columns="tide_model", values="tide_m")
+        tide_df = tide_df.pivot(columns="tide_model", values="tide_height")
 
         # If in 'one-to-one' mode, reindex using our input time/x/y
         # values to ensure the output is sorted the same as our inputs
@@ -812,7 +853,7 @@ def _pixel_tides_resample(
         how=ds.odc.geobox,
         chunks=dask_chunks,
         resampling=resample_method,
-    ).rename("tide_m")
+    ).rename("tide_height")
 
     # Optionally process and load into memory with Dask
     if dask_compute:
@@ -1064,7 +1105,7 @@ def pixel_tides(
         .set_index("tide_model", append=True)
         # Convert to xarray and select our tide modelling xr.DataArray
         .to_xarray()
-        .tide_m
+        .tide_height
         # Re-index and transpose into our input coordinates and dim order
         .reindex_like(rescaled_ds)
         .transpose("tide_model", "time", y_dim, x_dim)

eo_tides-0.0.19/eo_tides.egg-info/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.1
+Name: eo-tides
+Version: 0.0.19
+Summary: Tide modelling tools for large-scale satellite earth observation analysis
+Author-email: Robbi Bishop-Taylor <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: python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: geopandas>=1.0.0
+Requires-Dist: numpy
+Requires-Dist: odc-geo[xr]
+Requires-Dist: pandas
+Requires-Dist: pyproj
+Requires-Dist: pyTMD==2.1.6
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Requires-Dist: shapely
+Requires-Dist: tqdm
+Provides-Extra: notebooks
+Requires-Dist: odc-stac; extra == "notebooks"
+Requires-Dist: pystac-client; extra == "notebooks"
+Requires-Dist: folium; extra == "notebooks"
+Requires-Dist: matplotlib; extra == "notebooks"
+
+# `eo-tides:` Tide modelling tools for large-scale satellite earth observation analysis
+
+[![Release](https://img.shields.io/github/v/release/GeoscienceAustralia/eo-tides)](https://pypi.org/project/eo-tides/)
+[![Build status](https://img.shields.io/github/actions/workflow/status/GeoscienceAustralia/eo-tides/main.yml?branch=main)](https://github.com/GeoscienceAustralia/eo-tides/actions/workflows/main.yml?query=branch%3Amain)
+[![codecov](https://codecov.io/gh/GeoscienceAustralia/eo-tides/branch/main/graph/badge.svg)](https://codecov.io/gh/GeoscienceAustralia/eo-tides)
+[![Commit activity](https://img.shields.io/github/commit-activity/m/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/commit-activity/m/GeoscienceAustralia/eo-tides)
+[![License](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)
+
+- **Github repository**: <https://github.com/GeoscienceAustralia/eo-tides/>
+- **Documentation** <https://GeoscienceAustralia.github.io/eo-tides/>
+
+> [!CAUTION]
+> This package is a work in progress, and not currently ready for operational use.
+
+The `eo-tides` package provides powerful, parallelized tools for seamlessly integrating satellite Earth observation data with tide modelling.
+
+`eo-tides` combines advanced tide modelling functionality from the [`pyTMD`](https://pytmd.readthedocs.io/en/latest/) package and integrates it with [`pandas`](https://pandas.pydata.org/docs/index.html), [`xarray`](https://docs.xarray.dev/en/stable/) and [`odc-geo`](https://odc-geo.readthedocs.io/en/latest/), providing a suite of flexible tools for efficient analysis of coastal and ocean earth observation data – from regional, continental, to global scale.
+
+These tools can be applied to petabytes of freely available satellite data (e.g. from [Digital Earth Australia](https://knowledge.dea.ga.gov.au/) or [Microsoft Planetary Computer](https://planetarycomputer.microsoft.com/)) loaded via Open Data Cube's [`odc-stac`](https://odc-stac.readthedocs.io/en/latest/) or [`datacube`](https://opendatacube.readthedocs.io/en/latest/) packages, supporting coastal and ocean earth observation analysis for any time period or location globally.
+
+## Highlights
+
+- 🌊 Model tides from multiple global ocean tide models in parallel, and return tide heights in standardised `pandas.DataFrame` format for further analysis
+- 🛰️ "Tag" satellite data with tide height and stage based on the exact moment of image acquisition
+- 🌐 Model tides for every individual satellite pixel, producing three-dimensional "tide height" `xarray`-format datacubes that can be combined with satellite data
+- 🎯 Combine multiple tide models into a single locally-optimised "ensemble" model informed by satellite altimetry and satellite-observed patterns of tidal inundation
+- 📈 Calculate statistics describing local tide dynamics, as well as biases caused by interactions between tidal processes and satellite orbits
+- 🛠️ Validate modelled tides using measured sea levels from coastal tide gauges (e.g. [GESLA Global Extreme Sea Level Analysis](https://gesla.org/))
+
+## Supported tide models
+
+`eo-tides` supports [all ocean tide models supported by `pyTMD`](https://pytmd.readthedocs.io/en/latest/getting_started/Getting-Started.html#model-database). These include:
+
+- [Empirical Ocean Tide model](https://doi.org/10.5194/essd-13-3869-2021) (`EOT20`)
+- [Finite Element Solution tide models](https://doi.org/10.5194/os-2020-96) (`FES2022`, `FES2014`, `FES2012`)
+- [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`)
+
+For instructions on how to set up these models for use in `eo-tides`, refer to [Setting up tide models](https://geoscienceaustralia.github.io/eo-tides/setup/).
+
+## Citing `eo-tides`
+
+To cite `eo-tides` in your work, please use the following citation:
+
+```
+Bishop-Taylor, R., Sagar, S., Phillips, C., & Newey, V. (2024). eo-tides: Tide modelling tools for large-scale satellite earth observation analysis [Computer software]. https://github.com/GeoscienceAustralia/eo-tides
+```

{eo_tides-0.0.17 → eo_tides-0.0.19}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "eo-tides"
-version = "0.0.17"
+version = "0.0.19"
 description = "Tide modelling tools for large-scale satellite earth observation analysis"
 authors = [{ name = "Robbi Bishop-Taylor", email = "Robbi.BishopTaylor@ga.gov.au" }]
 readme = "README.md"

{eo_tides-0.0.17 → eo_tides-0.0.19}/tests/test_model.py

@@ -6,7 +6,7 @@ import pystac_client
 import pytest
 import xarray as xr
 
-from eo_tides.model import model_tides, pixel_tides
+from eo_tides.model import available_models, model_tides, pixel_tides
 from eo_tides.validation import eval_metrics
 
 GAUGE_X = 122.2183
@@ -34,7 +34,7 @@ def measured_tides_ds():
 
     # Update index and column names
     measured_tides_df.index.name = "time"
-    measured_tides_df.columns = ["tide_m"]
+    measured_tides_df.columns = ["tide_height"]
 
     # Apply station AHD offset
     measured_tides_df += ahd_offset
@@ -90,6 +90,12 @@ def satellite_ds(request):
     return ds
 
 
+# Test available tide models
+def test_available_models():
+    available_m = available_models()
+    assert available_m == ["FES2014", "HAMTIDE11"]
+
+
 # Run test for multiple input coordinates, CRSs and interpolation methods
 @pytest.mark.parametrize(
     "x, y, crs, method",
@@ -115,12 +121,12 @@ def test_model_tides(measured_tides_ds, x, y, crs, method):
     )
 
     # Compare measured and modelled tides
-    val_stats = eval_metrics(x=measured_tides_ds.tide_m, y=modelled_tides_df.tide_m)
+    val_stats = eval_metrics(x=measured_tides_ds.tide_height, y=modelled_tides_df.tide_height)
 
     # Test that modelled tides contain correct headings and have same
     # number of timesteps
     assert modelled_tides_df.index.names == ["time", "x", "y"]
-    assert modelled_tides_df.columns.tolist() == ["tide_model", "tide_m"]
+    assert modelled_tides_df.columns.tolist() == ["tide_model", "tide_height"]
     assert len(modelled_tides_df.index) == len(measured_tides_ds.time)
 
     # Test that modelled tides meet expected accuracy
@@ -159,7 +165,7 @@ def test_model_tides_multiplemodels(measured_tides_ds, models, output_format):
     if output_format == "long":
         # Verify output has correct columns
         assert modelled_tides_df.index.names == ["time", "x", "y"]
-        assert modelled_tides_df.columns.tolist() == ["tide_model", "tide_m"]
+        assert modelled_tides_df.columns.tolist() == ["tide_model", "tide_height"]
 
         # Verify tide model column contains correct values
         assert modelled_tides_df.tide_model.unique().tolist() == models
@@ -193,11 +199,11 @@ def test_model_tides_units(measured_tides_ds, units, expected_range, expected_dt
     )
 
     # Calculate tide range
-    tide_range = modelled_tides_df.tide_m.max() - modelled_tides_df.tide_m.min()
+    tide_range = modelled_tides_df.tide_height.max() - modelled_tides_df.tide_height.min()
 
     # Verify tide range and dtypes are as expected for unit
     assert np.isclose(tide_range, expected_range, rtol=0.01)
-    assert modelled_tides_df.tide_m.dtype == expected_dtype
+    assert modelled_tides_df.tide_height.dtype == expected_dtype
 
 
 # Run test for each combination of mode, output format, and one or
@@ -290,7 +296,7 @@ def test_model_tides_ensemble():
     )
 
     assert modelled_tides_df.index.names == ["time", "x", "y"]
-    assert modelled_tides_df.columns.tolist() == ["tide_model", "tide_m"]
+    assert modelled_tides_df.columns.tolist() == ["tide_model", "tide_height"]
     assert all(modelled_tides_df.tide_model == "ensemble")
 
     # Default, ensemble + other models requested
@@ -304,10 +310,10 @@ def test_model_tides_ensemble():
     )
 
     assert modelled_tides_df.index.names == ["time", "x", "y"]
-    assert modelled_tides_df.columns.tolist() == ["tide_model", "tide_m"]
+    assert modelled_tides_df.columns.tolist() == ["tide_model", "tide_height"]
     assert set(modelled_tides_df.tide_model) == set(models)
     assert np.allclose(
-        modelled_tides_df.tide_m,
+        modelled_tides_df.tide_height,
         [
             -2.831,
             -1.897,
@@ -336,7 +342,7 @@ def test_model_tides_ensemble():
     )
 
     assert modelled_tides_df.index.names == ["time", "x", "y"]
-    assert modelled_tides_df.columns.tolist() == ["tide_model", "tide_m"]
+    assert modelled_tides_df.columns.tolist() == ["tide_model", "tide_height"]
     assert set(modelled_tides_df.tide_model) == set(models)
 
     # Wide mode, default
@@ -487,7 +493,7 @@ def test_pixel_tides(satellite_ds, measured_tides_ds, resolution):
         )
 
     # Calculate accuracy stats
-    gauge_stats = eval_metrics(x=measured_tides_ds.tide_m, y=modelled_tides_gauge)
+    gauge_stats = eval_metrics(x=measured_tides_ds.tide_height, y=modelled_tides_gauge)
 
     # Assert pixel_tide outputs are accurate
     assert gauge_stats["Correlation"] > 0.99

eo_tides-0.0.17/PKG-INFO

@@ -1,55 +0,0 @@
-Metadata-Version: 2.1
-Name: eo-tides
-Version: 0.0.17
-Summary: Tide modelling tools for large-scale satellite earth observation analysis
-Author-email: Robbi Bishop-Taylor <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: python
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: geopandas>=1.0.0
-Requires-Dist: numpy
-Requires-Dist: odc-geo[xr]
-Requires-Dist: pandas
-Requires-Dist: pyproj
-Requires-Dist: pyTMD==2.1.6
-Requires-Dist: scikit-learn
-Requires-Dist: scipy
-Requires-Dist: shapely
-Requires-Dist: tqdm
-Provides-Extra: notebooks
-Requires-Dist: odc-stac; extra == "notebooks"
-Requires-Dist: pystac-client; extra == "notebooks"
-Requires-Dist: folium; extra == "notebooks"
-Requires-Dist: matplotlib; extra == "notebooks"
-
-# `eo-tides:` Tide modelling tools for large-scale satellite earth observation analysis
-
-[![Release](https://img.shields.io/github/v/release/GeoscienceAustralia/eo-tides)](https://pypi.org/project/eo-tides/)
-[![Build status](https://img.shields.io/github/actions/workflow/status/GeoscienceAustralia/eo-tides/main.yml?branch=main)](https://github.com/GeoscienceAustralia/eo-tides/actions/workflows/main.yml?query=branch%3Amain)
-[![codecov](https://codecov.io/gh/GeoscienceAustralia/eo-tides/branch/main/graph/badge.svg)](https://codecov.io/gh/GeoscienceAustralia/eo-tides)
-[![Commit activity](https://img.shields.io/github/commit-activity/m/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/commit-activity/m/GeoscienceAustralia/eo-tides)
-[![License](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)
-
-- **Github repository**: <https://github.com/GeoscienceAustralia/eo-tides/>
-- **Documentation** <https://GeoscienceAustralia.github.io/eo-tides/>
-
-> [!CAUTION]
-> This package is a work in progress, and not currently ready for operational use.
-
-The `eo-tides` package provides tools for analysing coastal and ocean satellite earth observation data using information about ocean tides.
-
-`eo-tides` combines advanced tide modelling functionality from the [`pyTMD`](https://pytmd.readthedocs.io/en/latest/) package and integrates it with `pandas`, `xarray` and `odc-geo` to provide a powerful set of tools for integrating satellite imagery with tide data.
-
-Some key functionality includes the ability to:
-
-- Model tides from multiple global ocean tide models (e.g. FES2022, FES2014, TPXO9, EOT20 and many more) in parallel, and return tide heights in standardised `pandas.DataFrame` format for further analysis
-- "Tag" satellite data timeseries with tide data based on the exact moment of each satellite acquisition
-- Model tides for every individual satellite pixel, producing three-dimensional "tide height" `xarray`-format datacubes that can be combined with satellite data
-- Calculate statistics describing local tide dynamics, as well as biases caused by interactions between tidal processes and satellite orbits
-- Validate modelled tides using measured sea levels from coastal tide gauges
-
-These tools can be applied directly to petabytes of freely available satellite data (e.g. from Digital Earth Australia or Microsoft Planetary Computer) loaded via Open Data Cube's `odc-stac` or `datacube` packages, supporting coastal and ocean earth observation analysis for any time period or location globally.

eo_tides-0.0.17/README.md

@@ -1,27 +0,0 @@
-# `eo-tides:` Tide modelling tools for large-scale satellite earth observation analysis
-
-[![Release](https://img.shields.io/github/v/release/GeoscienceAustralia/eo-tides)](https://pypi.org/project/eo-tides/)
-[![Build status](https://img.shields.io/github/actions/workflow/status/GeoscienceAustralia/eo-tides/main.yml?branch=main)](https://github.com/GeoscienceAustralia/eo-tides/actions/workflows/main.yml?query=branch%3Amain)
-[![codecov](https://codecov.io/gh/GeoscienceAustralia/eo-tides/branch/main/graph/badge.svg)](https://codecov.io/gh/GeoscienceAustralia/eo-tides)
-[![Commit activity](https://img.shields.io/github/commit-activity/m/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/commit-activity/m/GeoscienceAustralia/eo-tides)
-[![License](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)
-
-- **Github repository**: <https://github.com/GeoscienceAustralia/eo-tides/>
-- **Documentation** <https://GeoscienceAustralia.github.io/eo-tides/>
-
-> [!CAUTION]
-> This package is a work in progress, and not currently ready for operational use.
-
-The `eo-tides` package provides tools for analysing coastal and ocean satellite earth observation data using information about ocean tides.
-
-`eo-tides` combines advanced tide modelling functionality from the [`pyTMD`](https://pytmd.readthedocs.io/en/latest/) package and integrates it with `pandas`, `xarray` and `odc-geo` to provide a powerful set of tools for integrating satellite imagery with tide data.
-
-Some key functionality includes the ability to:
-
-- Model tides from multiple global ocean tide models (e.g. FES2022, FES2014, TPXO9, EOT20 and many more) in parallel, and return tide heights in standardised `pandas.DataFrame` format for further analysis
-- "Tag" satellite data timeseries with tide data based on the exact moment of each satellite acquisition
-- Model tides for every individual satellite pixel, producing three-dimensional "tide height" `xarray`-format datacubes that can be combined with satellite data
-- Calculate statistics describing local tide dynamics, as well as biases caused by interactions between tidal processes and satellite orbits
-- Validate modelled tides using measured sea levels from coastal tide gauges
-
-These tools can be applied directly to petabytes of freely available satellite data (e.g. from Digital Earth Australia or Microsoft Planetary Computer) loaded via Open Data Cube's `odc-stac` or `datacube` packages, supporting coastal and ocean earth observation analysis for any time period or location globally.

eo_tides-0.0.17/eo_tides.egg-info/PKG-INFO

@@ -1,55 +0,0 @@
-Metadata-Version: 2.1
-Name: eo-tides
-Version: 0.0.17
-Summary: Tide modelling tools for large-scale satellite earth observation analysis
-Author-email: Robbi Bishop-Taylor <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: python
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: geopandas>=1.0.0
-Requires-Dist: numpy
-Requires-Dist: odc-geo[xr]
-Requires-Dist: pandas
-Requires-Dist: pyproj
-Requires-Dist: pyTMD==2.1.6
-Requires-Dist: scikit-learn
-Requires-Dist: scipy
-Requires-Dist: shapely
-Requires-Dist: tqdm
-Provides-Extra: notebooks
-Requires-Dist: odc-stac; extra == "notebooks"
-Requires-Dist: pystac-client; extra == "notebooks"
-Requires-Dist: folium; extra == "notebooks"
-Requires-Dist: matplotlib; extra == "notebooks"
-
-# `eo-tides:` Tide modelling tools for large-scale satellite earth observation analysis
-
-[![Release](https://img.shields.io/github/v/release/GeoscienceAustralia/eo-tides)](https://pypi.org/project/eo-tides/)
-[![Build status](https://img.shields.io/github/actions/workflow/status/GeoscienceAustralia/eo-tides/main.yml?branch=main)](https://github.com/GeoscienceAustralia/eo-tides/actions/workflows/main.yml?query=branch%3Amain)
-[![codecov](https://codecov.io/gh/GeoscienceAustralia/eo-tides/branch/main/graph/badge.svg)](https://codecov.io/gh/GeoscienceAustralia/eo-tides)
-[![Commit activity](https://img.shields.io/github/commit-activity/m/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/commit-activity/m/GeoscienceAustralia/eo-tides)
-[![License](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)
-
-- **Github repository**: <https://github.com/GeoscienceAustralia/eo-tides/>
-- **Documentation** <https://GeoscienceAustralia.github.io/eo-tides/>
-
-> [!CAUTION]
-> This package is a work in progress, and not currently ready for operational use.
-
-The `eo-tides` package provides tools for analysing coastal and ocean satellite earth observation data using information about ocean tides.
-
-`eo-tides` combines advanced tide modelling functionality from the [`pyTMD`](https://pytmd.readthedocs.io/en/latest/) package and integrates it with `pandas`, `xarray` and `odc-geo` to provide a powerful set of tools for integrating satellite imagery with tide data.
-
-Some key functionality includes the ability to:
-
-- Model tides from multiple global ocean tide models (e.g. FES2022, FES2014, TPXO9, EOT20 and many more) in parallel, and return tide heights in standardised `pandas.DataFrame` format for further analysis
-- "Tag" satellite data timeseries with tide data based on the exact moment of each satellite acquisition
-- Model tides for every individual satellite pixel, producing three-dimensional "tide height" `xarray`-format datacubes that can be combined with satellite data
-- Calculate statistics describing local tide dynamics, as well as biases caused by interactions between tidal processes and satellite orbits
-- Validate modelled tides using measured sea levels from coastal tide gauges
-
-These tools can be applied directly to petabytes of freely available satellite data (e.g. from Digital Earth Australia or Microsoft Planetary Computer) loaded via Open Data Cube's `odc-stac` or `datacube` packages, supporting coastal and ocean earth observation analysis for any time period or location globally.