eo-tides 0.1.1__tar.gz → 0.2.0__tar.gz

{eo_tides-0.1.1 → eo_tides-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: eo-tides
-Version: 0.1.1
+Version: 0.2.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/
@@ -29,7 +29,7 @@ Requires-Dist: numpy>=1.26.0
 Requires-Dist: odc-geo>=0.4.7
 Requires-Dist: pandas>=2.2.0
 Requires-Dist: pyproj>=3.6.1
-Requires-Dist: pyTMD==2.1.6
+Requires-Dist: pyTMD==2.1.7
 Requires-Dist: scikit-learn>=1.4.0
 Requires-Dist: scipy>=1.11.2
 Requires-Dist: shapely>=2.0.6
@@ -68,9 +68,9 @@ These tools can be applied to petabytes of freely available satellite data (e.g.
 
 ## Highlights
 
-- 🌊 Model tides from multiple global ocean tide models in parallel, and return tide heights in standardised `pandas.DataFrame` format for further analysis
+- 🌊 Model tide heights and phases (e.g. high, low, ebb, flow) from multiple global ocean tide models in parallel, and return a `pandas.DataFrame` 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
+- 🌐 Model tides for every individual satellite pixel through time, producing three-dimensional "tide height" `xarray`-format datacubes that can be integrated with satellite data
 - 📈 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 -->
@@ -103,6 +103,12 @@ 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
 ```
 
+In addition, please consider also citing the underlying [`pyTMD` Python package](https://pytmd.readthedocs.io/en/latest/) which powers the tide modelling functionality behind `eo-tides`:
+
+```
+Sutterley, T. C., Alley, K., Brunt, K., Howard, S., Padman, L., Siegfried, M. (2017) pyTMD: Python-based tidal prediction software. 10.5281/zenodo.5555395
+```
+
 ## Acknowledgements
 
 For a full list of acknowledgements, refer to [Citations and Credits](https://geoscienceaustralia.github.io/eo-tides/credits/).

{eo_tides-0.1.1 → eo_tides-0.2.0}/README.md

@@ -24,9 +24,9 @@ These tools can be applied to petabytes of freely available satellite data (e.g.
 
 ## Highlights
 
-- 🌊 Model tides from multiple global ocean tide models in parallel, and return tide heights in standardised `pandas.DataFrame` format for further analysis
+- 🌊 Model tide heights and phases (e.g. high, low, ebb, flow) from multiple global ocean tide models in parallel, and return a `pandas.DataFrame` 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
+- 🌐 Model tides for every individual satellite pixel through time, producing three-dimensional "tide height" `xarray`-format datacubes that can be integrated with satellite data
 - 📈 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 -->
@@ -59,6 +59,12 @@ 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
 ```
 
+In addition, please consider also citing the underlying [`pyTMD` Python package](https://pytmd.readthedocs.io/en/latest/) which powers the tide modelling functionality behind `eo-tides`:
+
+```
+Sutterley, T. C., Alley, K., Brunt, K., Howard, S., Padman, L., Siegfried, M. (2017) pyTMD: Python-based tidal prediction software. 10.5281/zenodo.5555395
+```
+
 ## Acknowledgements
 
 For a full list of acknowledgements, refer to [Citations and Credits](https://geoscienceaustralia.github.io/eo-tides/credits/).

{eo_tides-0.1.1 → eo_tides-0.2.0}/eo_tides/__init__.py

@@ -28,8 +28,8 @@ validation : Load observed tide gauge data to validate modelled tides
 
 # Import commonly used functions for convenience
 from .eo import pixel_tides, tag_tides
-from .model import list_models, model_tides
-from .stats import tide_stats
+from .model import list_models, model_phases, model_tides
+from .stats import pixel_stats, tide_stats
 from .utils import idw
 from .validation import eval_metrics, load_gauge_gesla
 
@@ -37,9 +37,11 @@ from .validation import eval_metrics, load_gauge_gesla
 __all__ = [
     "list_models",
     "model_tides",
+    "model_phases",
     "tag_tides",
     "pixel_tides",
     "tide_stats",
+    "pixel_stats",
     "idw",
     "eval_metrics",
     "load_gauge_gesla",

{eo_tides-0.1.1 → eo_tides-0.2.0}/eo_tides/eo.py

@@ -2,9 +2,11 @@
 from __future__ import annotations
 
 import os
+import textwrap
 import warnings
 from typing import TYPE_CHECKING
 
+import numpy as np
 import odc.geo.xr
 import pandas as pd
 import xarray as xr
@@ -12,16 +14,94 @@ from odc.geo.geobox import GeoBox
 
 # Only import if running type checking
 if TYPE_CHECKING:
-    import numpy as np
+    import datetime
 
-from .model import model_tides
+    from odc.geo import Shape2d
+
+from .model import DatetimeLike, _standardise_time, model_tides
+
+
+def _resample_chunks(
+    data: xr.DataArray | xr.Dataset | GeoBox,
+    dask_chunks: tuple | None = None,
+) -> tuple | Shape2d:
+    """
+    Automatically return optimised dask chunks
+    for reprojection with `_pixel_tides_resample`.
+    Use entire image if GeoBox or if no default
+    chunks; use existing chunks if they exist.
+    """
+
+    # If dask_chunks is provided, return directly
+    if dask_chunks is not None:
+        return dask_chunks
+
+    # If data is a GeoBox, return its shape
+    if isinstance(data, GeoBox):
+        return data.shape
+
+    # if data has chunks, then return just spatial chunks
+    if data.chunks is not None:
+        y_dim, x_dim = data.odc.spatial_dims
+        return data.chunks[y_dim], data.chunks[x_dim]
+
+    # if data has no chunks, then return entire image shape
+    return data.odc.geobox.shape
+
+
+def _standardise_inputs(
+    data: xr.DataArray | xr.Dataset | GeoBox,
+    time: DatetimeLike | None,
+) -> tuple[GeoBox, np.ndarray | None]:
+    """
+    Takes an xarray or GeoBox input and an optional custom times,
+    and returns a standardised GeoBox and times (usually an
+    array, but possibly None).
+    """
+
+    # If `data` is an xarray object, extract its GeoBox and time
+    if isinstance(data, (xr.DataArray, xr.Dataset)):
+        # Try to extract GeoBox
+        try:
+            gbox: GeoBox = data.odc.geobox
+        except AttributeError:
+            error_msg = """
+            Cannot extract a valid GeoBox for `data`. This is required for
+            extracting details about `data`'s CRS and spatial location.
+
+            Import `odc.geo.xr` then run `data = data.odc.assign_crs(crs=...)`
+            to prepare your data before passing it to this function.
+            """
+            raise Exception(textwrap.dedent(error_msg).strip())
+
+        # Use custom time by default if provided; otherwise try and extract from `data`
+        if time is not None:
+            time = _standardise_time(time)
+        elif "time" in data.dims:
+            time = np.asarray(data.coords["time"].values)
+        else:
+            raise ValueError("`data` does not have a 'time' dimension, and no custom times were provided via `time`.")
+
+    # If `data` is a GeoBox, use it directly; raise an error if no time was provided
+    elif isinstance(data, GeoBox):
+        gbox = data
+        if time is not None:
+            time = _standardise_time(time)
+        else:
+            raise ValueError("If `data` is a GeoBox, custom times must be provided via `time`.")
+
+    # Raise error if no valid inputs were provided
+    else:
+        raise TypeError("`data` must be an xarray.DataArray, xarray.Dataset, or odc.geo.geobox.GeoBox.")
+
+    return gbox, time
 
 
 def _pixel_tides_resample(
     tides_lowres,
-    ds,
+    gbox,
     resample_method="bilinear",
-    dask_chunks="auto",
+    dask_chunks=None,
     dask_compute=True,
 ):
     """Resamples low resolution tides modelled by `pixel_tides` into the
@@ -32,56 +112,39 @@ def _pixel_tides_resample(
     ----------
     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`.
+    gbox : GeoBox
+        The GeoBox to use as the template for the resampling operation.
+        This is typically comes from the same satellite dataset originally
+        passed to `pixel_tides` (e.g. `data.odc.geobox`).
     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
+    dask_chunks : tuple of float, 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)`.
+        resampling step. 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.
+        If False, this will return `tides_highres` as a lazy loaded
+        Dask-enabled 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`.
+    tides_highres : xr.DataArray
+        A high resolution array of tide heights matching the exact
+        spatial resolution and extent of `gbox`.
 
     """
     # Determine spatial dimensions
-    y_dim, x_dim = ds.odc.spatial_dims
+    y_dim, x_dim = gbox.dimensions
 
     # 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
+    # Reproject into the pixel grid of `gbox` using odc.geo and Dask
     tides_highres = tides_lowres_dask.odc.reproject(
-        how=ds.odc.geobox,
+        how=gbox,
         chunks=dask_chunks,
         resampling=resample_method,
     ).rename("tide_height")
@@ -94,7 +157,8 @@ def _pixel_tides_resample(
 
 
 def tag_tides(
-    ds: xr.Dataset | xr.DataArray,
+    data: xr.Dataset | xr.DataArray | GeoBox,
+    time: DatetimeLike | None = None,
     model: str | list[str] = "EOT20",
     directory: str | os.PathLike | None = None,
     tidepost_lat: float | None = None,
@@ -104,7 +168,7 @@ def tag_tides(
     """
     Model tide heights for every timestep in a multi-dimensional
     dataset, and return a new `tide_height` array that can
-    be used to "tag" each observation with tide data.
+    be used to "tag" each observation with tide heights.
 
     The function models tides at the centroid of the dataset
     by default, but a custom tidal modelling location can
@@ -122,15 +186,23 @@ def tag_tides(
 
     Parameters
     ----------
-    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.
+    data : xarray.Dataset or xarray.DataArray or odc.geo.geobox.GeoBox
+        A multi-dimensional dataset or GeoBox pixel grid that will
+        be used to define the tide modelling location. If `data`
+        is an xarray object, it should include a "time" dimension.
+        If no "time" dimension exists or if `data` is a GeoBox,
+        then times must be passed using the `time` parameter.
+    time : DatetimeLike, optional
+        By default, tides will be modelled using times from the
+        "time" dimension of `data`. Alternatively, this param can
+        be used to provide a custom set of times. Accepts any format
+        that can be converted by `pandas.to_datetime()`. For example:
+        `time=pd.date_range(start="2000", end="2001", freq="5h")`
     model : str or list of str, optional
-        The tide model (or models) to use to model tides. If a list is
-        provided, a new "tide_model" dimension will be added to `ds`.
-        Defaults to "EOT20"; for a full list of available/supported
-        models, run `eo_tides.model.list_models`.
+        The tide model (or models) used to model tides. If a list is
+        provided, a new "tide_model" dimension will be added to the
+        `xarray.DataArray` outputs. 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
@@ -151,23 +223,18 @@ def tag_tides(
 
     Returns
     -------
-    ds : xr.Dataset
-        The original `xarray.Dataset` with a new `tide_height` variable
-        giving the height of the tide (and optionally, its ebb-flow phase)
-        for each timestep in the data.
-
+    tides_da : xr.DataArray
+        A one-dimensional tide height array. This will contain either
+        tide heights for every timestep in `data`, or for every time in
+        `times` if provided.
     """
-    # Only datasets are supported
-    if not isinstance(ds, xr.Dataset):
-        raise TypeError("Input must be an xarray.Dataset, not an xarray.DataArray or other data type.")
-
-    # Standardise model into a list for easy handling. and verify only one
+    # Standardise data inputs, time and models
+    gbox, time_coords = _standardise_inputs(data, time)
     model = [model] if isinstance(model, str) else model
 
-    # If custom tide modelling locations are not provided, use the
-    # dataset centroid
+    # If custom tide posts are not provided, use dataset centroid
     if tidepost_lat is None or tidepost_lon is None:
-        lon, lat = ds.odc.geobox.geographic_extent.centroid.coords[0]
+        lon, lat = gbox.geographic_extent.centroid.coords[0]
         print(f"Setting tide modelling location from dataset centroid: {lon:.2f}, {lat:.2f}")
     else:
         lon, lat = tidepost_lon, tidepost_lat
@@ -177,7 +244,7 @@ def tag_tides(
     tide_df = model_tides(
         x=lon,  # type: ignore
         y=lat,  # type: ignore
-        time=ds.time,
+        time=time_coords,
         model=model,
         directory=directory,
         crs="EPSG:4326",
@@ -195,43 +262,19 @@ 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",
-    #     })
-
     # Convert to xarray format
-    tide_xr = tide_df.reset_index().set_index(["time", "tide_model"]).drop(["x", "y"], axis=1).tide_height.to_xarray()
+    tides_da = 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")
+    if len(tides_da.tide_model) == 1:
+        tides_da = tides_da.squeeze("tide_model")
 
-    return tide_xr
+    return tides_da
 
 
 def pixel_tides(
-    ds: xr.Dataset | xr.DataArray,
-    times=None,
+    data: xr.Dataset | xr.DataArray | GeoBox,
+    time: DatetimeLike | None = None,
     model: str | list[str] = "EOT20",
     directory: str | os.PathLike | None = None,
     resample: bool = True,
@@ -239,7 +282,7 @@ def pixel_tides(
     resolution: float | None = None,
     buffer: float | None = None,
     resample_method: str = "bilinear",
-    dask_chunks: str | tuple[float, float] = "auto",
+    dask_chunks: tuple[float, float] | None = None,
     dask_compute: bool = True,
     **model_tides_kwargs,
 ) -> xr.DataArray:
@@ -250,10 +293,9 @@ def pixel_tides(
     This function models tides into a low-resolution tide
     modelling grid covering the spatial extent of the input
     data (buffered to reduce potential edge effects). These
-    modelled tides are then (optionally) resampled back into
-    the original higher resolution dataset's extent and
-    resolution - resulting in a modelled tide height for every
-    pixel through time.
+    modelled tides can then be resampled back into the original
+    higher resolution dataset's extent and resolution to
+    produce a modelled tide height for every pixel through time.
 
     This function uses the parallelised `model_tides` function
     under the hood. It supports all tidal models supported by
@@ -273,15 +315,18 @@ def pixel_tides(
 
     Parameters
     ----------
-    ds : xarray.Dataset or xarray.DataArray
-        A multi-dimensional dataset (e.g. "x", "y", "time") that will
-        be used to define the tide modelling grid.
-    times : pd.DatetimeIndex or list of pd.Timestamp, 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")`
+    data : xarray.Dataset or xarray.DataArray or odc.geo.geobox.GeoBox
+        A multi-dimensional dataset or GeoBox pixel grid that will
+        be used to define the spatial tide modelling grid. If `data`
+        is an xarray object, it should include a "time" dimension.
+        If no "time" dimension exists or if `data` is a GeoBox,
+        then times must be passed using the `time` parameter.
+    time : DatetimeLike, optional
+        By default, tides will be modelled using times from the
+        "time" dimension of `data`. Alternatively, this param can
+        be used to provide a custom set of times. Accepts any format
+        that can be converted by `pandas.to_datetime()`. For example:
+        `time=pd.date_range(start="2000", end="2001", freq="5h")`
     model : str or list of str, optional
         The tide model (or models) used to model tides. If a list is
         provided, a new "tide_model" dimension will be added to the
@@ -295,7 +340,7 @@ def pixel_tides(
         model that match the structure required by `pyTMD`
         (<https://geoscienceaustralia.github.io/eo-tides/setup/>).
     resample : bool, optional
-        Whether to resample low resolution tides back into `ds`'s original
+        Whether to resample low resolution tides back into `data`'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 : tuple of float or numpy.ndarray, optional
@@ -307,38 +352,38 @@ def pixel_tides(
     resolution : float, 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).
+        if `data` has a projected CRS (i.e. metre units), or a 0.05 degree
+        resolution grid if `data` 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 : float, 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
+        when creating the new low resolution grid. This buffering
+        ensures that modelled tides are seamless across analysis
+        boundaries. This buffer is eventually be clipped away when
+        the low-resolution modelled tides are re-projected back to the
+        original resolution and extent of `data`. To ensure that at least
+        two low-resolution grid pixels occur outside of the dataset
+        bounds, the default None applies a 12000 m buffer if `data` has a
         projected CRS (i.e. metre units), or a 0.12 degree buffer if
-        `ds` has a geographic CRS (e.g. degree units).
+        `data` has a geographic CRS (e.g. degree units).
     resample_method : str, 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.
-    dask_chunks : str or tuple of float, optional
+    dask_chunks : tuple of float, 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.
+        resampling step. By default, chunks will be automatically set
+        to match y/x chunks from `data` if they exist; otherwise chunks
+        will be chosen to cover the entire y/x 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.
+        If False, `tides_highres` will be returned as a Dask array.
     **model_tides_kwargs :
         Optional parameters passed to the `eo_tides.model.model_tides`
         function. Important parameters include `cutoff` (used to
@@ -348,54 +393,34 @@ def pixel_tides(
     Returns
     -------
     tides_da : xr.DataArray
-        If `resample=True` (default), a high-resolution array
-        of tide heights matching the exact spatial resolution and
-        extents 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
+        A three-dimensional tide height array.
+        If `resample=True` (default), a high-resolution array of tide
+        heights will be returned that matches the exact spatial resolution
+        and extents of `data`. This will contain either tide heights for
+        every timestep in `data` (or in `times` if provided), or tide height
         quantiles for every quantile provided by `calculate_quantiles`.
         If `resample=False`, results for the intermediate low-resolution
         tide modelling grid will be returned instead.
     """
-    # 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"]
-
-    # Standardise model into a list for easy handling
+    # Standardise data inputs, time and models
+    gbox, time_coords = _standardise_inputs(data, time)
+    dask_chunks = _resample_chunks(data, dask_chunks)
     model = [model] if isinstance(model, str) else model
 
     # Determine spatial dimensions
-    y_dim, x_dim = ds.odc.spatial_dims
+    y_dim, x_dim = gbox.dimensions
 
     # 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:
+    assert gbox.crs is not None
+    crs_units = gbox.crs.units[0][0:6]
+    if gbox.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"provided, but `data` has a geographic CRS "
                 f"in {crs_units} units. Did you accidently "
                 f"provide a resolution in projected "
                 f"(i.e. metre) units?",
@@ -408,7 +433,7 @@ def pixel_tides(
         elif resolution < 1:
             raise ValueError(
                 f"A resolution of less than 1 was provided, "
-                f"but `ds` has a projected CRS in "
+                f"but `data` has a projected CRS in "
                 f"{crs_units} units. Did you accidently "
                 f"provide a resolution in geographic "
                 f"(degree) units?",
@@ -417,12 +442,12 @@ def pixel_tides(
             buffer = 12000
 
     # Raise error if resolution is less than dataset resolution
-    dataset_res = ds.odc.geobox.resolution.x
+    dataset_res = gbox.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"than `data`'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 "
@@ -432,20 +457,20 @@ def pixel_tides(
     # 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)
+    buffered_geobox = gbox.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})
+    flattened_ds = flattened_ds.expand_dims(dim={"time": time_coords})
 
     # 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}",
+        crs=f"EPSG:{gbox.crs.epsg}",
         model=model,
         directory=directory,
         **model_tides_kwargs,
@@ -480,14 +505,14 @@ def pixel_tides(
         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)
+    tides_lowres = tides_lowres.odc.assign_crs(gbox.crs)
 
     # Reproject into original high resolution grid
     if resample:
         print("Reprojecting tides into original resolution")
         tides_highres = _pixel_tides_resample(
             tides_lowres,
-            ds,
+            gbox,
             resample_method,
             dask_chunks,
             dask_compute,