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

eo_tides/model.py

@@ -1,79 +1,165 @@
+# Used to postpone evaluation of type annotations
+from __future__ import annotations
+
 import os
 import pathlib
+import warnings
 from concurrent.futures import ProcessPoolExecutor
 from functools import partial
+from typing import TYPE_CHECKING
+
+# Only import if running type checking
+if TYPE_CHECKING:
+    import xarray as xr
 
 import geopandas as gpd
 import numpy as np
-import odc.geo.xr
 import pandas as pd
 import pyproj
 import pyTMD
+from colorama import Style, init
 from pyTMD.io.model import load_database, model
 from tqdm import tqdm
 
-from eo_tides.utils import idw
+from .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 available_models(directory=None, show_supported=True):
+def list_models(
+    directory: str | os.PathLike | None = None,
+    show_available: bool = True,
+    show_supported: bool = True,
+    raise_error: bool = False,
+) -> tuple[list[str], list[str]]:
     """
-    Prints a list of all tide models available for tide
-    modelling using `eo-tides`.
+    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 : str, 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.
+    raise_error : bool, optional
+        If True, raise an error if no available models are found.
+        If False, raise a warning.
 
     Returns
     -------
-    available_m : list
-        A list of all available tide models within
-        `directory`.
+    available_models : list of str
+        A list of all tide models available within `directory`.
+    supported_models : list of str
+        A list of all tide models supported by `eo-tides`.
     """
-    # TODO: Pull directory code into re-usable function
+    init()  # Initialize colorama
 
-    # 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 pyTMD database
+    model_database = load_database()["elevation"]
+    supported_models = list(model_database.keys())
+
+    # Extract expected model paths
+    expected_paths = {}
+    for m in supported_models:
+        model_file = model_database[m]["model_file"]
+        model_file = model_file[0] if isinstance(model_file, list) else model_file
+        expected_paths[m] = str(directory / pathlib.Path(model_file).expanduser().parent)
 
-    # Get full list of supported models from the database
-    supported_models = load_database()["elevation"].keys()
+    # Define column widths
+    status_width = 4  # Width for emoji
+    name_width = max(len(name) for name in supported_models)
+    path_width = max(len(path) for path in expected_paths.values())
 
     # 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:
+        total_width = min(status_width + name_width + path_width + 6, 80)
+        print("─" * total_width)
+        print(f"{'󠀠🌊':^{status_width}} | {'Model':<{name_width}} | {'Expected path':<{path_width}}")
+        print("─" * total_width)
+
+    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)
+            model_file = model(directory=directory).elevation(m=m)
+            available_models.append(m)
+
+            if show_available:
+                # Mark available models with a green tick
+                status = "✅"
+                print(f"{status:^{status_width}}│ {m:<{name_width}} │ {expected_paths[m]:<{path_width}}")
         except:
             if show_supported:
                 # Mark unavailable models with a red cross
-                print(f" ❌ {m}")
+                status = "❌"
+                print(
+                    f"{status:^{status_width}}│ {Style.DIM}{m:<{name_width}} │ {expected_paths[m]:<{path_width}}{Style.RESET_ALL}"
+                )
 
