topo-detidor v3.2.3¶

Mercurial revision 5786:5c8b45563631 | 2026-08-04

Description¶

topo-detidor corrects soundings (depth measurements) using tidal atlases. It applies tidal corrections to raw sounding data based on provided tidal constituents (waves) and their corresponding amplitude and phase values from atlas files.

Usage¶

topo-detidor [OPTIONS] -p sounding_list -a atlas_convention [-s start -f end] -w wave1 [wave2 ...]

Options¶

Option	Description
`-h`, `--help`	Display this help message and exit.
`-p <file>`	Path to the input file containing the list of soundings. The file must be an ASCII file with columns: `year month day hour minute second latitude longitude sounding`.
`-a <convention>`	Atlas file name convention. See Convention for details on how the convention is interpreted.
`-v <var1> [var2]`	Names of the variables for amplitude and phase in the atlas files. Default: `Ha Hg`.
`-w <wave1> [wave2 ...]`	List of tidal waves to correct for (e.g., `M2`, `S2`, `K1`).
`-o <file>`	Path to the output ASCII file. Default: `detided-soundings.dat`.

Convention¶

The atlas file name convention uses placeholders that are dynamically replaced:

Placeholder	Replacement
`WAVE`	Uppercase name of the wave (e.g., `M2`).
`wave`	Lowercase name of the wave (e.g., `m2`).
`Wave`	Capitalized name of the wave (e.g., `M2`).
`VAR`	Name of the variable (if present in the filename).

Note: If the file exists without any replacements, no substitutions are made.

Examples¶

Basic Correction¶

Correct soundings for waves M2 and S2 using the default atlas convention:

topo-detidor -p soundings.dat -a WAVE.spectral.nc -w M2 S2

Custom Variables¶

Use custom amplitude (a_eta_LGP2) and phase (G_eta_LGP2) variables:

topo-detidor -p soundings.dat -a WAVE.spectral.nc -v a_eta_LGP2 G_eta_LGP2 -w M2 S2

Output to a Custom File¶

Save the corrected soundings to a custom output file:

topo-detidor -p soundings.dat -a WAVE.spectral.nc -o corrected_soundings.dat -w M2 S2 K1

Correct for All Available Waves¶

Use a Bash trick to correct for all available waves in the current directory:

f=(*.spectral.nc)
topo-detidor -p soundings.dat -a WAVE.spectral.nc -v a_eta_LGP2 G_eta_LGP2 -w "${f[@]/.spectral.nc}"

Environment Variables¶

topo-detidor does not explicitly use environment variables for its core functionality. However, it relies on standard system libraries and may inherit environment settings from the shell (e.g., PATH for locating files).

Notes¶

Input File Format:
- The input file (-p) must be an ASCII file with the following columns: year month day hour minute second latitude longitude sounding.
- Columns can be separated by any non-numeric character (e.g., spaces, tabs, commas).
Atlas Files:
- Atlas files must follow the naming convention specified with -a.
- The tool expects amplitude and phase variables (default: Ha and Hg) to be present in the atlas files.
Output File:
- The output file (-o) contains the corrected soundings with additional columns for:
  - Tidal prediction (computed tidal height at the time and location of the sounding).
  - Corrected depth (raw sounding minus tidal prediction).
  - Amplitude and phase for each wave at the sounding location.
Time Handling:
- The tool assumes the input time is in seconds since the epoch (computed from year, month, day, hour, minute, second).
- The -s and -f options (start and end dates) are not fully implemented in the current version but are reserved for future use.
Performance:
- The tool processes soundings sequentially. For large datasets, consider splitting the input file into smaller chunks.