Refactor inputs to streamline API across functions (#19)

* First stage of refactoring inputs

* Clean

* Update case study notebook

* Update readme

* Update readme

* Fix plotting order bug

* Add phase tides

* Major refactor to use latest pyTMD, standarise inputs

* Update lockfile

* Fix lockfile

* Update uv version

* Update action.yml

* Update main.yml

.github/actions/setup-python-env/action.yml

@@ -13,7 +13,7 @@ inputs:
   uv-version:
     description: "uv version to use"
     required: true
-    default: "0.4.18"
+    default: "0.4.27"
 
 runs:
   using: "composite"

.github/workflows/main.yml

@@ -5,7 +5,7 @@ on:
     branches:
       - main
   pull_request:
-    types: [opened, synchronize, reopened, ready_for_review]
+    types: [opened, synchronize, reopened]
 
 env:
   EO_TIDES_TIDE_MODELS: ./tests/data/tide_models

Makefile

@@ -85,6 +85,8 @@ build-and-publish: build publish ## Build and publish.
 docs-test: ## Test if documentation can be built without warnings or errors
 	@uv run mkdocs build -s
 
+# On Sandbox: uv run mkdocs serve -a localhost:8000
+# https://app.sandbox.dea.ga.gov.au/user/[email protected]/proxy/8000/eo-tides/
 .PHONY: docs
 docs: ## Build and serve the documentation
 	@uv run mkdocs serve

docs/migration.md

@@ -34,6 +34,21 @@ Renamed for consistency with `model_tides` and `pixel_tides`.
 
     Update references to `tidal_tag` to `tag_tides`.
 
+## `ds` param renamed to `data`, now accepts `GeoBox`
+
+The `ds` param in all satellite data functions (`tag_tides`, `pixel_tides`, `tide_stats`, `pixel_tides`) has been updated to accept either `xarray.Dataset`, `xarray.DataArray` or a `odc.geo.geobox.GeoBox`. To account for this change, the `ds` param has been renamed to a more generic name `data`.
+
+!!! tip "Action required"
+
+    Update:
+    ```
+    tag_tides(ds=your_data)
+    ```
+    To:
+    ```
+    tag_tides(data=your_data)
+    ```
+
 ### `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.
@@ -42,16 +57,16 @@ The `tag_tides` function now returns an `xarray.DataArray` output containing tid
 
     Update:
     ```
-    ds = tag_tides(ds, ...)
+    data = tag_tides(data, ...)
     ```
     To:
     ```
-    ds["tide_height"] = tag_tides(ds, ...)
+    data["tide_height"] = tag_tides(data, ...)
     ```
 
 ### `pixel_tides` only returns a single array
 
-The `pixel_tides` function has been updated to only ever return a single array as an output: a high-resolution tide height array matching the resolution of the input `ds` by default, and a low-resolution tide height array if `resample=False`.
+The `pixel_tides` function has been updated to only ever return a single array as an output: a high-resolution tide height array matching the resolution of the input `data` by default, and a low-resolution tide height array if `resample=False`.
 
 !!! tip "Action required"
 

docs/notebooks/Case_study_intertidal.ipynb

@@ -410,7 +410,7 @@
    ],
    "source": [
     "ds[\"tide_height\"] = tag_tides(\n",
-    "    ds=ds,\n",
+    "    data=ds,\n",
     "    model=tide_model,\n",
     "    directory=directory,\n",
     ")"
@@ -502,7 +502,7 @@
    ],
    "source": [
     "tide_stats(\n",
-    "    ds=ds,\n",
+    "    data=ds,\n",
     "    model=tide_model,\n",
     "    directory=directory,\n",
     ");"

docs/notebooks/Satellite_data.ipynb

@@ -292,7 +292,7 @@
     "from eo_tides.eo import tag_tides\n",
     "\n",
     "tides_da = tag_tides(\n",
-    "    ds=ds,\n",
+    "    data=ds,\n",
     "    directory=directory,\n",
     ")\n",
     "\n",
@@ -554,7 +554,7 @@
     "\n",
     "# Model tides spatially\n",
     "tides_lowres = pixel_tides(\n",
-    "    ds=ds,\n",
+    "    data=ds,\n",
     "    resample=False,\n",
     "    directory=directory,\n",
     ")\n",
@@ -665,7 +665,7 @@
    "source": [
     "# Model tides spatially\n",
     "tides_highres = pixel_tides(\n",
-    "    ds=ds,\n",
+    "    data=ds,\n",
     "    resample=True,\n",
     "    directory=directory,\n",
     ")\n",
@@ -820,7 +820,7 @@
    "source": [
     "# Model tides spatially\n",
     "tides_highres_quantiles = pixel_tides(\n",
-    "    ds=ds,\n",
+    "    data=ds,\n",
     "    calculate_quantiles=(0, 0.5, 1),\n",
     "    directory=directory,\n",
     ")\n",
@@ -897,7 +897,7 @@
     "\n",
     "# Model tides spatially\n",
     "tides_highres = pixel_tides(\n",
-    "    ds, \n",
+    "    data=ds, \n",
     "    times=custom_times,\n",
     "    directory=directory,\n",
     ")\n",

docs/notebooks/Tide_statistics.ipynb

@@ -189,7 +189,7 @@
     "from eo_tides.stats import tide_stats\n",
     "\n",
     "statistics_df = tide_stats(\n",
-    "    ds_s2,\n",
+    "    data=ds_s2,\n",
     "    directory=directory,\n",
     ")\n"
    ]
@@ -358,7 +358,7 @@
    ],
    "source": [
     "statistics_df = tide_stats(\n",
-    "    ds_s1,\n",
+    "    data=ds_s1,\n",
     "    directory=directory,\n",
     ")\n"
    ]
@@ -458,7 +458,7 @@
    ],
    "source": [
     "statistics_df = tide_stats(\n",
-    "    ds_all,\n",
+    "    data=ds_all,\n",
     "    plot_col=\"satellite_name\",\n",
     "    directory=directory,\n",
     ")\n"
@@ -560,7 +560,7 @@
     "from eo_tides.stats import pixel_stats\n",
     "\n",
     "stats_ds = pixel_stats(\n",
-    "    ds=ds_s2,\n",
+    "    data=ds_s2,\n",
     "    directory=directory,\n",
     ")\n",
     "print(stats_ds)"

eo_tides/__init__.py

@@ -37,9 +37,11 @@
 __all__ = [
     "list_models",
     "model_tides",
+    "phase_tides",
     "tag_tides",
     "pixel_tides",
     "tide_stats",
+    "pixel_stats",
     "idw",
     "eval_metrics",
     "load_gauge_gesla",