Getting Started

See the background material and glossary for more information on the theory and methods used in pyTMD.

Tide Model Formats

Ocean and load tide constituent files are available from different modeling groups in different formats. pyTMD can access the harmonic constituents for the OTIS, GOT and FES families of ocean and load tide models. OTIS and ATLAS formatted data use binary files to store the constituent data for either heights (z) or zonal and meridional transports (u, v). They can be either a single file containing all the constituents (compact) or multiple files each containing a single constituent. Arctic Ocean models can be downloaded from the NSF ArcticData server using the arcticdata_tides.py program. CATS2008 can be downloaded from the US Antarctic Program (USAP) using the usap_cats_tides.py program. ATLAS netCDF formatted data use netCDF4 files for each constituent and variable type (z, u, v). GOT formatted data use ascii files for each height constituent (z). FES formatted data use either ascii (1999, 2004) or netCDF4 (2012, 2014) files for each constituent and variable type (z, u, v). The FES models can be downloaded using the aviso_fes_tides.py program for users registered with AVISO.

Model Database

pyTMD comes parameterized with models for the prediction of tidal elevations and currents. All presently available models are stored within a JSON database:

>>> import pyTMD
>>> pyTMD.models.current.get('CATS2008')
{'format': 'OTIS', 'grid_file': 'CATS2008/grid_CATS2008','model_file': {'u': 'CATS2008/uv.CATS2008.out'}, 'name': 'CATS2008','projection': 'CATS2008', 'reference': 'https://doi.org/10.15784/601235','type': ['u', 'v']}
>>> pyTMD.models.elevation.get('CATS2008')
{'format': 'OTIS', 'grid_file': 'CATS2008/grid_CATS2008','model_file': 'CATS2008/hf.CATS2008.out', 'name': 'CATS2008','projection': 'CATS2008', 'reference': 'https://doi.org/10.15784/601235','type': 'z', 'variable': 'tide_ocean'}

Directories

pyTMD uses a tree structure for storing the tidal constituent data. This structure was chosen based on the different formats of each tide model. Presently, the following models and their directories are parameterized within pyTMD.

  • Circum-Antarctic Tidal Simulations [37]

    • CATS0201: <path_to_tide_models>/cats0201_tmd/

    • CATS2008: <path_to_tide_models>/CATS2008/

    • CATS2008_load: <path_to_tide_models>/CATS2008a_SPOTL_Load/

    • CATS2008-v2023: <path_to_tide_models>/CATS2008_v2023/

  • Arctic Ocean and Greenland Coast Tidal Simulations [36]

    • AODTM-5: <path_to_tide_models>/aodtm5_tmd/

    • AOTIM-5: <path_to_tide_models>/aotim5_tmd/

    • AOTIM-5-2018: <path_to_tide_models>/Arc5km2018/

    • Arc2kmTM: <path_to_tide_models>/Arc2kmTM/

    • Gr1km-v2: <path_to_tide_models>/greenlandTMD_v2/

  • TOPEX/POSEIDON global tide models [19]

    • TPXO7.2: <path_to_tide_models>/TPXO7.2_tmd/

    • TPXO7.2_load: <path_to_tide_models>/TPXO7.2_load/

    • TPXO8-atlas: <path_to_tide_models>/tpxo8_atlas/

    • TPXO9.1: <path_to_tide_models>/TPXO9.1/DATA/

    • TPXO9-atlas: <path_to_tide_models>/TPXO9_atlas/

    • TPXO9-atlas-v2: <path_to_tide_models>/TPXO9_atlas_v2/

    • TPXO9-atlas-v3: <path_to_tide_models>/TPXO9_atlas_v3/

    • TPXO9-atlas-v4: <path_to_tide_models>/TPXO9_atlas_v4/

    • TPXO9-atlas-v5: <path_to_tide_models>/TPXO9_atlas_v5/

    • TPXO10-atlas-v2: <path_to_tide_models>/TPXO10_atlas_v2/

  • Global Ocean Tide models [44]

    • GOT4.7: <path_to_tide_models>/GOT4.7/grids_oceantide/

    • GOT4.7_load: <path_to_tide_models>/GOT4.7/grids_loadtide/

    • GOT4.8: <path_to_tide_models>/got4.8/grids_oceantide/

    • GOT4.8_load: <path_to_tide_models>/got4.8/grids_loadtide/

    • GOT4.10: <path_to_tide_models>/GOT4.10c/grids_oceantide/

    • GOT4.10_load: <path_to_tide_models>/GOT4.10c/grids_loadtide/

    • GOT5.5: <path_to_tide_models>/GOT5.5/ocean_tides/

    • GOT5.5_load: <path_to_tide_models>/GOT5.5/load_tides/

    • GOT5.6: <path_to_tide_models>/GOT5.6/ocean_tides/

    • RE14: <path_to_tide_models>/RE14_LongPeriodTides_rel/oceantides/

  • Finite Element Solution tide models [28]

    • FES2014: <path_to_tide_models>/fes2014/ocean_tide/

    • FES2014_load: <path_to_tide_models>/fes2014/load_tide/

    • FES2022: <path_to_tide_models>/fes2022b/ocean_tide_20241025/

    • FES2022_load: <path_to_tide_models>/fes2022b/load_tide/

  • Empirical Ocean Tide models [21]

    • EOT20: <path_to_tide_models>/EOT20/ocean_tides/

    • EOT20_load: <path_to_tide_models>/EOT20/load_tides/

  • Technical University of Denmark tide models [3]

    • DTU23: <path_to_tide_models>/DTU23_OceanTide/DTU23/

  • Hamburg direct data Assimilation Methods for Tides models [52]

