diff --git a/README.md b/README.md index d111363..3060f9c 100644 --- 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/)) @@ -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 new file mode 100644 index 0000000..0ab973b Binary files /dev/null and b/docs/assets/fes_ftp.jpg differ diff --git a/docs/assets/fes_myproducts.jpg b/docs/assets/fes_myproducts.jpg new file mode 100644 index 0000000..40471f5 Binary files /dev/null and b/docs/assets/fes_myproducts.jpg differ diff --git a/docs/assets/fes_productselection.jpg b/docs/assets/fes_productselection.jpg index 0dbb6e7..fb62b9b 100644 Binary files a/docs/assets/fes_productselection.jpg and b/docs/assets/fes_productselection.jpg differ diff --git a/docs/assets/fes_subscriptions.jpg b/docs/assets/fes_subscriptions.jpg new file mode 100644 index 0000000..0dbb6e7 Binary files /dev/null and b/docs/assets/fes_subscriptions.jpg differ diff --git a/docs/assets/tpxo_download.jpg b/docs/assets/tpxo_download.jpg new file mode 100644 index 0000000..fffa851 Binary files /dev/null and b/docs/assets/tpxo_download.jpg differ diff --git a/docs/index.md b/docs/index.md index b90dddc..f74de8b 100644 --- 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/)) @@ -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). +
diff --git a/docs/setup.md b/docs/setup.md index e7d138c..3438b36 100644 --- 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 index dca82b5..2d4541e 100644 --- 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: