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

{eo_tides-0.0.19 → eo_tides-0.0.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: eo-tides
-Version: 0.0.19
+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.19 → eo_tides-0.0.20}/eo_tides/model.py

@@ -1,5 +1,6 @@
 import os
 import pathlib
+import warnings
 from concurrent.futures import ProcessPoolExecutor
 from functools import partial
 
@@ -15,65 +16,103 @@ from tqdm import tqdm
 from eo_tides.utils import idw
 
 
-def available_models(directory=None, show_supported=True):
+def _set_directory(directory):
     """
-    Prints a list of all tide models available for tide
-    modelling using `eo-tides`.
+    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
-    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.
+    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 : str
-        Path to the directory containing tide model files.
+    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_m : list
-        A list of all available tide models within
-        `directory`.
+    available_models : list
+        A list of alltide models available within `directory`.
+    supported_models : list
+        A list of all tide models supported by `eo-tides`.
     """
-    # 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"
+    # Set tide modelling files directory. If no custom path is
+    # provided, try global environment variable.
+    directory = _set_directory(directory)
 
-    # 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()
+    # 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
-    print(f"Tide models available in `{directory}`:")
-    available_m = []
+    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)
-            # Mark available models with a green tick
-            print(f" ✅ {m}")
-            available_m.append(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}")
 
-    # Return list of available models
-    return available_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(
@@ -94,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
@@ -474,11 +486,11 @@ 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
@@ -504,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;
@@ -516,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`.
 
@@ -602,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)
@@ -644,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.19 → eo_tides-0.0.20}/eo_tides.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: eo-tides
-Version: 0.0.19
+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.19 → eo_tides-0.0.20}/eo_tides.egg-info/SOURCES.txt

@@ -12,4 +12,5 @@ eo_tides.egg-info/dependency_links.txt
 eo_tides.egg-info/requires.txt
 eo_tides.egg-info/top_level.txt
 tests/test_model.py
+tests/test_utils.py
 tests/test_validation.py

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

@@ -1,6 +1,6 @@
 [project]
 name = "eo-tides"
-version = "0.0.19"
+version = "0.0.20"
 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.19 → eo_tides-0.0.20}/tests/test_model.py

@@ -6,7 +6,7 @@ import pystac_client
 import pytest
 import xarray as xr
 
-from eo_tides.model import available_models, model_tides, pixel_tides
+from eo_tides.model import list_models, model_tides, pixel_tides
 from eo_tides.validation import eval_metrics
 
 GAUGE_X = 122.2183
@@ -91,9 +91,12 @@ def satellite_ds(request):
 
 
 # Test available tide models
-def test_available_models():
-    available_m = available_models()
-    assert available_m == ["FES2014", "HAMTIDE11"]
+def test_list_models():
+    available_models, supported_models = list_models()
+    assert available_models == ["FES2014", "HAMTIDE11"]
+
+    available_models, supported_models = list_models(show_available=False, show_supported=False)
+    assert available_models == ["FES2014", "HAMTIDE11"]
 
 
 # Run test for multiple input coordinates, CRSs and interpolation methods

eo_tides-0.0.20/tests/test_utils.py

@@ -0,0 +1,84 @@
+import numpy as np
+import pytest
+
+from eo_tides.utils import idw
+
+
+# Test Inverse Distance Weighted function
+def test_idw():
+    # Basic psuedo-1D example
+    input_z = [1, 2, 3, 4, 5]
+    input_x = [0, 1, 2, 3, 4]
+    input_y = [0, 0, 0, 0, 0]
+    output_x = [0.5, 1.5, 2.5, 3.5]
+    output_y = [0.0, 0.0, 0.0, 0.0]
+    out = idw(input_z, input_x, input_y, output_x, output_y, k=2)
+    assert np.allclose(out, [1.5, 2.5, 3.5, 4.5])
+
+    # Verify that k > input points gives error
+    with pytest.raises(ValueError):
+        idw(input_z, input_x, input_y, output_x, output_y, k=6)
+
+    # 2D nearest neighbour case
+    input_z = [1, 2, 3, 4]
+    input_x = [0, 4, 0, 4]
+    input_y = [0, 0, 4, 4]
+    output_x = [1, 4, 0, 3]
+    output_y = [0, 1, 3, 4]
+    out = idw(input_z, input_x, input_y, output_x, output_y, k=1)
+    assert np.allclose(out, [1, 2, 3, 4])
+
+    # Two neighbours
+    input_z = [1, 2, 3, 4]
+    input_x = [0, 4, 0, 4]
+    input_y = [0, 0, 4, 4]
+    output_x = [2, 0, 4, 2]
+    output_y = [0, 2, 2, 4]
+    out = idw(input_z, input_x, input_y, output_x, output_y, k=2)
+    assert np.allclose(out, [1.5, 2, 3, 3.5])
+
+    # Four neighbours
+    out = idw(input_z, input_x, input_y, output_x, output_y, k=4)
+    assert np.allclose(out, [2.11, 2.30, 2.69, 2.88], rtol=0.01)
+
+    # Four neighbours; max distance of 2
+    out = idw(input_z, input_x, input_y, output_x, output_y, k=4, max_dist=2)
+    assert np.allclose(out, [1.5, 2, 3, 3.5])
+
+    # Four neighbours; max distance of 2, k_min of 4 (should return NaN)
+    out = idw(input_z, input_x, input_y, output_x, output_y, k=4, max_dist=2, k_min=4)
+    assert np.isnan(out).all()
+
+    # Four neighbours; power function p=0
+    out = idw(input_z, input_x, input_y, output_x, output_y, k=4, p=0)
+    assert np.allclose(out, [2.5, 2.5, 2.5, 2.5])
+
+    # Four neighbours; power function p=2
+    out = idw(input_z, input_x, input_y, output_x, output_y, k=4, p=2)
+    assert np.allclose(out, [1.83, 2.17, 2.83, 3.17], rtol=0.01)
+
+    # Different units, nearest neighbour case
+    input_z = [10, 20, 30, 40]
+    input_x = [1125296, 1155530, 1125296, 1155530]
+    input_y = [-4169722, -4169722, -4214782, -4214782]
+    output_x = [1124952, 1159593, 1120439, 1155284]
+    output_y = [-4169749, -4172892, -4211108, -4214332]
+    out = idw(input_z, input_x, input_y, output_x, output_y, k=1)
+    assert np.allclose(out, [10, 20, 30, 40])
+
+    # Verify distance works on different units
+    output_x = [1142134, 1138930]
+    output_y = [-4171232, -4213451]
+    out = idw(input_z, input_x, input_y, output_x, output_y, k=4, max_dist=20000)
+    assert np.allclose(out, [15, 35], rtol=0.1)
+
+    # Test multidimensional input
+    input_z = np.column_stack(([1, 2, 3, 4], [10, 20, 30, 40]))
+    input_x = [0, 4, 0, 4]
+    input_y = [0, 0, 4, 4]
+    output_x = [1, 4, 0, 3]
+    output_y = [0, 1, 3, 4]
+    out = idw(input_z, input_x, input_y, output_x, output_y, k=1)
+    assert input_z.shape == out.shape
+    assert np.allclose(out[:, 0], [1, 2, 3, 4])
+    assert np.allclose(out[:, 1], [10, 20, 30, 40])