For other tide models, the model parameters can be set with a model definition file. Note that any alternatively defined model will have to fit the file standard of a currently supported model.

Definition Files

For models not currently within the pyTMD database, the model parameters can be set with a definition file in JSON format. The JSON definition files follow a similar structure as the main pyTMD database, but for individual entries. The JSON format directly maps the parameter names with their values stored in the appropriate data type (strings, lists, numbers, booleans, etc). For FES-type models of currents, the two lists of model files (u and v) are stored in a name-value pair objects (similar to a python dictionary). While still human readable, the JSON format is both interoperable and more easily machine readable.

Each definition file should have name, format and type parameters. Each model type may also require specific sets of parameters for the individual model reader. For models with multiple constituent files, the files can be found using a glob string to search a directory.

  • OTIS, ATLAS-compact and TMD3

    • format: OTIS, ATLAS-compact or TMD3

    • grid_file: path to model grid file

    • model_file: path to model constituent file(s) or a glob string

    • name: tide model name

    • projection: model spatial projection.

    • type: z or u,v

  • ATLAS-netcdf

    • compressed: model files are gzip compressed

    • format: ATLAS-netcdf

    • grid_file: path to model grid file

    • model_file: path to model constituent files or a glob string

    • name: tide model name

    • scale: scaling factor for converting to output units

    • type: z or u,v

  • GOT-ascii and GOT-netcdf

    • compressed: model files are gzip compressed

    • format: GOT-ascii or GOT-netcdf

    • model_file: path to model constituent files or a glob string

    • name: tide model name

    • scale: scaling factor for converting to output units

    • type: z

  • FES-ascii and FES-netcdf

    • compressed: model files are gzip compressed

    • format: FES-ascii or FES-netcdf

    • model_file: path to model constituent files or a glob string

    • name: tide model name

    • scale: scaling factor for converting to output units

    • type: z or u,v

    • version: tide model version

Programs

pyTMD.compute calculates tide predictions for use with numpy arrays or pandas dataframes. These are a series of functions that take x, y, and time coordinates and compute the corresponding tidal elevation or currents.

>>> import pyTMD
>>> tide_h = pyTMD.compute.tide_elevations(x, y, delta_time, DIRECTORY=path_to_tide_models, MODEL='CATS2008', EPSG=3031, EPOCH=(2000,1,1,0,0,0), TYPE='drift', TIME='GPS', METHOD='spline', FILL_VALUE=np.nan)
>>> tide_uv = pyTMD.compute.tide_currents(x, y, delta_time, DIRECTORY=path_to_tide_models, MODEL='CATS2008', EPSG=3031, EPOCH=(2000,1,1,0,0,0), TYPE='drift', TIME='GPS', METHOD='spline', FILL_VALUE=np.nan)

Time

The default time in pyTMD is days (UTC) since a given epoch. For ocean, load and equilibrium tide programs, the epoch is 1992-01-01T00:00:00. For pole tide programs, the epoch is 1858-11-17T00:00:00 (Modified Julian Days). pyTMD uses the timescale library to convert different time formats to the necessary time format of a given program. timescale can also parse date strings describing the units and epoch of relative times, or the calendar date of measurement for geotiff formats.

Spatial Coordinates

The default coordinate system in pyTMD is WGS84 geodetic coordinates in latitude and longitude. pyTMD uses pyproj to convert from different coordinate systems and datums. Some regional tide models are projected in a different coordinate system. These models have their coordinate reference system (CRS) information stored as PROJ descriptors in the JSON model database: For other projected models, a formatted coordinate reference system (CRS) descriptor (e.g. PROJ, WKT, or EPSG code) can be used. For all cases with projected models, pyTMD will convert from latitude and longitude to the model coordinate system to calculate the local tidal constants.

Interpolation

For converting from model coordinates, pyTMD uses spatial interpolation routines from scipy along with a built-in bilinear interpolation routine. The default interpolator uses a biharmonic spline function to interpolate from the model coordinate system to the output coordinates. There are options to use nearest and linear interpolators with the regular grid function. For coastal or near-grounded points, the model can be extrapolated using a nearest-neighbor routine. The default maximum extrapolation distance is 10 kilometers. This default distance may not be a large enough extrapolation for some applications and models. The extrapolation cutoff can be set to any distance in kilometers, but should be used with caution in cases such as narrow fjords or ice sheet grounding zones [38].