Add DTU23, minor docs updates (#47)

* Add DTU23, docs updates * Update changelog * Formatting * Update generated PDF * Update notebook documentation * Update generated PDF * Minor wording * Update generated PDF * Test notebook outputs * Update generated PDF * Update main.yml * Update generated PDF * Re-run all notebooks * Update generated PDF * Update changelog * Update uv.lock * Upgrade pyTMD version --------- Co-authored-by: robbibt <[email protected]>
GeoscienceAustralia · Feb 11, 2025 · 935179c · 935179c
1 parent 5491eb8
commit 935179c
Show file tree

Hide file tree

Showing 15 changed files with 1,057 additions and 881 deletions.
diff --git a/README.md b/README.md
@@ -41,6 +41,7 @@ These tools can be applied to petabytes of freely available satellite data (e.g.
 - [TOPEX/POSEIDON global tide models](https://www.tpxo.net/global) (TPXO10, TPXO9, TPXO8)
 - [Global Ocean Tide models](https://doi.org/10.1002/2016RG000546) (GOT5.6, GOT5.5, GOT4.10, GOT4.8, GOT4.7)
 - [Hamburg direct data Assimilation Methods for Tides models](https://doi.org/10.1002/2013JC009766) (HAMTIDE11)
+- [Technical University of Denmark tide models](https://doi.org/10.11583/DTU.23828874) (DTU23)
 
 For instructions on how to set up these models for use in `eo-tides`, refer to [Setting up tide models](setup.md).
 

diff --git a/docs/assets/dtu23_download.jpg b/docs/assets/dtu23_download.jpg
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -1,5 +1,13 @@
 # Changelog
 
+## v0.6.0 (upcoming)
+
+### New features
+
+- Added `return_phases` parameter to `eo_tides.eo.tag_tides`, which will return a dataframe containing tide phase information for each satellite observation
+- Added support for [Technical University of Denmark tide models](https://doi.org/10.11583/DTU.23828874) (DTU23)
+- Minor docs improvements, updates for new FES2022 data format
+
 ## v0.5.0
 
 ### New features

diff --git a/docs/index.md b/docs/index.md
@@ -35,6 +35,7 @@ These tools can be applied to petabytes of freely available satellite data (e.g.
 - [TOPEX/POSEIDON global tide models](https://www.tpxo.net/global) (TPXO10, TPXO9, TPXO8)
 - [Global Ocean Tide models](https://doi.org/10.1002/2016RG000546) (GOT5.6, GOT5.5, GOT4.10, GOT4.8, GOT4.7)
 - [Hamburg direct data Assimilation Methods for Tides models](https://doi.org/10.1002/2013JC009766) (HAMTIDE11)
+- [Technical University of Denmark tide models](https://doi.org/10.11583/DTU.23828874) (DTU23)
 
 For instructions on how to set up these models for use in `eo-tides`, refer to [Setting up tide models](setup.md).
 

diff --git a/docs/notebooks/Case_study_intertidal.ipynb b/docs/notebooks/Case_study_intertidal.ipynb
diff --git a/docs/notebooks/Model_tides.ipynb b/docs/notebooks/Model_tides.ipynb
diff --git a/docs/notebooks/Satellite_data.ipynb b/docs/notebooks/Satellite_data.ipynb
diff --git a/docs/notebooks/Tide_statistics.ipynb b/docs/notebooks/Tide_statistics.ipynb
diff --git a/docs/notebooks/Validating_tides.ipynb b/docs/notebooks/Validating_tides.ipynb
diff --git a/docs/setup.md b/docs/setup.md
@@ -72,21 +72,23 @@ Follow the guides below for some of the most commonly used global ocean tide mod
 
         ![image](assets/fes_ftp.jpg)
 
-    7. Navigate to `/auxiliary/tide_model/`, and download the contents of one or more of the following directories:
+    7. Navigate to `/auxiliary/tide_model/`, and download the contents of one of the following FTP directory:
 
-        - `fes2022b/ocean_tide/`
-        - `fes2022b/ocean_tide_extrapolated/`
+    - `fes2022b/ocean_tide_20241025/` (if using standard model data)
+    - `fes2022b/ocean_tide_extrapolated/` (if using extrapolated model data)
 
-        !!! tip
+    !!! tip
 
-            The "extrapolated" version of FES models have been extended inland using a simple "nearest" extrapolation method to ensure data coverage across the entire coastal zone. This can be useful for ensuring you always return a modelled tide, but can also introduce uncertainty into your modelling (particularly in complex regions such as narrow peninsulas or inlets/embayments).
+        The "extrapolated" version of FES models have been extended inland using a simple "nearest" extrapolation method to ensure data coverage across the entire coastal zone. This can be useful for ensuring you always return a modelled tide, but can also introduce uncertainty into your modelling (particularly in complex regions such as narrow peninsulas or inlets/embayments).
 
-    8. Create new nested directories inside your [tide model directory](#setting-up-a-tide-model-directory) called `fes2022b/ocean_tide/` (if using standard model data) or `fes2022b/ocean_tide_extrapolated/` (if using extrapolated model data) to store the FES2022 model files.
+    8. Create a new nested folder inside your [tide model directory](#setting-up-a-tide-model-directory) called either `fes2022b/ocean_tide_20241025/` (if using standard model data) or `fes2022b/ocean_tide_extrapolated/` (if using extrapolated model data) to store your dowloaded files.
 
-    9. Extract your `...nc.xz` files into this directory (e.g. `tar -xf m2_fes2022.nc.xz`). You should end up with the following directory structure containing the extracted NetCDF files:
+    9. Copy your downloaded files into your new tide model directory folder, then uncompress each compressed `*.nc.xz` file (e.g. `xz -dk *.nc.xz`).
+
+    You should end up with the following directory structure containing uncompressed `.nc`-format NetCDF files:
 
         ```
-        tide_models/fes2022b/ocean_tide/
+        tide_models/fes2022b/ocean_tide_20241025/
            |- 2n2_fes2022.nc
            |- ...
            |- t2_fes2022.nc
@@ -218,6 +220,28 @@ Follow the guides below for some of the most commonly used global ocean tide mod
            |- u_s2_tpxo9_atlas_30_v5.nc
         ```
 
+??? note "DTU Technical University of Denmark tide models"
+
+    ### DTU Technical University of Denmark tide models
+
+    1. Visit [DTU23 Global Ocean Tide model (DTU23_OceanTide)](https://data.dtu.dk/articles/dataset/DTU23_Global_Ocean_Tide_model_DTU23_OceanTide_/23828874)
+    2. Download `DTU23_OceanTide.zip`
+
+    ![image](assets/dtu23_download.jpg)
+
+    3. Create a new directory inside your [tide model directory](#setting-up-a-tide-model-directory) called `DTU23_OceanTide` to store the DTU23 model files.
+    4. Extract your zipped model files (e.g. `DTU23_OceanTide.zip`) into this new directory.
+    5. Uncompress all compressed `*.d.gz` format files inside the `DTU23` folder (e.g. `gunzip -dk *.gz` from a terminal).
+
+    You should end up with the following directory structure containing uncompressed `.d`-format files:
+
+        ```
+        tide_models/DTU23_OceanTide/DTU23/
+           |- K1_DTU23.d
+           |- ...
+           |- S2_DTU23.d
+        ```
+
 !!! tip
 
     To allow you to improve tide modelling performance by clipping your tide model files ([see below](#clipping-model-files-to-improve-performance)), we recommend downloading NetCDF-format versions of tide models wherever possible.

diff --git a/eo_tides/eo.py b/eo_tides/eo.py
@@ -189,6 +189,7 @@ def tag_tides(
     - 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)
+    - Technical University of Denmark tide models (DTU23)
 
     Parameters
     ----------
@@ -210,7 +211,7 @@ def tag_tides(
         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.utils.list_models`.
+        `from eo_tides.utils import list_models; list_models()`.
     directory : str, optional
         The directory containing tide model data files. If no path is
         provided, this will default to the environment variable
@@ -336,6 +337,7 @@ def pixel_tides(
     - 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)
+    - Technical University of Denmark tide models (DTU23)
 
     This function requires access to tide model data files.
     These should be placed in a folder with subfolders matching
@@ -363,7 +365,7 @@ def pixel_tides(
         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.utils.list_models`.
+        `from eo_tides.utils import list_models; list_models()`.
     directory : str, optional
         The directory containing tide model data files. If no path is
         provided, this will default to the environment variable

diff --git a/eo_tides/model.py b/eo_tides/model.py
@@ -416,6 +416,7 @@ def model_tides(
     - 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)
+    - Technical University of Denmark tide models (DTU23)
 
     This function requires access to tide model data files.
     These should be placed in a folder with subfolders matching
@@ -444,7 +445,7 @@ def model_tides(
         The tide model (or list of models) to use to model tides.
         Defaults to "EOT20"; specify "all" to use all models available
         in `directory`. For a full list of available and supported models,
-        run `eo_tides.utils.list_models`.
+        run `from eo_tides.utils import list_models; list_models()`.
     directory : str, optional
         The directory containing tide model data files. If no path is
         provided, this will default to the environment variable
@@ -735,7 +736,7 @@ def model_phases(
         The tide model (or list of models) to use to model tides.
         Defaults to "EOT20"; specify "all" to use all models available
         in `directory`. For a full list of available and supported models,
-        run `eo_tides.utils.list_models`.
+        run `from eo_tides.utils import list_models; list_models()`.
     directory : str, optional
         The directory containing tide model data files. If no path is
         provided, this will default to the environment variable

diff --git a/eo_tides/stats.py b/eo_tides/stats.py
@@ -243,10 +243,11 @@ def tide_stats(
     model : str or list of str, optional
         The tide model (or list of models) to use to model tides.
         If a list is provided, the resulting statistics will be
-        returned as a `pandas.Dataframe`; otherwise a `pandas.Series`.
-        Defaults to "EOT20"; specify "all" to use all models available
-        in `directory`. For a full list of available and supported
-        models, run `eo_tides.utils.list_models`.
+        returned as a `pandas.Dataframe`; otherwise a `pandas.Series`
+        will be returned. Defaults to "EOT20"; specify "all" to use
+        all models available in `directory`. For a full list of
+        available and supported models, run
+        `from eo_tides.utils import list_models; list_models()`.
     directory : str, optional
         The directory containing tide model data files. If no path is
         provided, this will default to the environment variable
@@ -453,7 +454,7 @@ def pixel_stats(
         added to the `xarray.Dataset` output. Defaults to "EOT20";
         specify "all" to use all models available in `directory`.
         For a full list of available and supported models, run
-        `eo_tides.utils.list_models`.
+        `from eo_tides.utils import list_models; list_models()`.
     directory : str, optional
         The directory containing tide model data files. If no path is
         provided, this will default to the environment variable

diff --git a/pyproject.toml b/pyproject.toml
@@ -44,7 +44,7 @@ dependencies = [
     "psutil>=5.8.0",
     "pyogrio>=0.10.0",
     "pyproj>=3.7.0",
-    "pyTMD==2.2.0",
+    "pyTMD==2.2.1",
     "scikit-learn>=1.4.0",
     "scipy>=1.14.1",
     "shapely>=2.0.6",