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

eo_tides/model.py

@@ -1,19 +1,27 @@
+# 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):
@@ -40,7 +48,12 @@ def _set_directory(directory):
         return directory
 
 
-def list_models(directory=None, show_available=True, show_supported=True, raise_error=False):
+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]]:
     """
     List all tide models available for tide modelling, and
     all models supported by `eo-tides` and `pyTMD`.
@@ -54,7 +67,7 @@ def list_models(directory=None, show_available=True, show_supported=True, raise_
 
     Parameters
     ----------
-    directory : string, optional
+    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.
@@ -66,45 +79,79 @@ def list_models(directory=None, show_available=True, show_supported=True, raise_
     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_models : list
-        A list of alltide models available within `directory`.
-    supported_models : list
+    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`.
     """
+    init()  # Initialize colorama
+
     # 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())
+    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)
+
+    # 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
     if show_available or show_supported:
-        print(f"Tide models available in `{directory}`:")
+        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)
+            model_file = model(directory=directory).elevation(m=m)
+            available_models.append(m)
+
             if show_available:
                 # Mark available models with a green tick
-                print(f" ✅ {m}")
-            available_models.append(m)
+                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}"
+                )
+
+    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}`. "
-            "Verify that you have provided the correct `directory` path, "
+            "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."
+            "to point to the location of your tide model directory?"
         )
         if raise_error:
             raise Exception(warning_text)
@@ -296,10 +343,8 @@ def _model_tides(
 
 
 def _ensemble_model(
-    x,
-    y,
-    crs,
     tide_df,
+    crs,
     ensemble_models,
     ensemble_func=None,
     ensemble_top_n=3,
@@ -313,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
@@ -354,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
@@ -379,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 = (
@@ -461,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
@@ -499,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:
-
-        - "EOT20"
-        - "FES2014"
-        - "FES2022"
-        - "TPXO9-atlas-v5"
-        - "TPXO8-atlas"
-        - "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, 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:
 
@@ -554,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
@@ -570,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
@@ -594,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",
@@ -615,7 +649,7 @@ def model_tides(
 
     """
     # 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)
@@ -652,6 +686,9 @@ def model_tides(
     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"]
 
@@ -767,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
@@ -788,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