Update and publish ensemble tide modelling functionality

docs/changelog.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## v0.3.2 (upcoming)
+
+### New features
+
+- Publishes ensemble tide modelling code for combining multiple global ocean tide models into a single locally optimised ensemble tide model using external model ranking data (e.g. satellite altimetry or NDWI-tide correlations along the coastline)
+  - Update ensemble code to latest version that includes FES2022, GOT5.6 and TPXO10
+  - Make ensemble model calculation function a top level function (i.e. rename from `_ensemble_model` to `ensemble_tides`)
+  - Load tide model ranking points from external flatgeobuff format file for faster cloud access
+- Make buffer distance applied when cropping model files configurable via the `crop_buffer` param, with a default of 5 degrees
+- Reorder `model_tides` params to provide more logical flow and move more common params like `mode`, `output_format` and `output_units` higher
+
+### Bug fixes
+
+- Fix warnings from `load_gauge_gesla` function
+
 ## v0.3.1 (2024-11-15)
 
 ### New features

docs/migration.md

@@ -49,6 +49,21 @@ The `ds` param in all satellite data functions (`tag_tides`, `pixel_tides`, `tid
     tag_tides(data=your_data)
     ```
 
+## `times` param renamed to `time`, accepts any format supported by `pandas.to_datetime()`
+
+The `times` parameter has been renamed to `time`, and updated to more flexibly accept any time format that can be converted by `pandas.to_datetime()`; e.g. `np.ndarray[datetime64]`, `pd.DatetimeIndex`, `pd.Timestamp`, `datetime.datetime` and strings (e.g. `"2020-01-01 23:00"`). For example: `time=pd.date_range(start="2000", end="2001", freq="5h")`.
+
+!!! tip "Action required"
+
+    Update:
+    ```
+    model_tides(..., times=...)
+    ```
+    To:
+    ```
+    model_tides(..., time=...)
+    ```
+
 ### `tag_tides` now returns an array instead of updating data in-place
 
 The `tag_tides` function now returns an `xarray.DataArray` output containing tide heights, rather than appending tide height data to the original input dataset in-place. This change provides better consistency with `pixel_tides`, which also returns an array of tide heights.

eo_tides/__init__.py

@@ -28,7 +28,7 @@
 
 # Import commonly used functions for convenience
 from .eo import pixel_tides, tag_tides
-from .model import model_phases, model_tides
+from .model import ensemble_tides, model_phases, model_tides
 from .stats import pixel_stats, tide_stats
 from .utils import clip_models, idw, list_models
 from .validation import eval_metrics, load_gauge_gesla
@@ -38,6 +38,7 @@
     "list_models",
     "model_tides",
     "model_phases",
+    "ensemble_tides",
     "tag_tides",
     "pixel_tides",
     "tide_stats",

eo_tides/eo.py

@@ -39,7 +39,7 @@ def _resample_chunks(
         return data.shape
 
     # if data has chunks, then return just spatial chunks
-    if data.chunks is not None:
+    if data.chunks:
         y_dim, x_dim = data.odc.spatial_dims
         return data.chunks[y_dim], data.chunks[x_dim]
 
@@ -197,10 +197,12 @@ def tag_tides(
         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
-        `xarray.DataArray` outputs. Defaults to "EOT20"; for a full
-        list of available/supported models, run `eo_tides.model.list_models`.
+        The tide model (or list of models) to use to model tides.
+        If a list is provided, a new "tide_model" dimension will be
+        added to the `xarray.DataArray` outputs. Defaults to "EOT20";
+        specify "all" to use all models available in `directory`.
+        For a full list of available and 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
@@ -326,10 +328,12 @@ def pixel_tides(
         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
-        `xarray.DataArray` outputs. Defaults to "EOT20"; for a full
-        list of available/supported models, run `eo_tides.model.list_models`.
+        The tide model (or list of models) to use to model tides.
+        If a list is provided, a new "tide_model" dimension will be
+        added to the `xarray.DataArray` outputs. Defaults to "EOT20";
+        specify "all" to use all models available in `directory`.
+        For a full list of available and 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