Setting up tide models¶

Important

eo-tides provides tools for modelling tides using global ocean tide models but does not host or maintain the models themselves. Users are responsible for accessing, using, and citing ocean tide models in compliance with each model's licensing terms.

Once you have installed eo-tides, we need to download and set up the external global ocean tide models required for eo-tides to work. The following documentation provides instructions for getting started with several common global ocean tide models.

Tip

Please refer to the pyTMD documentation for additional instructions covering all other supported tide models.

Setting up a tide model directory¶

As a first step, we need to create a directory that will contain our tide model data. This directory will be accessed by all eo-tides functions. For example, we might want to store our tide models in a directory called tide_models/:

tide_models/

Tip

This directory doesn't need to be called tide_models; use any name and/or location that is convenient to you and accessible from your Python environment. Please refer to the documentation below for further details on configuring eo-tides to use this directory.

Downloading tide model data¶

Now we need to download some data from one or more models, and save this into our tide model directory. Follow the guides below for some of the most commonly used global ocean tide models:

EOT20 Empirical Ocean Tide model (default)

EOT20 Empirical Ocean Tide model (default)¶

Visit EOT20 - A global Empirical Ocean Tide model from multi-mission satellite altimetry
Under Data, click Download:
Create a new directory inside your tide model directory called EOT20/ to store the EOT20 model files.
Extract the 85762.zip and then ocean_tides.zip into this new directory. You should end up with the following directory structure containing the extracted NetCDF files:
```
tide_models/EOT20/ocean_tides/
   |- 2N2_ocean_eot20.nc
   |- ...
   |- T2_ocean_eot20.nc
```

FES2022 Finite Element Solution tide models

FES2022 Finite Element Solution tide models¶

Register with AVISO+, and select FES (Finite Element Solution - Oceanic Tides Heights) from the Licence Agreement and product selection section:
Once your registration is complete, login to MY AVISO+.
Once logged in, select My products in the left-hand menu:
FES (Finite Element Solution - Oceanic Tides Heights) should appear under Your current subscriptions. Right click on Ftp, and copy the FTP address.
Using an FTP client like FileZilla, log in to the FTP using your AVISO+ username and password:
Navigate to /auxiliary/tide_model/, and download the contents of one or more of the following directories:
- fes2022b/ocean_tide/
- fes2022b/ocean_tide_extrapolated/
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).
Create new nested directories inside your 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.

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:

tide_models/fes2022b/ocean_tide/
   |- 2n2_fes2022.nc
   |- ...
   |- t2_fes2022.nc

Or:

tide_models/fes2022b/ocean_tide_extrapolated/
   |- 2n2_fes2022.nc
   |- ...
   |- t2_fes2022.nc

FES2014 Finite Element Solution tide models

FES2014 Finite Element Solution tide models¶

Register with AVISO+, and select FES (Finite Element Solution - Oceanic Tides Heights) from the Licence Agreement and product selection section:
Once your registration is complete, login to MY AVISO+.
Once logged in, select My products in the left-hand menu:
FES (Finite Element Solution - Oceanic Tides Heights) should appear under Your current subscriptions. Right click on Ftp, and copy the FTP address.
Using an FTP client like FileZilla, log in to the FTP using your AVISO+ username and password:
Navigate to /auxiliary/tide_model/, and download the contents of one or more of the following directories:
- fes2014_elevations_and_load/fes2014b_elevations/
- fes2014_elevations_and_load/fes2014b_elevations_extrapolated/
Tip

The "extrapolated" version of FES 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).
Create a new directory inside your tide model directory called fes2014/ to store the FES2014 model files.
Extract ocean_tide.tar.xz or ocean_tide_extrapolated.tar.xz into this directory (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/ocean_tide/
   |- 2n2.nc
   |- ...
   |- t2.nc
```
Or:
```
tide_models/fes2014/ocean_tide_extrapolated/
   |- 2n2.nc
   |- ...
   |- t2.nc
```

GOT Global Ocean Tide models

GOT Global Ocean Tide models¶

Visit Ocean tide models
Under Short-period (diurnal/semidiurnal) tides, click choose your desired GOT model:
Create a new directory inside your tide model directory called either GOT4.7/, got4.8/, GOT4.10c/, GOT5.5/ or GOT5.6/ to store the GOT model files.
Extract your downloaded .tar.gz file into this new directory. You should end up with the following directory structure containing the extracted NetCDF files:
```
tide_models/GOT5.6/ocean_tides/
   |- ...
```
Or:
```
tide_models/GOT5.5/ocean_tides/
   |- ...
```
Important

Note that GOT5.6 requires that both GOT5.6 and GOT5.5 model files are downloaded and extracted.

Or:
```
tide_models/GOT4.10c/grids_oceantide/
   |- ...
```
Or:
```
tide_models/got4.8/grids_oceantide/
   |- ...
```
Or:
```
tide_models/GOT4.7/grids_oceantide/
   |- ...
```

Configuring `eo-tides` to use tide model directory¶

eo-tides can be pointed to the location of your tide model directory and your downloaded tide model data in two ways:

Using the `directory` function parameter¶

All tide modelling functions from eo-tides provide a directory parameter that can be used to specify the location of your tide model directory. For example, using model_tides from the eo_tides.model module:

import pandas as pd
from eo_tides.model import model_tides

model_tides(
        x=155,
        y=-35,
        time=pd.date_range("2022-01-01", "2022-01-04", freq="1D"),
        directory="tide_models/"
)

Setting the `EO_TIDES_TIDE_MODELS` environmental variable¶

For more advanced usage, you can set the path to your tide model directory by setting the EO_TIDES_TIDE_MODELS environment variable:

import os
os.environ["EO_TIDES_TIDE_MODELS"] = "tide_models/"

All tide modelling functions from eo-tides will check for the presence of the EO_TIDES_TIDE_MODELS environment variable, and use it as the default directory path if available (the EO_TIDES_TIDE_MODELS environment variable will be overuled by the directory parameter if provided).

Tip

Setting the EO_TIDES_TIDE_MODELS environment variable can be useful when the location of your tide model directory might change between different environments, and you want to avoid hard-coding a single location via the directory parameter.

Verifying available and supported models¶

You can check what tide models have been correctly set up for use by eo-tides using the eo_tides.model.list_models function:

from eo_tides.model import list_models

available_models, supported_models = list_models(directory="tide_models/")

This will print out a useful summary, with available models marked with a ✅:

──────────────────────────────────────────────────────────
 󠀠🌊  | Model        | Expected path
──────────────────────────────────────────────────────────
 ✅  │ EOT20        │ tide_models/EOT20/ocean_tides
 ❌  │ FES2014      │ tide_models/fes2014/ocean_tide
 ✅  │ HAMTIDE11    │ tide_models/hamtide
 ❌  │ TPXO9.1      │ tide_models/TPXO9.1/DATA
 ...   ...            ...
──────────────────────────────────────────────────────────

Summary:
Available models: 2/50

Next steps¶

Now that you have installed eo-tides and set up some tide models, you can learn how to use eo-tides for modelling tides and analysing satellite data!