eo-tides 0.0.22__tar.gz → 0.1.0__tar.gz

{eo_tides-0.0.22 → eo_tides-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: eo-tides
-Version: 0.0.22
+Version: 0.1.0
 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/
@@ -37,6 +37,7 @@ Requires-Dist: tqdm>=4.55.0
 Requires-Dist: xarray>=2022.3.0
 Provides-Extra: notebooks
 Requires-Dist: odc-stac>=0.3.10; extra == "notebooks"
+Requires-Dist: odc-geo[tiff,warp]>=0.4.7; extra == "notebooks"
 Requires-Dist: pystac-client>=0.8.3; extra == "notebooks"
 Requires-Dist: folium>=0.16.0; extra == "notebooks"
 Requires-Dist: planetary_computer>=1.0.0; extra == "notebooks"
@@ -47,7 +48,7 @@ Requires-Dist: planetary_computer>=1.0.0; extra == "notebooks"
 
 [![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)
-![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FGeoscienceAustralia%2Feo-tides%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)
+![Python Version from PEP 621 TOML](https://img.shields.io/pypi/pyversions/eo-tides)
 [![codecov](https://codecov.io/gh/GeoscienceAustralia/eo-tides/branch/main/graph/badge.svg)](https://codecov.io/gh/GeoscienceAustralia/eo-tides)
 [![License](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)
 
@@ -70,9 +71,9 @@ These tools can be applied to petabytes of freely available satellite data (e.g.
 - 🌊 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 integrated 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/))
+<!-- - 🎯 Combine multiple tide models into a single locally-optimised "ensemble" model informed by satellite altimetry and satellite-observed patterns of tidal inundation -->
 
 ## Supported tide models
 
@@ -86,6 +87,14 @@ These tools can be applied to petabytes of freely available satellite data (e.g.
 
 For instructions on how to set up these models for use in `eo-tides`, refer to [Setting up tide models](setup.md).
 
+## Installing and setting up `eo-tides`
+
+To get started with `eo-tides`, follow the [Installation](https://geoscienceaustralia.github.io/eo-tides/install/) and [Setting up tide models](https://geoscienceaustralia.github.io/eo-tides/setup/) guides.
+
+## Jupyter Notebooks code examples
+
+Interactive Jupyter Notebook usage examples and more complex coastal EO case studies can be found in the [`docs/notebooks/`](https://github.com/GeoscienceAustralia/eo-tides/tree/main/docs/notebooks) directory, or [rendered in the documentation here](https://geoscienceaustralia.github.io/eo-tides/notebooks/Model_tides/).
+
 ## Citing `eo-tides`
 
 To cite `eo-tides` in your work, please use the following citation:
@@ -93,3 +102,8 @@ 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. https://github.com/GeoscienceAustralia/eo-tides
 ```
+
+## Acknowledgements
+
+For a full list of acknowledgements, refer to [Citations and Credits](https://geoscienceaustralia.github.io/eo-tides/credits/).
+This repository was initialised using the [`cookiecutter-uv`](https://github.com/fpgmaas/cookiecutter-uv) package.

{eo_tides-0.0.22 → eo_tides-0.1.0}/README.md

@@ -4,7 +4,7 @@
 
 [![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)
-![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FGeoscienceAustralia%2Feo-tides%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)
+![Python Version from PEP 621 TOML](https://img.shields.io/pypi/pyversions/eo-tides)
 [![codecov](https://codecov.io/gh/GeoscienceAustralia/eo-tides/branch/main/graph/badge.svg)](https://codecov.io/gh/GeoscienceAustralia/eo-tides)
 [![License](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)
 
@@ -27,9 +27,9 @@ These tools can be applied to petabytes of freely available satellite data (e.g.
 - 🌊 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 integrated 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/))
+<!-- - 🎯 Combine multiple tide models into a single locally-optimised "ensemble" model informed by satellite altimetry and satellite-observed patterns of tidal inundation -->
 
 ## Supported tide models
 
@@ -43,6 +43,14 @@ These tools can be applied to petabytes of freely available satellite data (e.g.
 
 For instructions on how to set up these models for use in `eo-tides`, refer to [Setting up tide models](setup.md).
 
+## Installing and setting up `eo-tides`
+
+To get started with `eo-tides`, follow the [Installation](https://geoscienceaustralia.github.io/eo-tides/install/) and [Setting up tide models](https://geoscienceaustralia.github.io/eo-tides/setup/) guides.
+
+## Jupyter Notebooks code examples
+
+Interactive Jupyter Notebook usage examples and more complex coastal EO case studies can be found in the [`docs/notebooks/`](https://github.com/GeoscienceAustralia/eo-tides/tree/main/docs/notebooks) directory, or [rendered in the documentation here](https://geoscienceaustralia.github.io/eo-tides/notebooks/Model_tides/).
+
 ## Citing `eo-tides`
 
 To cite `eo-tides` in your work, please use the following citation:
@@ -50,3 +58,8 @@ 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. https://github.com/GeoscienceAustralia/eo-tides
 ```
+
+## Acknowledgements
+
+For a full list of acknowledgements, refer to [Citations and Credits](https://geoscienceaustralia.github.io/eo-tides/credits/).
+This repository was initialised using the [`cookiecutter-uv`](https://github.com/fpgmaas/cookiecutter-uv) package.

{eo_tides-0.0.22 → eo_tides-0.1.0}/eo_tides/eo.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import os
+import warnings
 from typing import TYPE_CHECKING
 
 import odc.geo.xr
@@ -93,19 +94,17 @@ def _pixel_tides_resample(
 
 
 def tag_tides(
-    ds: xr.Dataset,
+    ds: xr.Dataset | xr.DataArray,
     model: str | list[str] = "EOT20",
     directory: str | os.PathLike | None = None,
     tidepost_lat: float | None = None,
     tidepost_lon: float | None = None,
-    ebb_flow: bool = False,
-    swap_dims: bool = False,
     **model_tides_kwargs,
-) -> xr.Dataset:
+) -> xr.DataArray:
     """
     Model tide heights for every timestep in a multi-dimensional
-    dataset, and add them as a new `tide_height` (and optionally,
-    `ebb_flow`) variable that "tags" each observation with tide data.
+    dataset, and return a new `tide_height` array that can
+    be used to "tag" each observation with tide data.
 
     The function models tides at the centroid of the dataset
     by default, but a custom tidal modelling location can
@@ -123,7 +122,7 @@ def tag_tides(
 
     Parameters
     ----------
-    ds : xarray.Dataset
+    ds : xarray.Dataset or xarray.DataArray
         A multi-dimensional dataset (e.g. "x", "y", "time") to
         tag with tide heights. This dataset must contain a "time"
         dimension.
@@ -143,16 +142,6 @@ def tag_tides(
         Optional coordinates used to model tides. The default is None,
         which uses the centroid of the dataset as the tide modelling
         location.
-    ebb_flow : bool, optional
-        An optional boolean indicating whether to compute if the
-        tide phase was ebbing (falling) or flowing (rising) for each
-        observation. The default is False; if set to True, a new
-        "ebb_flow" variable will be added to the dataset with each
-        observation labelled with "Ebb" or "Flow".
-    swap_dims : bool, optional
-        An optional boolean indicating whether to swap the `time`
-        dimension in the original `ds` to the new "tide_height"
-        variable. Defaults to False.
     **model_tides_kwargs :
         Optional parameters passed to the `eo_tides.model.model_tides`
         function. Important parameters include `cutoff` (used to
@@ -174,8 +163,6 @@ def tag_tides(
 
     # Standardise model into a list for easy handling. and verify only one
     model = [model] if isinstance(model, str) else model
-    if (len(model) > 1) & swap_dims:
-        raise ValueError("Can only swap dimensions when a single tide model is passed to `model`.")
 
     # If custom tide modelling locations are not provided, use the
     # dataset centroid
@@ -208,48 +195,38 @@ def tag_tides(
             f"`tidepost_lat` and `tidepost_lon` parameters."
         )
 
-    # Optionally calculate the tide phase for each observation
-    if ebb_flow:
-        # Model tides for a time 15 minutes prior to each previously
-        # modelled satellite acquisition time. This allows us to compare
-        # tide heights to see if they are rising or falling.
-        print("Modelling tidal phase (e.g. ebb or flow)")
-        tide_pre_df = model_tides(
-            x=lon,  # type: ignore
-            y=lat,  # type: ignore
-            time=(ds.time - pd.Timedelta("15 min")),
-            model=model,
-            directory=directory,
-            crs="EPSG:4326",
-            **model_tides_kwargs,
-        )
-
-        # Compare tides computed for each timestep. If the previous tide
-        # was higher than the current tide, the tide is 'ebbing'. If the
-        # previous tide was lower, the tide is 'flowing'
-        tide_df["ebb_flow"] = (tide_df.tide_height < tide_pre_df.tide_height.values).replace({
-            True: "Ebb",
-            False: "Flow",
-        })
+    # # Optionally calculate the tide phase for each observation
+    # if ebb_flow:
+    #     # Model tides for a time 15 minutes prior to each previously
+    #     # modelled satellite acquisition time. This allows us to compare
+    #     # tide heights to see if they are rising or falling.
+    #     print("Modelling tidal phase (e.g. ebb or flow)")
+    #     tide_pre_df = model_tides(
+    #         x=lon,  # type: ignore
+    #         y=lat,  # type: ignore
+    #         time=(ds.time - pd.Timedelta("15 min")),
+    #         model=model,
+    #         directory=directory,
+    #         crs="EPSG:4326",
+    #         **model_tides_kwargs,
+    #     )
+
+    #     # Compare tides computed for each timestep. If the previous tide
+    #     # was higher than the current tide, the tide is 'ebbing'. If the
+    #     # previous tide was lower, the tide is 'flowing'
+    #     tide_df["ebb_flow"] = (tide_df.tide_height < tide_pre_df.tide_height.values).replace({
+    #         True: "Ebb",
+    #         False: "Flow",
+    #     })
 
     # Convert to xarray format
-    tide_xr = tide_df.reset_index().set_index(["time", "tide_model"]).drop(["x", "y"], axis=1).to_xarray()
+    tide_xr = tide_df.reset_index().set_index(["time", "tide_model"]).drop(["x", "y"], axis=1).tide_height.to_xarray()
 
     # If only one tidal model exists, squeeze out "tide_model" dim
     if len(tide_xr.tide_model) == 1:
-        tide_xr = tide_xr.squeeze("tide_model", drop=True)
-
-    # Add each array into original dataset
-    for var in tide_xr.data_vars:
-        ds[var] = tide_xr[var]
-
-    # Swap dimensions and sort by tide height
-    if swap_dims:
-        ds = ds.swap_dims({"time": "tide_height"})
-        ds = ds.sortby("tide_height")
-        ds = ds.drop_vars("time")
+        tide_xr = tide_xr.squeeze("tide_model")
 
-    return ds
+    return tide_xr
 
 
 def pixel_tides(
@@ -493,8 +470,10 @@ def pixel_tides(
     # Set dtype to dtype of the input data as quantile always returns
     # float64 (memory intensive)
     if calculate_quantiles is not None:
-        print("Computing tide quantiles")
-        tides_lowres = tides_lowres.quantile(q=calculate_quantiles, dim="time").astype(tides_lowres.dtype)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            print("Computing tide quantiles")
+            tides_lowres = tides_lowres.quantile(q=calculate_quantiles, dim="time").astype(tides_lowres.dtype)
 
     # If only one tidal model exists, squeeze out "tide_model" dim
     if len(tides_lowres.tide_model) == 1:

{eo_tides-0.0.22 → eo_tides-0.1.0}/eo_tides/model.py

@@ -3,8 +3,10 @@ from __future__ import annotations
 
 import os
 import pathlib
+import textwrap
 import warnings
 from concurrent.futures import ProcessPoolExecutor
+from concurrent.futures.process import BrokenProcessPool
 from functools import partial
 from typing import TYPE_CHECKING
 
@@ -130,7 +132,7 @@ def list_models(
                 # Mark available models with a green tick
                 status = "✅"
                 print(f"{status:^{status_width}}│ {m:<{name_width}} │ {expected_paths[m]:<{path_width}}")
-        except:
+        except FileNotFoundError:
             if show_supported:
                 # Mark unavailable models with a red cross
                 status = "❌"
@@ -147,16 +149,19 @@ def list_models(
 
     # Raise error or warning if no models are available
     if not available_models:
-        warning_text = (
-            f"No valid tide models are available in `{directory}`. "
-            "Are you sure 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?"
-        )
+        warning_msg = textwrap.dedent(
+            f"""
+            No valid tide models are available in `{directory}`.
+            Are you sure 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?
+            """
+        ).strip()
+
         if raise_error:
-            raise Exception(warning_text)
+            raise Exception(warning_msg)
         else:
-            warnings.warn(warning_text, UserWarning)
+            warnings.warn(warning_msg, UserWarning)
 
     # Return list of available and supported models
     return available_models, supported_models
@@ -199,88 +204,101 @@ def _model_tides(
         lat.max() + buffer,
     ]
 
-    # Read tidal constants and interpolate to grid points
-    if pytmd_model.format in ("OTIS", "ATLAS-compact", "TMD3"):
-        amp, ph, D, c = pyTMD.io.OTIS.extract_constants(
-            lon,
-            lat,
-            pytmd_model.grid_file,
-            pytmd_model.model_file,
-            pytmd_model.projection,
-            type=pytmd_model.type,
-            grid=pytmd_model.file_format,
-            crop=crop,
-            bounds=bounds,
-            method=method,
-            extrapolate=extrapolate,
-            cutoff=cutoff,
-        )
+    try:
+        # Read tidal constants and interpolate to grid points
+        if pytmd_model.format in ("OTIS", "ATLAS-compact", "TMD3"):
+            amp, ph, D, c = pyTMD.io.OTIS.extract_constants(
+                lon,
+                lat,
+                pytmd_model.grid_file,
+                pytmd_model.model_file,
+                pytmd_model.projection,
+                type=pytmd_model.type,
+                grid=pytmd_model.file_format,
+                crop=crop,
+                bounds=bounds,
+                method=method,
+                extrapolate=extrapolate,
+                cutoff=cutoff,
+            )
 
-        # Use delta time at 2000.0 to match TMD outputs
-        deltat = np.zeros((len(timescale)), dtype=np.float64)
-
-    elif pytmd_model.format in ("ATLAS-netcdf",):
-        amp, ph, D, c = pyTMD.io.ATLAS.extract_constants(
-            lon,
-            lat,
-            pytmd_model.grid_file,
-            pytmd_model.model_file,
-            type=pytmd_model.type,
-            crop=crop,
-            bounds=bounds,
-            method=method,
-            extrapolate=extrapolate,
-            cutoff=cutoff,
-            scale=pytmd_model.scale,
-            compressed=pytmd_model.compressed,
-        )
+            # Use delta time at 2000.0 to match TMD outputs
+            deltat = np.zeros((len(timescale)), dtype=np.float64)
+
+        elif pytmd_model.format in ("ATLAS-netcdf",):
+            amp, ph, D, c = pyTMD.io.ATLAS.extract_constants(
+                lon,
+                lat,
+                pytmd_model.grid_file,
+                pytmd_model.model_file,
+                type=pytmd_model.type,
+                crop=crop,
+                bounds=bounds,
+                method=method,
+                extrapolate=extrapolate,
+                cutoff=cutoff,
+                scale=pytmd_model.scale,
+                compressed=pytmd_model.compressed,
+            )
 
-        # Use delta time at 2000.0 to match TMD outputs
-        deltat = np.zeros((len(timescale)), dtype=np.float64)
-
-    elif pytmd_model.format in ("GOT-ascii", "GOT-netcdf"):
-        amp, ph, c = pyTMD.io.GOT.extract_constants(
-            lon,
-            lat,
-            pytmd_model.model_file,
-            grid=pytmd_model.file_format,
-            crop=crop,
-            bounds=bounds,
-            method=method,
-            extrapolate=extrapolate,
-            cutoff=cutoff,
-            scale=pytmd_model.scale,
-            compressed=pytmd_model.compressed,
-        )
+            # Use delta time at 2000.0 to match TMD outputs
+            deltat = np.zeros((len(timescale)), dtype=np.float64)
+
+        elif pytmd_model.format in ("GOT-ascii", "GOT-netcdf"):
+            amp, ph, c = pyTMD.io.GOT.extract_constants(
+                lon,
+                lat,
+                pytmd_model.model_file,
+                grid=pytmd_model.file_format,
+                crop=crop,
+                bounds=bounds,
+                method=method,
+                extrapolate=extrapolate,
+                cutoff=cutoff,
+                scale=pytmd_model.scale,
+                compressed=pytmd_model.compressed,
+            )
 
-        # Delta time (TT - UT1)
-        deltat = timescale.tt_ut1
-
-    elif pytmd_model.format in ("FES-ascii", "FES-netcdf"):
-        amp, ph = pyTMD.io.FES.extract_constants(
-            lon,
-            lat,
-            pytmd_model.model_file,
-            type=pytmd_model.type,
-            version=pytmd_model.version,
-            crop=crop,
-            bounds=bounds,
-            method=method,
-            extrapolate=extrapolate,
-            cutoff=cutoff,
-            scale=pytmd_model.scale,
-            compressed=pytmd_model.compressed,
-        )
+            # Delta time (TT - UT1)
+            deltat = timescale.tt_ut1
+
+        elif pytmd_model.format in ("FES-ascii", "FES-netcdf"):
+            amp, ph = pyTMD.io.FES.extract_constants(
+                lon,
+                lat,
+                pytmd_model.model_file,
+                type=pytmd_model.type,
+                version=pytmd_model.version,
+                crop=crop,
+                bounds=bounds,
+                method=method,
+                extrapolate=extrapolate,
+                cutoff=cutoff,
+                scale=pytmd_model.scale,
+                compressed=pytmd_model.compressed,
+            )
 
-        # Available model constituents
-        c = pytmd_model.constituents
+            # Available model constituents
+            c = pytmd_model.constituents
 
-        # Delta time (TT - UT1)
-        deltat = timescale.tt_ut1
-    else:
-        raise Exception(
-            f"Unsupported model format ({pytmd_model.format}). This may be due to an incompatible version of `pyTMD`."
-        )
+            # Delta time (TT - UT1)
+            deltat = timescale.tt_ut1
+        else:
+            raise Exception(
+                f"Unsupported model format ({pytmd_model.format}). This may be due to an incompatible version of `pyTMD`."
+            )
+
+    # Raise error if constituent files no not cover analysis extent
+    except IndexError:
+        error_msg = textwrap.dedent(
+            f"""
+            The {model} tide model constituent files do not cover the requested analysis extent.
+            This can occur if you are using clipped model files to improve run times.
+            Consider using model files that cover your entire analysis area, or set `crop=False`
+            to reduce the extent of tide model constituent files that is loaded.
+            """
+        ).strip()
+        raise Exception(error_msg)
 
     # Calculate complex phase in radians for Euler's
     cph = -1j * ph * np.pi / 180.0
@@ -550,8 +568,8 @@ def model_tides(
     <https://pytmd.readthedocs.io/en/latest/getting_started/Getting-Started.html#directories>
 
     This function is a modification of the `pyTMD` package's
-    `compute_tidal_elevations` function. For more info:
-    <https://pytmd.readthedocs.io/en/latest/api_reference/compute_tidal_elevations.html>
+    `pyTMD.compute.tide_elevations` function. For more info:
+    <https://pytmd.readthedocs.io/en/latest/api_reference/compute.html#pyTMD.compute.tide_elevations>
 
     Parameters
     ----------
@@ -787,12 +805,19 @@ def model_tides(
                 )
 
             # Apply func in parallel, iterating through each input param
-            model_outputs = list(
-                tqdm(
-                    executor.map(iter_func, model_iters, x_iters, y_iters, time_iters),
-                    total=len(model_iters),
-                ),
-            )
+            try:
+                model_outputs = list(
+                    tqdm(
+                        executor.map(iter_func, model_iters, x_iters, y_iters, time_iters),
+                        total=len(model_iters),
+                    ),
+                )
+            except BrokenProcessPool:
+                error_msg = (
+                    "Parallelised tide modelling failed, likely to to an out-of-memory error. "
+                    "Try reducing the size of your analysis, or set `parallel=False`."
+                )
+                raise RuntimeError(error_msg)
 
     # Model tides in series if parallelisation is off
     else: