tides-sample v3.2.3¶

Mercurial revision 5770:c90c3015e72d | 2026-05-22

Description¶

tides-sample extracts specific locations from a tidal atlas into MGR files to build synthetic tide gauges. This tool is useful for generating time series of tidal predictions at specified locations based on precomputed tidal atlases.

Usage¶

tides-sample [OPTIONS] wave1 [wave2 ...]

Options¶

Option	Description
`-h`, `--help`	Show this help and exit.
`-l <file>`	File listing all the locations to extract. The file should contain the coordinates (longitude, latitude) of each location.
`-a <convention>`	Naming convention for the atlas files. See Convention below.
`-p <path>`	Path to the list of control points. This can be:

An ASCII file with the number of control points followed by their coordinates (longitude, latitude).
A pattern of NetCDF files containing latitude, longitude, and time variables (see also -o option).
If not provided, predictions are made for all points in the atlas. |
| -o <path> | Path for the output file. The output format depends on the input:
NetCDF if:
- -p is not provided, or
- -p specifies a NetCDF file with a time variable, or
- -o is followed by a .nc extension.
ASCII otherwise. |

Convention¶

The atlas file naming convention supports the following placeholders:

WAVE: Replaced by the uppercase name of the wave (e.g., M2).
wave: Replaced by the lowercase name of the wave (e.g., m2).
Wave: Replaced by the capitalized name of the wave (e.g., M2).

Note: If the file exists without any replacements, no substitution is performed.

Examples¶

Extract Tidal Data for Specific Locations¶

Extract tidal data for locations listed in locations.txt using the default atlas convention:

tides-sample -l locations.txt M2 S2 K1 O1

Specify a Custom Atlas Convention¶

Use a custom naming convention for atlas files (e.g., tidal_atlas_{WAVE}.nc):

tides-sample -a "tidal_atlas_{WAVE}.nc" -l locations.txt M2 S2

Extract Data for All Points in the Atlas¶

Extract tidal data for all points in the atlas (no -p option):

tides-sample -o output.nc M2 S2 K1

Output to ASCII File¶

Extract tidal data and save to an ASCII file:

tides-sample -l locations.txt -o output.txt M2 S2

Use NetCDF Control Points¶

Specify control points from a NetCDF file containing latitude, longitude, and time variables:

tides-sample -p control_points.nc -o output.nc M2 S2 K1

Environment Variables¶

This tool does not rely on specific environment variables. However, ensure that:

Input files (atlas, locations, control points) are accessible.
Output directories have write permissions.

Notes¶

Input Files:

The -l file must contain valid coordinates (longitude, latitude) for each location.
If -p is not provided, predictions are made for all points in the atlas.

Output Format:

The output format (NetCDF or ASCII) is determined automatically based on the input options.
If -o ends with .nc, the output is always in NetCDF format.

Wave List:

Waves must be specified as arguments (e.g., M2, S2, K1).
The tool supports any valid tidal constituent recognized by the atlas.

Atlas Convention:

The -a option allows flexibility in specifying the naming pattern for atlas files.
Placeholders (WAVE, wave, Wave) are replaced dynamically.

Unused Options:

-c: Name of the output MGR file (not used in the current version).
-m: Mesh file of the atlas (not used in the current version).