Minor doc updates

GeoscienceAustralia · Oct 28, 2024 · 3216bef · 3216bef
1 parent 3a63b3b
commit 3216bef
Show file tree

Hide file tree

Showing 9 changed files with 51 additions and 14 deletions.
diff --git a/README.md b/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/).

diff --git a/docs/assets/fes_ftp.jpg b/docs/assets/fes_ftp.jpg
diff --git a/docs/assets/fes_myproducts.jpg b/docs/assets/fes_myproducts.jpg
diff --git a/docs/assets/fes_productselection.jpg b/docs/assets/fes_productselection.jpg
diff --git a/docs/assets/fes_subscriptions.jpg b/docs/assets/fes_subscriptions.jpg
diff --git a/docs/assets/tpxo_download.jpg b/docs/assets/tpxo_download.jpg
diff --git a/docs/index.md b/docs/index.md
@@ -22,9 +22,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
-- 🛰️ "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 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 heights based on the exact moment of image acquisition
+- 🌐 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 -->
@@ -49,6 +49,13 @@ 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
+```
+
 ## Next steps
 
 To get started, first follow the [guide to installing `eo-tides`](install.md), and then [set up one or multiple global ocean tide models](setup.md).
+<br>
diff --git a/docs/setup.md b/docs/setup.md
@@ -61,15 +61,15 @@ Follow the guides below for some of the most commonly used global ocean tide mod
     2. Once your registration is complete, login to [MY AVISO+](https://www.aviso.altimetry.fr/en/my-aviso-plus.html).
     3. Once logged in, select [My products](https://www.aviso.altimetry.fr/en/my-aviso-plus/my-products.html) in the left-hand menu:
 
-        ![image](https://user-images.githubusercontent.com/17680388/160057999-381fb818-e379-46cb-a3c4-a836308a96d8.png)
+        ![image](assets/fes_myproducts.jpg)
 
     4. `FES (Finite Element Solution - Oceanic Tides Heights)` should appear under `Your current subscriptions.` Right click on `Ftp`, and copy the FTP address.
 
-        ![image](https://user-images.githubusercontent.com/17680388/160058064-77430ddf-1939-449d-86e7-f05b27ca768a.png)
+        ![image](assets/fes_subscriptions.jpg)
 
     5. Using an FTP client like FileZilla, log in to the FTP using your AVISO+ username and password:
 
-        ![image](https://user-images.githubusercontent.com/17680388/160058263-b0b1da72-e5ac-47ca-b1d0-544569d3f06a.png)
+        ![image](assets/fes_ftp.jpg)
 
     6. Navigate to `/auxiliary/tide_model/`, and download the contents of one or more of the following directories:
 
@@ -109,15 +109,15 @@ Follow the guides below for some of the most commonly used global ocean tide mod
     2. Once your registration is complete, login to [MY AVISO+](https://www.aviso.altimetry.fr/en/my-aviso-plus.html).
     3. Once logged in, select [My products](https://www.aviso.altimetry.fr/en/my-aviso-plus/my-products.html) in the left-hand menu:
 
-        ![image](https://user-images.githubusercontent.com/17680388/160057999-381fb818-e379-46cb-a3c4-a836308a96d8.png)
+        ![image](assets/fes_myproducts.jpg)
 
     4. `FES (Finite Element Solution - Oceanic Tides Heights)` should appear under `Your current subscriptions.` Right click on `Ftp`, and copy the FTP address.
 
-        ![image](https://user-images.githubusercontent.com/17680388/160058064-77430ddf-1939-449d-86e7-f05b27ca768a.png)
+        ![image](assets/fes_subscriptions.jpg)
 
     5. Using an FTP client like FileZilla, log in to the FTP using your AVISO+ username and password:
 
-        ![image](https://user-images.githubusercontent.com/17680388/160058263-b0b1da72-e5ac-47ca-b1d0-544569d3f06a.png)
+        ![image](assets/fes_ftp.jpg)
 
     6. Navigate to `/auxiliary/tide_model/`, and download the contents of one or more of the following directories:
 
@@ -188,6 +188,30 @@ Follow the guides below for some of the most commonly used global ocean tide mod
            |- ...
         ```
 
+??? note "TPXO Global Tidal Models"
+
+    ### TPXO Global Tidal Models
+
+    1. Visit [TPXO Registration](https://www.tpxo.net/tpxo-products-and-registration)
+    2. Follow instructions to email TPXO authors for access, providing your name, institution, your intended application/use case, and which TPXO models you need (typically, "TPXO10-atlas-v2 netcdf" or "TPXO9-atlas-v5 netcdf").
+    3. If your request is approved, you will be emailed an invite to an app.box.com folder. Open this link, then click "Download" on the top-right to download your zipped model files.
+
+        ![image](assets/tpxo_download.jpg)
+
+    4. Create a new directory inside your [tide model directory](#setting-up-a-tide-model-directory) called either `TPXO10_atlas_v2/` or `TPXO9_atlas_v5/` to store the TPXO model files.
+
+    4. Extract your zipped model files (e.g. `TPXO10_atlas_v2_nc.zip` or `TPXO9_atlas_v5_nc.zip`) into this new directory. You should end up with the following directory structure containing the extracted NetCDF files depending on the model you downloaded:
+
+        ```
+        tide_models/TPXO10_atlas_v2/
+           |- ...
+        ```
+        Or:
+        ```
+        tide_models/TPXO9_atlas_v5/
+           |- ...
+        ```
+
 ## Configuring `eo-tides` to use tide model directory
 
 `eo-tides` can be pointed to the location of your [tide model directory](#setting-up-a-tide-model-directory) and your downloaded tide model data in two ways:

diff --git a/eo_tides/model.py b/eo_tides/model.py
@@ -76,12 +76,12 @@ def list_models(
     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`.
+    List all tide models available for tide modelling.
 
     This function scans the specified tide model directory
     and returns a list of models that are available in the
-    directory as well as the full list of all supported models.
+    directory as well as the full list of all models supported
+    by `eo-tides` and `pyTMD`.
 
     For instructions on setting up tide models, see:
     <https://geoscienceaustralia.github.io/eo-tides/setup/>