From 94a1adba5ce2bbba45b17d74eab0aeddb32a4111 Mon Sep 17 00:00:00 2001 From: Robbi Bishop-Taylor Date: Thu, 26 Sep 2024 08:16:12 +0000 Subject: [PATCH] Update readmes --- docs/index.md | 19 +++++++++++++------ docs/install.md | 15 +++++++++++++++ docs/setup.md | 27 ++++++--------------------- 3 files changed, 34 insertions(+), 27 deletions(-) diff --git a/docs/index.md b/docs/index.md index 5ebca2f..3ad3dd6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,9 +1,6 @@ # `eo-tides:` Tide modelling tools for large-scale satellite earth observation analysis - - - [![Release](https://img.shields.io/github/v/release/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/v/release/GeoscienceAustralia/eo-tides) [![Build status](https://img.shields.io/github/actions/workflow/status/GeoscienceAustralia/eo-tides/main.yml?branch=main)](https://github.com/GeoscienceAustralia/eo-tides/actions/workflows/main.yml?query=branch%3Amain) [![Commit activity](https://img.shields.io/github/commit-activity/m/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/commit-activity/m/GeoscienceAustralia/eo-tides) @@ -15,14 +12,24 @@ The `eo-tides` package provides tools for analysing coastal and ocean satellite earth observation data using information about ocean tides. -`eo-tides` combines advanced tide modelling functionality from the [`pyTMD`](https://pytmd.readthedocs.io/en/latest/) package and integrates it with `pandas`, `xarray` and `odc-geo` to provide a powerful set of tools for integrating satellite imagery with tide data. +`eo-tides` combines advanced tide modelling functionality from the [`pyTMD`](https://pytmd.readthedocs.io/en/latest/) package and integrates it with `pandas`, `xarray` and `odc-geo` to provide a powerful set of parallelised tools for integrating satellite imagery with tide data – from local, regional to continental scale. Some key functionality includes the ability to: -- Model tides from multiple global ocean tide models (e.g. FES2022, FES2014, TPXO9, EOT20 and many more) in parallel, and return tide heights in standardised `pandas.DataFrame` format for further analysis +- 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 timeseries with tide data based on the exact moment of each satellite acquisition - Model tides for every individual satellite pixel, producing three-dimensional "tide height" `xarray`-format datacubes that can be combined 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 +- Validate modelled tides using measured sea levels from coastal tide gauges (e.g. GESLA) These tools can be applied directly to petabytes of freely available satellite data (e.g. from Digital Earth Australia or Microsoft Planetary Computer) loaded via Open Data Cube's `odc-stac` or `datacube` packages, supporting coastal and ocean earth observation analysis for any time period or location globally. + +## Supported tide models + +`eo-tides` supports [all ocean tide models supported by `pyTMD`](https://pytmd.readthedocs.io/en/latest/getting_started/Getting-Started.html#model-database). These include: + +- FES2022, FES2014, FES2012 +- TPXO10, TPXO9, TPXO8 +- GOT5.6, GOT5.5, GOT4.10 +- EOT20 +- HAMTIDE11 diff --git a/docs/install.md b/docs/install.md index e69de29..bb4fc09 100644 --- a/docs/install.md +++ b/docs/install.md @@ -0,0 +1,15 @@ +# Installing `eo-tides` + +`eo-tides` can be installed into your Python environment from [PyPI](https://pypi.org/project/eo-tides/) using `pip`: + +``` +pip install eo-tides +``` + +By default, only essential package dependencies are installed. To install all packages required for running the included Jupyter Notebook examples (including `odc-stac` and `pystac-client` for loading freely available satellite data): + +``` +pip install eo-tides[notebooks] +``` + +Once you have installed `eo-tides`, you will need to [download and set up at least one tide model](../setup/) before you can model tides. diff --git a/docs/setup.md b/docs/setup.md index a44f94f..d1f1222 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -21,37 +21,24 @@ 6. Navigate to `/auxiliary/tide_model/fes2014_elevations_and_load/`, and download the following files: -- `fes2014a_loadtide/load_tide.tar.xz` - `fes2014b_elevations/ocean_tide.tar.xz` (_or_ `fes2014b_elevations_extrapolated/ocean_tide_extrapolated.tar.xz`; this extrapolated version includes additional coverage of the coastal zone, which can be useful for coastal applications) -7. Create a new folder (i.e. `tide_models/fes2014/`) to store the model files in a location that will be accessible to the DEA Coastlines code. Extract `load_tide.tar.xz` and `ocean_tide.tar.xz` into this folder (e.g. `tar -xf load_tide.tar.xz`). You should end up with the following directory structure containing the extracted NetCDF files: +7. Create a new folder (i.e. `tide_models/fes2014/`) to store the model files in an accessible location. Extract `ocean_tide.tar.xz` into this folder (e.g. `tar -xf ocean_tide.tar.xz`). You should end up with the following directory structure containing the extracted NetCDF files: ``` -tide_models/fes2014/load_tide/ - |- 2n2.nc - |- ... - |- t2.nc tide_models/fes2014/ocean_tide/ |- 2n2.nc |- ... |- t2.nc ``` -> **Note**: If you downloaded `ocean_tide_extrapolated.tar.xz`, you will need to rename the extracted `ocean_tide_extrapolated` folder to `ocean_tide`. - ### Modelling tides -If the `pyTMD` Python package is not installed on your system, this can be installed using: - -``` -pip install pytmd -``` - -Tides can now be modelled using the `model_tides` function from the `dea_tools.coastal` package: +Tides can now be modelled using the `model_tides` function from the `eo_tides.model` module: ``` import pandas as pd -from dea_tools.coastal import model_tides +from eo_tides.model import model_tides lons=[155, 160] lats=[-35, -36] @@ -60,11 +47,9 @@ example_times = pd.date_range("2022-01-01", "2022-01-04", freq="1D") model_tides( x=lons, y=lats, - time=example_times.values, - directory='tide_models' + time=example_times, + directory='tide_models/' ) ``` -In the DEA Coastlines code, this function is used in the `raster` module as part of the annual water index composite generation process. - -Depending on where you created the `tide_models` directory, you may need to update the `directory` parameter of the `model_tide_points` function to point to the location of the FES2014 model files. +Depending on where you created the `tide_models` directory, you may need to update the `directory` parameter of the `model_tides` function to point to the location of the FES2014 model files.