Skip to content

Commit

Permalink
Update readmes
Browse files Browse the repository at this point in the history
  • Loading branch information
robbibt committed Sep 26, 2024
1 parent e286dcd commit 94a1adb
Show file tree
Hide file tree
Showing 3 changed files with 34 additions and 27 deletions.
19 changes: 13 additions & 6 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,6 @@
<img style="float: left; margin: 0 50px 0 0;" src="assets/eo-tides-logo.jpg" width="136">
# `eo-tides:` Tide modelling tools for large-scale satellite earth observation analysis

<!-- <img src="assets/eo-tides-logo.jpg" alt="drawing" width="200"/> -->
<!-- <img style="display: block; margin: auto;" src="assets/eo-tides-logo.jpg"/> -->

[![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)
Expand All @@ -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
15 changes: 15 additions & 0 deletions docs/install.md
Original file line number Diff line number Diff line change
@@ -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.
27 changes: 6 additions & 21 deletions docs/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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.

0 comments on commit 94a1adb

Please sign in to comment.