tides-validate v3.2.3¶

Mercurial revision 5770:c90c3015e72d | 2026-05-22

Description¶

tides-validate is a tool that creates a comparison table of tidal waves between model outputs and observations. It is used by CTOH (Centre de Topographie des Océans et de l’Hydrosphère).

Usage¶

tides-validate -g file.mgr -a WAVE-file.nc wave1 [wave2 ...]

Options¶

General Options¶

Option	Description
`-h`, `--help`	Display help and exit.
`--silent`	Suppress output messages.

Input/Output Options¶

Option	Description
`-g <file>`	Harmonic data input file (required).
`-a <convention>`	Naming convention for tidal atlases (required). See Convention.
`-o <name>`	Output root name (default: `validate.out` or `validate.tex`).
`-p <path>`	Path for tidal atlases.
`-m <file>`	ASCII mesh file.
`-f <format>`	Analysis file format.
`-v <var1> <var2>`	Variable name conventions for amplitude and phase (default: `Ha Hg` for structured atlases).
`-i <num>`	Iteration number (use `-1` for the last one).
`-x <order>`	Output order: `FILE`, `ALPHA`, `LAT`, `LON`, or `IMMERSION`.

Comparison Options¶

Option	Description
`-d`	Print data/model differences.
`-D`	Print data/model differences in brief format.
`-b <file>`	Bathymetry database.
`-l`	Output format in LaTeX.
`-c`	Output format in CSV.
`--strict`	Only compare with data strictly included in the grid (no extrapolation).
`-cm`	Analysis file unit is in centimeters.

Geographical and Depth Limits¶

Option	Description
`--frame [lonmin:lonmax;latmin:latmax]`	Limit validation to stations within the specified geographical frame.
`--polygons <path>`	Path to a file containing polygons. Validation is limited to stations within these polygons.
`--range <min:max>`	Depth range for validation (in meters).
`--regions <regions>`	Limit validation to specific regions.
`--level <num>`	Level for validation.

Unstructured Grid Options¶

Option	Description
`-unstructured [discretisation]`	Specify if the NetCDF file is unstructured. Provide the discretisation type (e.g., `LGP1` or `LGP2`).
`-unstructured-ascii [discretisation]`	Same as `-unstructured` but for ASCII files.

Metadata Options¶

Option	Description
`--tag <tag>`	Tag for output files.
`--year <year>`	Year for validation (default: `1950`).
`--units <unit>`	Unit for analysis (default: `cm`).

Convention¶

The naming convention for tidal atlases uses placeholders:

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

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

Examples¶

Basic Validation¶

Compare model and observation data for waves M2 and S2:

tides-validate -g model_data.mgr -a WAVE-file.nc M2 S2

Output in LaTeX Format¶

Generate a LaTeX report for waves K1 and O1:

tides-validate -g model_data.mgr -a WAVE-file.nc -l K1 O1

Output in CSV Format¶

Generate a CSV report for waves M2 and N2:

tides-validate -g model_data.mgr -a WAVE-file.nc -c M2 N2

Limit Validation to a Geographical Frame¶

Validate waves M2 and S2 within a specific geographical area:

tides-validate -g model_data.mgr -a WAVE-file.nc \
  --frame "-10:10;40:60" M2 S2

Limit Validation to Polygons¶

Validate waves K1 and O1 within polygons defined in polygons.shp:

tides-validate -g model_data.mgr -a WAVE-file.nc \
  --polygons polygons.shp K1 O1

Use Custom Variable Names¶

Specify custom variable names for amplitude (amp) and phase (phase):

tides-validate -g model_data.mgr -a WAVE-file.nc \
  -v amp phase M2 S2

Unstructured Grid¶

Validate waves for an unstructured grid with LGP2 discretisation:

tides-validate -g model_data.mgr -a WAVE-file.nc \
  -unstructured LGP2 M2 S2

Strict Comparison¶

Only compare data strictly included in the grid (no extrapolation):

tides-validate -g model_data.mgr -a WAVE-file.nc \
  --strict M2 S2

Output in Brief Format¶

Print differences in a brief format:

tides-validate -g model_data.mgr -a WAVE-file.nc -D M2 S2

Specify Depth Range¶

Limit validation to a depth range of 10 to 50 meters:

tides-validate -g model_data.mgr -a WAVE-file.nc \
  --range "10:50" M2 S2

Environment Variables¶

tides-validate does not rely on specific environment variables. However, ensure your system has the necessary permissions to read input files and write to the output directory.

Notes¶

Required Options:

-g (harmonic data input file) and -a (naming convention for tidal atlases) are mandatory.
At least one tidal constituent (e.g., M2, S2) must be specified.

Variable Names:

For structured grids, default variable names are Ha (amplitude) and Hg (phase).
For unstructured grids, you must specify variable names using -v or provide a mesh file (-m).

Conflicting Options:

You cannot use both --frame and --polygons simultaneously.

Output Formats:

Use -l for LaTeX output or -c for CSV output.
Default output filenames: validate.out (text) or validate.tex (LaTeX).

Units:

By default, the analysis file unit is in centimeters. Use -cm to confirm this or --units to specify another unit.