altimetry-detidor v3.2.3¶

Mercurial revision 5770:c90c3015e72d | 2026-05-22

Description¶

altimetry-detidor is a tool designed to detide altimetric data series from X-TRACK inputs. It is used by CTOH (Centre de Topographie des Océans et de l’Hydrosphère).

The tool processes input files (e.g., input.nc) and generates:

input.mgr (or input.mgr.nc if -f NETCDF is specified)
input.mgr.stat (statistics file)
input.res.dat (residual data file, unless -np is used)

Usage¶

altimetry-detidor OPTIONS input.nc

Options¶

General Options¶

Option	Description
`--help`, `-h`	Display help and exit.
`--info`	Show Rayleigh criteria for several missions and exit.
`--debug`	Enable verbose debugging output.
`-verbose <level>`	Set verbosity level (e.g., `-verbose 2` enables additional output).

Spectrum and Corrections¶

Option	Description
`-spectrum <name>`	Name of the spectrum for analysis. Default: `COASTAL`. See Spectrum for available options.
`--dac=no`	Disable GDR DAC correction.
`--tide=no`	Disable GDR tide correction. Use `-o` to specify custom ocean tide corrections.
`-a <atlas>`	Atlas name for tidal dealiasing spectrum. Available options: `GLORYS-v2`, `FES2004`, `FES2012`, `FES2014`, `GOT4.7`, `MEDSEA`, `NEA`, `PERSIAN`.
`-o <convention> <amp_var> <phase_var>`	Apply custom ocean tide correction instead of GDR tide. Requires 3 parameters: convention, amplitude variable name, and phase lag variable name.
`-l <convention> <amp_var> <phase_var>`	Apply load tide correction (for geocentric series only). Requires 3 parameters: convention, amplitude variable name, and phase lag variable name.
`-ogcm_parameters <convention> <amp_var> <phase_var>`	Apply GLORYS corrections. Requires 3 parameters: convention, amplitude variable name, and phase lag variable name.

Date and Data Filtering¶

Option	Description
`-s <date>`	Start date for analysis (format: `dd/mm/yyyy`).
`-e <date>`	End date for analysis (format: `dd/mm/yyyy`).
`-latmin <value>`	Minimum absolute latitude to exclude (e.g., `-latmin 10` excludes latitudes below 10°).

Analysis and Output¶

Option	Description
`-cm`	Atlas amplitude units are in centimeters (default: meters).
`-percent <n>`, `-m <n>`	Minimum number of elements in the time series (default: `160`).
`--sla-range <[min:max]>`	Validity range for SLA (Sea Level Anomaly). Values outside this range are blacklisted. Default: `[-INFINITY:+INFINITY]` (no blacklisting).
`--auto-parse`	Use matrix coefficient instead of Rayleigh criterion for tidal wave separability.
`--max-ratio <value>`	Cross-correlation threshold in harmonic matrix for constituent separability (default: `0.3`).
`--averaging <time>`	Deprecated. Use `--averaging-interval` instead.
`--averaging-interval <[min:max]>`	Time integration range (in seconds) for time-averaged data (e.g., `"[-3600:0]"` for hourly averages).
`-r <days>`	Repetitivity of measurements in days (default: `0`). Required for error budgets.
`-b <budget>`	Error budget type. Currently supports: `psd` (default: `none`). Requires `-r`.
`-f <format>`	Output format for tide gauge data: `ASCII` (default) or `NETCDF`.
`--save_psd`	Save the power spectral density in `psd_r1_c.py`. Requires `-r` and `-b psd`.

Performance and Parallelization¶

Option	Description
`-np <n>`	Number of CPU cores to use. Default: `1`. Use `-1` to use all available cores. Enables OpenMP parallelization and disables residual output.
`-gnu=yes`	Save ASCII data (time, height, DAC parameters, tidal atlas parameters, residual) in a `.gnu` file for use with tools like gnuplot. Disabled if `-np` is used.

Spectrum¶

