eo-tides 0.0.18__py3-none-any.whl → 0.0.20__py3-none-any.whl

eo_tides/model.py

@@ -1,5 +1,6 @@
 import os
 import pathlib
+import warnings
 from concurrent.futures import ProcessPoolExecutor
 from functools import partial
 
@@ -9,11 +10,111 @@ 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 _set_directory(directory):
+    """
+    Set tide modelling files directory. If no custom
+    path is provided, try global environmental variable
+    instead.
+    """
+    if directory is None:
+        if "EO_TIDES_TIDE_MODELS" in os.environ:
+            directory = os.environ["EO_TIDES_TIDE_MODELS"]
+        else:
+            raise Exception(
+                "No tide model directory provided via `directory`, and/or no "
+                "`EO_TIDES_TIDE_MODELS` environment variable found. "
+                "Please provide a valid path to your tide model directory."
+            )
+
+    # Verify path exists
+    directory = pathlib.Path(directory).expanduser()
+    if not directory.exists():
+        raise FileNotFoundError(f"No valid tide model directory found at path `{directory}`")
+    else:
+        return directory
+
+
+def list_models(directory=None, show_available=True, show_supported=True, raise_error=False):
+    """
+    List all tide models available for tide modelling, and
+    all models supported by `eo-tides` and `pyTMD`.
+
+    This function scans the specified tide model directory
+    and returns a list of models that are available in the
+    directory as well as the full list of all supported models.
+
+    For instructions on setting up tide models, see:
+    <https://geoscienceaustralia.github.io/eo-tides/setup/>
+
+    Parameters
+    ----------
+    directory : string, optional
+        The directory containing tide model data files. If no path is
+        provided, this will default to the environment variable
+        `EO_TIDES_TIDE_MODELS` if set, or raise an error if not.
+        Tide modelling files should be stored in sub-folders for each
+        model that match the structure required by `pyTMD`
+        (<https://geoscienceaustralia.github.io/eo-tides/setup/>).
+    show_available : bool, optional
+        Whether to print a list of locally available models.
+    show_supported : bool, optional
+        Whether to print a list of all supported models, in
+        addition to models available locally.
+
+    Returns
+    -------
+    available_models : list
+        A list of alltide models available within `directory`.
+    supported_models : list
+        A list of all tide models supported by `eo-tides`.
+    """
+    # Set tide modelling files directory. If no custom path is
+    # provided, try global environment variable.
+    directory = _set_directory(directory)
+
+    # Get full list of supported models from pyTMD database
+    supported_models = list(load_database()["elevation"].keys())
+
+    # Print list of supported models, marking available and
+    # unavailable models and appending available to list
+    if show_available or show_supported:
+        print(f"Tide models available in `{directory}`:")
+    available_models = []
+    for m in supported_models:
+        try:
+            model(directory=directory).elevation(m=m)
+            if show_available:
+                # Mark available models with a green tick
+                print(f" ✅ {m}")
+            available_models.append(m)
+        except:
+            if show_supported:
+                # Mark unavailable models with a red cross
+                print(f" ❌ {m}")
+
+    # Raise error or warning if no models are available
+    if not available_models:
+        warning_text = (
+            f"No valid tide models are available in `{directory}`. "
+            "Verify that you have provided the correct `directory` path, "
+            "or set the `EO_TIDES_TIDE_MODELS` environment variable "
+            "to point to the location of your tide model directory."
+        )
+        if raise_error:
+            raise Exception(warning_text)
+        else:
+            warnings.warn(warning_text, UserWarning)
+
+    # Return list of available and supported models
+    return available_models, supported_models
+
+
 def _model_tides(
     model,
     x,
@@ -32,34 +133,7 @@ def _model_tides(
     extraction of tide modelling constituents and tide modelling using
     `pyTMD`.
     """
-    # import pyTMD.eop
-    # import pyTMD.io
-    # import pyTMD.io.model
-    # import pyTMD.predict
-    # import pyTMD.spatial
-    # import pyTMD.time
-    # import pyTMD.utilities
-
-    # Get parameters for tide model; use custom definition file for
-    # FES2012 (leave this as an undocumented feature for now)
-    # if model == "FES2012":
-    #     pytmd_model = pyTMD.io.model(directory).from_file(
-    #         directory / "model_FES2012.def"
-    #     )
-    # elif model == "TPXO8-atlas-v1":
-    #     pytmd_model = pyTMD.io.model(directory).from_file(directory / "model_TPXO8.def")
-    # else:
-    #     pytmd_model = pyTMD.io.model(
-    #         directory, format="netcdf", compressed=False
-    #     ).elevation(model)
-
-    #     if model in NONSTANDARD_MODELS:
-    #         model_params = NONSTANDARD_MODELS[model]
-    #         model_params_bytes = io.BytesIO(json.dumps(model_params).encode("utf-8"))
-    #         pytmd_model = pyTMD.io.model(directory).from_file(definition_file=model_params_bytes)
-
-    #     else:
-
+    # Obtain model details
     pytmd_model = pyTMD.io.model(directory).elevation(model)
 
     # Convert x, y to latitude/longitude
@@ -411,11 +485,12 @@ def model_tides(
 
     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`)
+
+    - 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
@@ -441,11 +516,11 @@ def model_tides(
     model : string, optional
         The tide model used to model tides. Options include:
 
-        - "FES2014" (pre-configured on DEA Sandbox)
+        - "EOT20"
+        - "FES2014"
         - "FES2022"
         - "TPXO9-atlas-v5"
         - "TPXO8-atlas"
-        - "EOT20"
         - "HAMTIDE11"
         - "GOT4.10"
         - "ensemble" (advanced ensemble tide model functionality;
@@ -453,7 +528,7 @@ def model_tides(
     directory : string, optional
         The directory containing tide model data files. If no path is
         provided, this will default to the environment variable
-        `EO_TIDES_TIDE_MODELS` if set, otherwise "/var/share/tide_models".
+        `EO_TIDES_TIDE_MODELS` if set, or raise an error if not.
         Tide modelling files should be stored in sub-folders for each
         model that match the structure provided by `pyTMD`.
 
@@ -539,23 +614,6 @@ def model_tides(
         A dataframe containing modelled tide heights.
 
     """
-    # 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")
-
-    # If time passed as a single Timestamp, convert to datetime64
-    if isinstance(time, pd.Timestamp):
-        time = time.to_datetime64()
-
     # Turn inputs into arrays for consistent handling
     models_requested = np.atleast_1d(model)
     x = np.atleast_1d(x)
@@ -581,32 +639,41 @@ def model_tides(
             "you intended to model multiple timesteps at each point."
         )
 
-    # Verify that all provided models are supported
-    valid_models = [
-        # Standard built-in pyTMD models
-        "EOT20",
-        "FES2014",
-        "FES2022",
-        "GOT4.10",
-        "HAMTIDE11",
-        "TPXO8-atlas",  # binary version, not suitable for clipping
-        "TPXO9-atlas-v5",
-        # Non-standard models, defined internally
-        "FES2012",
-        "FES2014_extrapolated",
-        "FES2022_extrapolated",
-        "GOT5.6",
-        "GOT5.6_extrapolated",
-        "TPXO8-atlas-v1",  # netCDF version
-        # Advanced ensemble model functionality
-        "ensemble",
-    ]
+    # If time passed as a single Timestamp, convert to datetime64
+    if isinstance(time, pd.Timestamp):
+        time = time.to_datetime64()
+
+    # Set tide modelling files directory. If no custom path is
+    # provided, try global environment variable.
+    directory = _set_directory(directory)
+
+    # Get full list of supported models from pyTMD database;
+    # add ensemble option to list of models
+    available_models, valid_models = list_models(
+        directory, show_available=False, show_supported=False, raise_error=True
+    )
+    available_models = available_models + ["ensemble"]
+    valid_models = valid_models + ["ensemble"]
+
+    # Error if any models are not supported
     if not all(m in valid_models for m in models_requested):
-        raise ValueError(
-            f"One or more of the models requested {models_requested} is "
-            f"not valid. The following models are currently supported: "
-            f"{valid_models}",
+        error_text = (
+            f"One or more of the requested models are not valid:\n"
+            f"{models_requested}\n\n"
+            "The following models are supported:\n"
+            f"{valid_models}"
+        )
+        raise ValueError(error_text)
+
+    # Error if any models are not available in `directory`
+    if not all(m in available_models for m in models_requested):
+        error_text = (
+            f"One or more of the requested models are valid, but not available in `{directory}`:\n"
+            f"{models_requested}\n\n"
+            f"The following models are available in `{directory}`:\n"
+            f"{available_models}"
         )
+        raise ValueError(error_text)
 
     # If ensemble modelling is requested, use a custom list of models
     # for subsequent processing

{eo_tides-0.0.18.dist-info → eo_tides-0.0.20.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: eo-tides
-Version: 0.0.18
+Version: 0.0.20
 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/

eo_tides-0.0.20.dist-info/RECORD

@@ -0,0 +1,10 @@
+eo_tides/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+eo_tides/model.py,sha256=wo2bsWEefpTFd3KrkzZelIU4FV_noCNJjMQs2arwypk,46021
+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.20.dist-info/LICENSE,sha256=NYULqbFuDRV6CysPbkR2WZk863YwwHeftBtnsb4cWf8,1077
+eo_tides-0.0.20.dist-info/METADATA,sha256=_Ns8em48OsUfgl97Rw4hSPXPqfJV9FelTtq25qcb4ag,5335
+eo_tides-0.0.20.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+eo_tides-0.0.20.dist-info/top_level.txt,sha256=lXZDUUM1DlLdKWHRn8zdmtW8Rx-eQOIWVvt0b8VGiyQ,9
+eo_tides-0.0.20.dist-info/RECORD,,

eo_tides-0.0.18.dist-info/RECORD

@@ -1,10 +0,0 @@
-eo_tides/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-eo_tides/model.py,sha256=5teDNCgtqRyp0vJHhXMdPtZYdaKzXcAo-a9Cum46Jgg,43305
-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.18.dist-info/LICENSE,sha256=NYULqbFuDRV6CysPbkR2WZk863YwwHeftBtnsb4cWf8,1077
-eo_tides-0.0.18.dist-info/METADATA,sha256=WLxfpg2EhN7Ly9GbNhLLFJVa2LiuO3NHckIcmjY2pqE,5335
-eo_tides-0.0.18.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
-eo_tides-0.0.18.dist-info/top_level.txt,sha256=lXZDUUM1DlLdKWHRn8zdmtW8Rx-eQOIWVvt0b8VGiyQ,9
-eo_tides-0.0.18.dist-info/RECORD,,