Getting started

Installation

Install the tidepredictor package from the distributed wheel file. Available on https://github.com/DHI/tidepredictor/releases.

E.g. for version 0.1.0:

pip install https://github.com/DHI/tidepredictor/releases/download/v0.1.0/tidepredictor-0.1.0-py3-none-any.whl

Copy constituent files (.nc files) for both DTU14 and FES2014 models to the local machine with the following directory tree:

~/.local/share/tidepredictor/
├── DTU14/
│   ├── current.nc
│   └── level.nc
└── FES2014/
    ├── level/
    │   ├── 2n2.nc
    │   ├── eps2.nc
    │   ├── .
    │   ├── .
    │   ├── .
    │   ├── ssa.nc
    │   └── t2.nc
    └── current/
        ├── Bathymetry.nc
        ├── eastward_velocity/
        │   ├── 2n2.nc
        │   ├── eps2.nc
        │   ├── .
        │   ├── .
        │   ├── .
        │   ├── ssa.nc
        │   └── t2.nc
        └── northward_velocity/
            ├── 2n2.nc
            ├── eps2.nc
            ├── .
            ├── .
            ├── .
            ├── ssa.nc
            └── t2.nc

Bathymetry

Note that the bathymetry file (fx. GEBCO) must be located for FES2014 current profile calculations. Please see the folder tree above for the correct file naming and location. Global bathymetry file from GEBCO [GEBCO_2025 Grid (sub-ice topo/bathy)] can be downloaded from here: https://www.gebco.net/data-products/gridded-bathymetry-data

Usage

tidepredictor can be used both as a command-line application and as a Python library. The package currently supports two tidal models: DTU14 and FES2014. The desired model can be selected using the model_name keyword argument, with FES2014 set as the default option.

Python library

import tidepredictor as tp
from datetime import datetime, timedelta

path = tp.get_default_constituent_path(tp.PredictionType.level, model_name="DTU14")

repo = tp.NetCDFConstituentRepository(path, model_name="DTU14")

predictor = tp.LevelPredictor(repo)

df = predictor.predict(
    lon=-2.75,
    lat=56.1,
    start=datetime(2021, 1, 1),
    end=datetime(2021, 1, 1, 12),
    interval=timedelta(hours=1),
)

And similar for depth averaged currents.

path = tp.get_default_constituent_path(tp.PredictionType.current, model_name="FES2014")

repo = tp.NetCDFConstituentRepository(path, model_name="FES2014")

predictor = tp.CurrentPredictor(repo)

df = predictor.predict_depth_averaged(
    lon=-2.75,
    lat=56.1,
    start=datetime(2021, 1, 1),
    end=datetime(2021, 1, 1, 12),
    interval=timedelta(hours=1)
)

And current profiles.

path = tp.get_default_constituent_path(tp.PredictionType.current,model_name="FES2014")

repo = tp.NetCDFConstituentRepository(path,model_name="FES2014")

predictor = tp.CurrentPredictor(repo, alpha=1.0/3)

df = predictor.predict_profile(
    lon=-2.75,
    lat=56.1,
    start=datetime(2021, 1, 1),
    end=datetime(2021, 1, 2, 1),
    interval=timedelta(hours=1),
    levels=[-1.0, -10.0, -27.0]
)

import pandas as pd
import matplotlib.pyplot as plt

fig, ax = plt.subplots(figsize=(7,4))

ax.plot(df["time"],df["CS_avg"],marker=".",label="Depth-averaged")
for depth in [-1.0, -10.0, -27.0]:
    ax.plot(df["time"],df[f"CS_({depth})"],marker=".",label=f"{depth} m")

ax.grid("True",ls="--")
ax.set_ylabel("CS [m/s]")
ax.legend(loc="upper left",bbox_to_anchor=(1.02,1.0))
ax.tick_params(axis="x",rotation=30)

Command line

!tidepredictor -x -2.75 -y 56.1 -s "2021-01-01" -e "2021-01-01 02:00:00" -i 30

time,level
2021-01-01T00:00:00Z,-0.3465
2021-01-01T00:30:00Z,0.1553
2021-01-01T01:00:00Z,0.5931
2021-01-01T01:30:00Z,0.9517
2021-01-01T02:00:00Z,1.2437

All options are available as command line arguments.

!tidepredictor --help

                                                                               
 Usage: tidepredictor [OPTIONS]                                                
                                                                               
 Predict the tides for a given location.                                       
                                                                               
+- Options -------------------------------------------------------------------+
| *  --lon                 -x      FLOAT RANGE           Longitude            |
|                                  [-180<=x<=180]        [default: None]      |
|                                                        [required]           |
| *  --lat                 -y      FLOAT RANGE           Latitude             |
|                                  [-90<=x<=90]          [default: None]      |
|                                                        [required]           |
|    --start               -s      [%Y-%m-%d|%Y-%m-%dT%  Start date           |
|                                  H:%M:%S|%Y-%m-%d      [default: None]      |
|                                  %H:%M:%S]                                  |
|    --end                 -e      [%Y-%m-%d|%Y-%m-%dT%  End date             |
|                                  H:%M:%S|%Y-%m-%d      [default: None]      |
|                                  %H:%M:%S]                                  |
|    --interval            -i      INTEGER RANGE [x>=1]  Interval in minutes  |
|                                                        [default: 30]        |
|    --output              -o      PATH                  Output file, default |
|                                                        is stdout            |
|                                                        [default: None]      |
|    --model               -m      TEXT                  Model name           |
|                                                        [default: FES2014]   |
|    --format                      [csv|json]            Output format        |
|                                                        [default: csv]       |
|    --type                        [level|current]       Type of prediction,  |
|                                                        'level' or 'current' |
|                                                        (u,v)                |
|                                                        [default: level]     |
|    --precision           -p      INTEGER RANGE [x>=0]  Number of decimal    |
|                                                        places. (csv only)   |
|                                                        [default: 4]         |
|    --alpha                       FLOAT                 Alpha factor for     |
|                                                        current profile      |
|                                                        [default:            |
|                                                        0.14285714285714285] |
|    --install-completion                                Install completion   |
|                                                        for the current      |
|                                                        shell.               |
|    --show-completion                                   Show completion for  |
|                                                        the current shell,   |
|                                                        to copy it or        |
|                                                        customize the        |
|                                                        installation.        |
|    --help                                              Show this message    |
|                                                        and exit.            |
+-----------------------------------------------------------------------------+