-    # Return list of available models
-    return available_m
+    if show_available or show_supported:
+        print("─" * total_width)
+
+        # Print summary
+        print(f"\n{Style.BRIGHT}Summary:{Style.RESET_ALL}")
+        print(f"Available models: {len(available_models)}/{len(supported_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?"
+        )
+        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 +180,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
@@ -284,10 +343,8 @@ def _model_tides(
 
 
 def _ensemble_model(
-    x,
-    y,
-    crs,
     tide_df,
+    crs,
     ensemble_models,
     ensemble_func=None,
     ensemble_top_n=3,
@@ -301,29 +358,27 @@ def _ensemble_model(
     to inform the selection of the best local models.
 
     This function performs the following steps:
+    1. Takes a dataframe of tide heights from multiple tide models, as
+       produced by `eo_tides.model.model_tides`
     1. Loads model ranking points from a GeoJSON file, filters them
        based on the valid data percentage, and retains relevant columns
-    2. Interpolates the model rankings into the requested x and y
-       coordinates using Inverse Weighted Interpolation (IDW)
+    2. Interpolates the model rankings into the "x" and "y" coordinates
+       of the original dataframe using Inverse Weighted Interpolation (IDW)
     3. Uses rankings to combine multiple tide models into a single
        optimised ensemble model (by default, by taking the mean of the
        top 3 ranked models)
-    4. Returns a DataFrame with the combined ensemble model predictions
+    4. Returns a new dataFrame with the combined ensemble model predictions
 
     Parameters
     ----------
-    x : array-like
-        Array of x-coordinates where the ensemble model predictions are
-        required.
-    y : array-like
-        Array of y-coordinates where the ensemble model predictions are
-        required.
-    crs : string
-        Input coordinate reference system for x and y coordinates. Used
-        to ensure that interpolations are performed in the correct CRS.
     tide_df : pandas.DataFrame
-        DataFrame containing tide model predictions with columns
+        DataFrame produced by `eo_tides.model.model_tides`, containing
+        tide model predictions with columns:
         `["time", "x", "y", "tide_height", "tide_model"]`.
+    crs : string
+        Coordinate reference system for the "x" and "y" coordinates in
+        `tide_df`. Used to ensure that interpolations are performed
+        in the correct CRS.
     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
@@ -342,7 +397,7 @@ def _ensemble_model(
     ranking_points : str, optional
         Path to the GeoJSON file containing model ranking points. This
         dataset should include columns containing rankings for each tide
-        model, named with the prefix "rank_". e.g. "rank_FES2014".
+        model, named with the prefix "rank_". e.g. "rank_EOT20".
         Low values should represent high rankings (e.g. 1 = top ranked).
     ranking_valid_perc : float, optional
         Minimum percentage of valid data required to include a model
@@ -367,6 +422,10 @@ def _ensemble_model(
         the provided dictionary keys).
 
     """
+    # Extract x and y coords from dataframe
+    x = tide_df.index.get_level_values(level="x")
+    y = tide_df.index.get_level_values(level="y")
+
     # Load model ranks points and reproject to same CRS as x and y
     model_ranking_cols = [f"rank_{m}" for m in ensemble_models]
     model_ranks_gdf = (
@@ -449,36 +508,36 @@ def _ensemble_model(
 
 
 def model_tides(
-    x,
-    y,
-    time,
-    model="FES2014",
-    directory=None,
-    crs="EPSG:4326",
-    crop=True,
-    method="spline",
-    extrapolate=True,
-    cutoff=None,
-    mode="one-to-many",
-    parallel=True,
-    parallel_splits=5,
-    output_units="m",
-    output_format="long",
-    ensemble_models=None,
+    x: float | list[float] | xr.DataArray,
+    y: float | list[float] | xr.DataArray,
+    time: np.ndarray | pd.DatetimeIndex,
+    model: str | list[str] = "EOT20",
+    directory: str | os.PathLike | None = None,
+    crs: str = "EPSG:4326",
+    crop: bool = True,
+    method: str = "spline",
+    extrapolate: bool = True,
+    cutoff: float | None = None,
+    mode: str = "one-to-many",
+    parallel: bool = True,
+    parallel_splits: int = 5,
+    output_units: str = "m",
+    output_format: str = "long",
+    ensemble_models: list[str] | None = None,
     **ensemble_kwargs,
-):
+) -> pd.DataFrame:
     """
-    Compute tide heights from multiple tide models and for
-    multiple coordinates and/or timesteps.
+    Model tide heights at multiple coordinates and/or timesteps
+    using using one or more ocean tide 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`)
+    - 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
@@ -487,52 +546,39 @@ 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_tide_corrections` function. For more info:
-    <https://pytmd.readthedocs.io/en/stable/user_guide/compute_tide_corrections.html>
+    `compute_tidal_elevations` function. For more info:
+    <https://pytmd.readthedocs.io/en/latest/api_reference/compute_tidal_elevations.html>
 
     Parameters
     ----------
-    x, y : float or list of floats
+    x, y : float or list of float
         One or more x and y coordinates used to define
         the location at which to model tides. By default these
         coordinates should be lat/lon; use "crs" if they
         are in a custom coordinate reference system.
-    time : A datetime array or pandas.DatetimeIndex
+    time : Numpy datetime array or pandas.DatetimeIndex
         An array containing `datetime64[ns]` values or a
         `pandas.DatetimeIndex` providing the times at which to
         model tides in UTC time.
-    model : string, optional
-        The tide model used to model tides. Options include:
-
-        - "FES2014" (pre-configured on DEA Sandbox)
-        - "FES2022"
-        - "TPXO9-atlas-v5"
-        - "TPXO8-atlas"
-        - "EOT20"
-        - "HAMTIDE11"
-        - "GOT4.10"
-        - "ensemble" (advanced ensemble tide model functionality;
-          combining multiple models based on external model rankings)
-    directory : string, optional
+    model : str or list of str, optional
+        The tide model (or models) to use to model tides.
+        Defaults to "EOT20"; for a full list of available/supported
+        models, run `eo_tides.model.list_models`.
+    directory : str, 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`.
-
-        For example:
-
-        - `{directory}/fes2014/ocean_tide/`
-        - `{directory}/tpxo8_atlas/`
-        - `{directory}/TPXO9_atlas_v5/`
+        model that match the structure required by `pyTMD`
+        (<https://geoscienceaustralia.github.io/eo-tides/setup/>).
     crs : str, optional
         Input coordinate reference system for x and y coordinates.
         Defaults to "EPSG:4326" (WGS84; degrees latitude, longitude).
-    crop : bool optional
+    crop : bool, optional
         Whether to crop tide model constituent files on-the-fly to
         improve performance. Cropping will be performed based on a
         1 degree buffer around all input points. Defaults to True.
-    method : string, optional
+    method : str, optional
         Method used to interpolate tidal constituents
         from model files. Options include:
 
@@ -542,11 +588,11 @@ def model_tides(
     extrapolate : bool, optional
         Whether to extrapolate tides for x and y coordinates outside of
         the valid tide modelling domain using nearest-neighbor.
-    cutoff : int or float, optional
+    cutoff : float, optional
         Extrapolation cutoff in kilometers. The default is None, which
         will extrapolate for all points regardless of distance from the
         valid tide modelling domain.
-    mode : string, optional
+    mode : str, optional
         The analysis mode to use for tide modelling. Supports two options:
 
         - "one-to-many": Models tides for every timestep in "time" at
@@ -558,7 +604,7 @@ def model_tides(
         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
+    parallel : bool, optional
         Whether to parallelise tide modelling using `concurrent.futures`.
         If multiple tide models are requested, these will be run in
         parallel. Optionally, tide modelling can also be run in parallel
@@ -582,7 +628,7 @@ def model_tides(
         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
+    ensemble_models : list of str, optional
         An optional list of models used to generate the ensemble tide
         model if "ensemble" tide modelling is requested. Defaults to
         ["FES2014", "TPXO9-atlas-v5", "EOT20", "HAMTIDE11", "GOT4.10",
@@ -602,25 +648,8 @@ 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)
+    models_requested = list(np.atleast_1d(model))
     x = np.atleast_1d(x)
     y = np.atleast_1d(y)
     time = np.atleast_1d(time)
@@ -644,32 +673,44 @@ 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
+    )
+    # TODO: This is hacky, find a better way. Perhaps a kwarg that
+    # turns ensemble functionality on, and checks that supplied
+    # models match models expected for ensemble?
+    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
@@ -763,11 +804,11 @@ def model_tides(
 
     # Optionally compute ensemble model and add to dataframe
     if "ensemble" in models_requested:
-        ensemble_df = _ensemble_model(x, y, crs, tide_df, models_to_process, **ensemble_kwargs)
+        ensemble_df = _ensemble_model(tide_df, crs, models_to_process, **ensemble_kwargs)
 
         # Update requested models with any custom ensemble models, then
         # filter the dataframe to keep only models originally requested
-        models_requested = np.union1d(models_requested, ensemble_df.tide_model.unique())
+        models_requested = list(np.union1d(models_requested, ensemble_df.tide_model.unique()))
         tide_df = pd.concat([tide_df, ensemble_df]).query("tide_model in @models_requested")
 
     # Optionally convert to a wide format dataframe with a tide model in
@@ -784,362 +825,3 @@ def model_tides(
             tide_df = tide_df.reindex(output_indices)
 
     return tide_df
-
-
-def _pixel_tides_resample(
-    tides_lowres,
-    ds,
-    resample_method="bilinear",
-    dask_chunks="auto",
-    dask_compute=True,
-):
-    """Resamples low resolution tides modelled by `pixel_tides` into the
-    geobox (e.g. spatial resolution and extent) of the original higher
-    resolution satellite dataset.
-
-    Parameters
-    ----------
-    tides_lowres : xarray.DataArray
-        The low resolution tide modelling data array to be resampled.
-    ds : xarray.Dataset
-        The dataset whose geobox will be used as the template for the
-        resampling operation. This is typically the same satellite
-        dataset originally passed to `pixel_tides`.
-    resample_method : string, optional
-        The resampling method to use. Defaults to "bilinear"; valid
-        options include "nearest", "cubic", "min", "max", "average" etc.
-    dask_chunks : str or tuple, optional
-        Can be used to configure custom Dask chunking for the final
-        resampling step. The default of "auto" will automatically set
-        x/y chunks to match those in `ds` if they exist, otherwise will
-        set x/y chunks that cover the entire extent of the dataset.
-        For custom chunks, provide a tuple in the form `(y, x)`, e.g.
-        `(2048, 2048)`.
-    dask_compute : bool, optional
-        Whether to compute results of the resampling step using Dask.
-        If False, this will return `tides_highres` as a Dask array.
-
-    Returns
-    -------
-    tides_highres, tides_lowres : tuple of xr.DataArrays
-        In addition to `tides_lowres` (see above), a high resolution
-        array of tide heights will be generated matching the
-        exact spatial resolution and extent of `ds`.
-
-    """
-    # Determine spatial dimensions
-    y_dim, x_dim = ds.odc.spatial_dims
-
-    # Convert array to Dask, using no chunking along y and x dims,
-    # and a single chunk for each timestep/quantile and tide model
-    tides_lowres_dask = tides_lowres.chunk({d: None if d in [y_dim, x_dim] else 1 for d in tides_lowres.dims})
-
-    # Automatically set Dask chunks for reprojection if set to "auto".
-    # This will either use x/y chunks if they exist in `ds`, else
-    # will cover the entire x and y dims) so we don't end up with
-    # hundreds of tiny x and y chunks due to the small size of
-    # `tides_lowres` (possible odc.geo bug?)
-    if dask_chunks == "auto":
-        if ds.chunks is not None:
-            if (y_dim in ds.chunks) & (x_dim in ds.chunks):
-                dask_chunks = (ds.chunks[y_dim], ds.chunks[x_dim])
-            else:
-                dask_chunks = ds.odc.geobox.shape
-        else:
-            dask_chunks = ds.odc.geobox.shape
-
-    # Reproject into the GeoBox of `ds` using odc.geo and Dask
-    tides_highres = tides_lowres_dask.odc.reproject(
-        how=ds.odc.geobox,
-        chunks=dask_chunks,
-        resampling=resample_method,
-    ).rename("tide_height")
-
-    # Optionally process and load into memory with Dask
-    if dask_compute:
-        tides_highres.load()
-
-    return tides_highres, tides_lowres
-
-
-def pixel_tides(
-    ds,
-    times=None,
-    resample=True,
-    calculate_quantiles=None,
-    resolution=None,
-    buffer=None,
-    resample_method="bilinear",
-    model="FES2014",
-    dask_chunks="auto",
-    dask_compute=True,
-    **model_tides_kwargs,
-):
-    """Obtain tide heights for each pixel in a dataset by modelling
-    tides into a low-resolution grid surrounding the dataset,
-    then (optionally) spatially resample this low-res data back
-    into the original higher resolution dataset extent and resolution.
-
-    Parameters
-    ----------
-    ds : xarray.Dataset
-        A dataset whose geobox (`ds.odc.geobox`) will be used to define
-        the spatial extent of the low resolution tide modelling grid.
-    times : pandas.DatetimeIndex or list of pandas.Timestamps, optional
-        By default, the function will model tides using the times
-        contained in the `time` dimension of `ds`. Alternatively, this
-        param can be used to model tides for a custom set of times
-        instead. For example:
-        `times=pd.date_range(start="2000", end="2001", freq="5h")`
-    resample : bool, optional
-        Whether to resample low resolution tides back into `ds`'s original
-        higher resolution grid. Set this to `False` if you do not want
-        low resolution tides to be re-projected back to higher resolution.
-    calculate_quantiles : list or np.array, optional
-        Rather than returning all individual tides, low-resolution tides
-        can be first aggregated using a quantile calculation by passing in
-        a list or array of quantiles to compute. For example, this could
-        be used to calculate the min/max tide across all times:
-        `calculate_quantiles=[0.0, 1.0]`.
-    resolution : int, optional
-        The desired resolution of the low-resolution grid used for tide
-        modelling. The default None will create a 5000 m resolution grid
-        if `ds` has a projected CRS (i.e. metre units), or a 0.05 degree
-        resolution grid if `ds` has a geographic CRS (e.g. degree units).
-        Note: higher resolutions do not necessarily provide better
-        tide modelling performance, as results will be limited by the
-        resolution of the underlying global tide model (e.g. 1/16th
-        degree / ~5 km resolution grid for FES2014).
-    buffer : int, optional
-        The amount by which to buffer the higher resolution grid extent
-        when creating the new low resolution grid. This buffering is
-        important as it ensures that ensure pixel-based tides are seamless
-        across dataset boundaries. This buffer will eventually be clipped
-        away when the low-resolution data is re-projected back to the
-        resolution and extent of the higher resolution dataset. To
-        ensure that at least two pixels occur outside of the dataset
-        bounds, the default None applies a 12000 m buffer if `ds` has a
-        projected CRS (i.e. metre units), or a 0.12 degree buffer if
-        `ds` has a geographic CRS (e.g. degree units).
-    resample_method : string, optional
-        If resampling is requested (see `resample` above), use this
-        resampling method when converting from low resolution to high
-        resolution pixels. Defaults to "bilinear"; valid options include
-        "nearest", "cubic", "min", "max", "average" etc.
-    model : string or list of strings
-        The tide model or a list of models used to model tides, as
-        supported by the `pyTMD` Python package. Options include:
-        - "FES2014" (default; pre-configured on DEA Sandbox)
-        - "FES2022"
-        - "TPXO8-atlas"
-        - "TPXO9-atlas-v5"
-        - "EOT20"
-        - "HAMTIDE11"
-        - "GOT4.10"
-    dask_chunks : str or tuple, optional
-        Can be used to configure custom Dask chunking for the final
-        resampling step. The default of "auto" will automatically set
-        x/y chunks to match those in `ds` if they exist, otherwise will
-        set x/y chunks that cover the entire extent of the dataset.
-        For custom chunks, provide a tuple in the form `(y, x)`, e.g.
-        `(2048, 2048)`.
-    dask_compute : bool, optional
-        Whether to compute results of the resampling step using Dask.
-        If False, this will return `tides_highres` as a Dask array.
-    **model_tides_kwargs :
-        Optional parameters passed to the `dea_tools.coastal.model_tides`
-        function. Important parameters include "directory" (used to
-        specify the location of input tide modelling files) and "cutoff"
-        (used to extrapolate modelled tides away from the coast; if not
-        specified here, cutoff defaults to `np.inf`).
-
-    Returns
-    -------
-    If `resample` is False:
-
-        tides_lowres : xr.DataArray
-            A low resolution data array giving either tide heights every
-            timestep in `ds` (if `times` is None), tide heights at every
-            time in `times` (if `times` is not None), or tide height quantiles
-            for every quantile provided by `calculate_quantiles`.
-
-    If `resample` is True:
-
-        tides_highres, tides_lowres : tuple of xr.DataArrays
-            In addition to `tides_lowres` (see above), a high resolution
-            array of tide heights will be generated that matches the
-            exact spatial resolution and extent of `ds`. This will contain
-            either tide heights every timestep in `ds` (if `times` is None),
-            tide heights at every time in `times` (if `times` is not None),
-            or tide height quantiles for every quantile provided by
-            `calculate_quantiles`.
-
-    """
-    from odc.geo.geobox import GeoBox
-
-    # First test if no time dimension and nothing passed to `times`
-    if ("time" not in ds.dims) & (times is None):
-        raise ValueError(
-            "`ds` does not contain a 'time' dimension. Times are required "
-            "for modelling tides: please pass in a set of custom tides "
-            "using the `times` parameter. For example: "
-            "`times=pd.date_range(start='2000', end='2001', freq='5h')`",
-        )
-
-    # If custom times are provided, convert them to a consistent
-    # pandas.DatatimeIndex format
-    if times is not None:
-        if isinstance(times, list):
-            time_coords = pd.DatetimeIndex(times)
-        elif isinstance(times, pd.Timestamp):
-            time_coords = pd.DatetimeIndex([times])
-        else:
-            time_coords = times
-
-    # Otherwise, use times from `ds` directly
-    else:
-        time_coords = ds.coords["time"]
-
-    # Set defaults passed to `model_tides`
-    model_tides_kwargs.setdefault("cutoff", np.inf)
-
-    # Standardise model into a list for easy handling
-    model = [model] if isinstance(model, str) else model
-
-    # Test if no time dimension and nothing passed to `times`
-    if ("time" not in ds.dims) & (times is None):
-        raise ValueError(
-            "`ds` does not contain a 'time' dimension. Times are required "
-            "for modelling tides: please pass in a set of custom tides "
-            "using the `times` parameter. For example: "
-            "`times=pd.date_range(start='2000', end='2001', freq='5h')`",
-        )
-
-    # If custom times are provided, convert them to a consistent
-    # pandas.DatatimeIndex format
-    if times is not None:
-        if isinstance(times, list):
-            time_coords = pd.DatetimeIndex(times)
-        elif isinstance(times, pd.Timestamp):
-            time_coords = pd.DatetimeIndex([times])
-        else:
-            time_coords = times
-
-    # Otherwise, use times from `ds` directly
-    else:
-        time_coords = ds.coords["time"]
-
-    # Determine spatial dimensions
-    y_dim, x_dim = ds.odc.spatial_dims
-
-    # Determine resolution and buffer, using different defaults for
-    # geographic (i.e. degrees) and projected (i.e. metres) CRSs:
-    crs_units = ds.odc.geobox.crs.units[0][0:6]
-    if ds.odc.geobox.crs.geographic:
-        if resolution is None:
-            resolution = 0.05
-        elif resolution > 360:
-            raise ValueError(
-                f"A resolution of greater than 360 was "
-                f"provided, but `ds` has a geographic CRS "
-                f"in {crs_units} units. Did you accidently "
-                f"provide a resolution in projected "
-                f"(i.e. metre) units?",
-            )
-        if buffer is None:
-            buffer = 0.12
-    else:
-        if resolution is None:
-            resolution = 5000
-        elif resolution < 1:
-            raise ValueError(
-                f"A resolution of less than 1 was provided, "
-                f"but `ds` has a projected CRS in "
-                f"{crs_units} units. Did you accidently "
-                f"provide a resolution in geographic "
-                f"(degree) units?",
-            )
-        if buffer is None:
-            buffer = 12000
-
-    # Raise error if resolution is less than dataset resolution
-    dataset_res = ds.odc.geobox.resolution.x
-    if resolution < dataset_res:
-        raise ValueError(
-            f"The resolution of the low-resolution tide "
-            f"modelling grid ({resolution:.2f}) is less "
-            f"than `ds`'s pixel resolution ({dataset_res:.2f}). "
-            f"This can cause extremely slow tide modelling "
-            f"performance. Please select provide a resolution "
-            f"greater than {dataset_res:.2f} using "
-            f"`pixel_tides`'s 'resolution' parameter.",
-        )
-
-    # Create a new reduced resolution tide modelling grid after
-    # first buffering the grid
-    print(f"Creating reduced resolution {resolution} x {resolution} {crs_units} tide modelling array")
-    buffered_geobox = ds.odc.geobox.buffered(buffer)
-    rescaled_geobox = GeoBox.from_bbox(bbox=buffered_geobox.boundingbox, resolution=resolution)
-    rescaled_ds = odc.geo.xr.xr_zeros(rescaled_geobox)
-
-    # Flatten grid to 1D, then add time dimension
-    flattened_ds = rescaled_ds.stack(z=(x_dim, y_dim))
-    flattened_ds = flattened_ds.expand_dims(dim={"time": time_coords.values})
-
-    # Model tides in parallel, returning a pandas.DataFrame
-    tide_df = model_tides(
-        x=flattened_ds[x_dim],
-        y=flattened_ds[y_dim],
-        time=flattened_ds.time,
-        crs=f"EPSG:{ds.odc.geobox.crs.epsg}",
-        model=model,
-        **model_tides_kwargs,
-    )
-
-    # Convert our pandas.DataFrame tide modelling outputs to xarray
-    tides_lowres = (
-        # Rename x and y dataframe indexes to match x and y xarray dims
-        tide_df.rename_axis(["time", x_dim, y_dim])
-        # Add tide model column to dataframe indexes so we can convert
-        # our dataframe to a multidimensional xarray
-        .set_index("tide_model", append=True)
-        # Convert to xarray and select our tide modelling xr.DataArray
-        .to_xarray()
-        .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)
-    )
-
-    # Optionally calculate and return quantiles rather than raw data.
-    # 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)
-
-    # If only one tidal model exists, squeeze out "tide_model" dim
-    if len(tides_lowres.tide_model) == 1:
-        tides_lowres = tides_lowres.squeeze("tide_model")
-
-    # Ensure CRS is present before we apply any resampling
-    tides_lowres = tides_lowres.odc.assign_crs(ds.odc.geobox.crs)
-
-    # Reproject into original high resolution grid
-    if resample:
-        print("Reprojecting tides into original array")
-        tides_highres, tides_lowres = _pixel_tides_resample(
-            tides_lowres,
-            ds,
-            resample_method,
-            dask_chunks,
-            dask_compute,
-        )
-        return tides_highres, tides_lowres
-
-    print("Returning low resolution tide array")
-    return tides_lowres
-
-
-if __name__ == "__main__":  # pragma: no cover
-    pass