The spectrum can be specified as:

Predefined spectra (run showarg to get associated waves and the duration needed for wave separation) :

ESTUARINE
ESTUARINE-HF
COMODO
COASTAL (default)
COASTAL-HF
SHELF
SHELF-HF
DEEP
DEEP-HF
REDUCED
CURRENTS-HF
FES2022c
AVISO-FES-SP
AVISO-FES-ADMITTANCE
AVISO-FES-LP
AVISO-FES-LP-PROXY

Custom spectrum:

Provide an ASCII file with the number of waves, followed by each wave’s details:
- An integer (≠ 999)
- Wave name (case-insensitive)
- A non-blank separator (e.g., comma ,)
- An ignored number (placeholder)

Examples¶

Basic Detiding¶

Detide an input file using the default COASTAL spectrum:

altimetry-detidor input.nc

Custom Spectrum and Output Format¶

Detide using the FES2014 spectrum and save output in NetCDF format:

altimetry-detidor -spectrum FES2014 -f NETCDF input.nc

Disable GDR Corrections¶

Detide without applying GDR DAC or tide corrections:

altimetry-detidor --dac=no --tide=no input.nc

Custom Ocean Tide Correction¶

Apply a custom ocean tide correction using a specific atlas:

altimetry-detidor -a FES2014 -o "/path/to/atlas/WAVE.nc" amp_var phase_var input.nc

Load Tide Correction (Geocentric Series)¶

Apply a load tide correction for geocentric data:

altimetry-detidor -l "/path/to/load/WAVE.nc" load_amp_var load_phase_var input.nc

GLORYS Corrections¶

Apply GLORYS corrections for dealiasing:

altimetry-detidor -ogcm_parameters "/path/to/ogcm/WAVE.nc" ogcm_amp_var ogcm_phase_var input.nc

Date Range and Latitude Filter¶

Process data between 01/01/2020 and 31/12/2020, excluding latitudes below 10°:

altimetry-detidor -s 01/01/2020 -e 31/12/2020 -latmin 10 input.nc

Parallel Processing¶

Use 4 CPU cores for parallel processing:

altimetry-detidor -np 4 input.nc

Save Power Spectral Density¶

Save the power spectral density for error budget analysis:

altimetry-detidor -r 10 -b psd --save_psd input.nc

Custom SLA Range¶

Blacklist SLA values outside the range [-1, 1]:

altimetry-detidor --sla-range "[-1:1]" input.nc

GNU Plot Output¶

Save data in a .gnu file for plotting with gnuplot:

altimetry-detidor -gnu=yes input.nc

Environment Variables¶

altimetry-detidor uses OpenMP (version 201511) for parallelization. Key environment variables:

Variable	Description
`OMP_NUM_THREADS`	Number of threads to use.
`OMP_SCHEDULE`	Runtime schedule type and chunk size.
`OMP_DYNAMIC`	Enable/disable dynamic thread adjustment.
`OMP_NESTED`	Enable/disable nested parallelism.

Example:

OMP_NUM_THREADS=6 altimetry-detidor input.nc

Note: If running on a busy machine, limit threads to the number of free CPUs to avoid performance degradation.

Notes¶

Input Files:

Must be X-TRACK SLA reference files (e.g., input.nc).

Output Files:

input.mgr or input.mgr.nc: Tidal constants and analysis results.
input.mgr.stat: Statistics for each track (mean, std, etc.).
input.res.dat: Residual data (disabled if -np is used).

Conventions for Atlas Files:

The convention path must include the term WAVE as a placeholder for the tidal wave name.
Example: /home/softs/data/climatology/GLORYS-v2/WAVE.GLORYS.nc

Error Budgets:

Requires -r (repetitivity) and -b (budget type, e.g., psd).
--save_psd saves the power spectral density for further analysis.

Parallelization:

Using -np > 1 enables OpenMP and disables residual output.
-gnu=yes is disabled if -np is used.

Deprecated Options:

-satellite: No longer used (ignored if provided).