eo-tides 0.0.17__py3-none-any.whl → 0.0.19__py3-none-any.whl

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+eo_tides/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+eo_tides/model.py,sha256=yPUioASD8_Ikm5PDdtK4DzxbzAYLeBw7HZ9v4Ol6MJk,45393
+eo_tides/stats.py,sha256=Lzo46pWUhox3ZUnMLtyLzqZ9FrCNG6nJ6iS5IpqEsy8,158
+eo_tides/utils.py,sha256=l9VXJawQzaRBYaFMsP8VBeaN5VA3rFDdzcvF7Rk04Vc,5620
+eo_tides/validation.py,sha256=kpYGHOeK-YP11c3tHt9l5_8IvOHF1SAJP79PXA7i-Vs,11434
+eo_tides-0.0.19.dist-info/LICENSE,sha256=NYULqbFuDRV6CysPbkR2WZk863YwwHeftBtnsb4cWf8,1077
+eo_tides-0.0.19.dist-info/METADATA,sha256=e1Wl1lCXvOvCp0U6smxXzU2nUEs0QtxSUGoYkmxfBV4,5335
+eo_tides-0.0.19.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+eo_tides-0.0.19.dist-info/top_level.txt,sha256=lXZDUUM1DlLdKWHRn8zdmtW8Rx-eQOIWVvt0b8VGiyQ,9
+eo_tides-0.0.19.dist-info/RECORD,,

eo_tides-0.0.17.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -1,10 +0,0 @@
-eo_tides/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-eo_tides/model.py,sha256=Gx8oUAyo5kzyl7SZhqzS2QlnblXkubr_Wn2NijYzUlc,43811
-eo_tides/stats.py,sha256=Lzo46pWUhox3ZUnMLtyLzqZ9FrCNG6nJ6iS5IpqEsy8,158
-eo_tides/utils.py,sha256=l9VXJawQzaRBYaFMsP8VBeaN5VA3rFDdzcvF7Rk04Vc,5620
-eo_tides/validation.py,sha256=kpYGHOeK-YP11c3tHt9l5_8IvOHF1SAJP79PXA7i-Vs,11434
-eo_tides-0.0.17.dist-info/LICENSE,sha256=NYULqbFuDRV6CysPbkR2WZk863YwwHeftBtnsb4cWf8,1077
-eo_tides-0.0.17.dist-info/METADATA,sha256=G8PxvP4subHP1pg6uZkAYGfmItfsjWepEWs32q9ra9w,3593
-eo_tides-0.0.17.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
-eo_tides-0.0.17.dist-info/top_level.txt,sha256=lXZDUUM1DlLdKWHRn8zdmtW8Rx-eQOIWVvt0b8VGiyQ,9
-eo_tides-0.0.17.dist-info/RECORD,,