detidor v3.2.3¶

Mercurial revision 5770:c90c3015e72d | 2026-05-22

Description¶

detidor is a command-line tool designed to detide time series data from ASCII-formatted input files. It performs harmonic analysis and generates detided outputs, harmonic constants, and residual time series.

Note: The input file must be in ASCII format.

Usage¶

detidor FILE [OPTIONS]

Options¶

Input/Output Options¶

Option	Description
`-h`, `--help`	Display help and exit.
`-format <format>`	Specify the time series format. Supported formats: `BODC`, `BODC2`, `CANADA`, `DART`, `DMY`, `FOREMAN`, `GESLA`, `GLOSS`, `GNU`, `HAWAII`, `HAWAII_NC`, `LEGEND`, `LIST`, `LIST2`, `MINH`, `NETCDF`, `PAB`, `PROFILERS`, `PUERTOS`, `RADAR`, `RADAR_RAW`, `REFMAR`, `RMN`, `SEINE`, `SONEL_HR`, `USER`, `YMD`. Default: `GLOSS` (also works for `JASL`).
`--residual-format <format>`	Specify the format for residual output. Default: `GNU`.
`-context <format>`	Use `ctoh` to automatically organize outputs in a structured directory.
`--mooring=<info>`	Input mooring information (e.g., `"lon=<lon> lat=<lat> code=<code> name=<name> depth=<depth>"`).
`-tides <files>`	Convention for tidal atlas files. If not provided, harmonic analysis is performed.
`-o <out_prefix>`	Prefix for output files.
`--no-date`	Disable dates in output file names.
`-n <ncols>`	Number of columns in ASCII GNU format input file. Default: `1`.

Analysis Options¶

Option	Description
`-spectrum <SPECTRA>`	Specify a predefined spectrum or a file. Default: `COASTAL`. See Wave List and Spectra for available spectra.
`-w <wave1> [wave2 ...]`	List of waves to predict.
`--save-timeseries=yes/no`	Save or do not save the raw time series as the first column in the output file. Default: `yes`.
`--FFT=yes/no`	Compute and save the FFT of the time series and its residual. Default: `yes`.
`--save_psd`	Save the power spectral density in `psd_r1_c.py` (requires FFT).
`-cm`	Use if the atlas is in centimeters.
`--averaging <time_span>`	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).

Advanced Options¶

Option	Description
`--time <template>`	Time template for output files.
`--delimiter <char>`	Delimiter for input files. Default: `" "`.
`--sort <method>`	Sort harmonic constants by method (e.g., `FREQUENCY`). Default: `FREQUENCY`.
`-target <index>`	Target index for analysis.
`-maxratio <value>`	Maximum ratio for discrete parsing. Default: `0.3`.
`-rayleigh <value>`	Rayleigh ratio for harmonic analysis. Default: `1.0`.
`-repetition <value>`	Repetition value for discrete parsing.
`--center <name>`	Center name for metadata.
`--debug`	Enable debug mode.
`--prefix <prefix>`	Prefix for output files.
`--suffix <suffix>`	Suffix for output files.
`--split=yes/no`	Split time series into multiple files. Default: `yes`.
`-step <n>y or <n>m`	Split time series into chunks of `n` years or `n` months. Default: process all at once.
`--time-format <format>`	Time format for input files.

Backward Compatibility Options¶

Option	Description
`--discrete_parsing`	Use old/obsolete discrete parsing.
`-c <atlas_type>`	Specify the atlas file name convention: `<prefix>wave<postfix>`.
`-l <stations_list>`	Save the station list to `<stations_list>`.

Undocumented Options¶

Option	Description
`--time`	(Undocumented)
`--split`	(Undocumented)
`-averaging`	(Undocumented)
`--HF`	(Undocumented)

Wave List and Spectra¶

You can specify:

Individual waves (run showarg to see the full list of available waves):

Majors ones are Q1 O1 P1 K1 N2 M2 S2 K2 M4 MS4.

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

ESTUARINE
ESTUARINE-HF
COMODO
COASTAL
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

Examples¶

Basic Detiding¶

Detide a time series using the default COASTAL spectrum:

detidor input_file.txt -o output_prefix

Detiding with a Custom Spectrum¶

Detide using the COASTAL-HF spectrum:

detidor input_file.txt -spectrum COASTAL-HF -o output_prefix

Detiding with Specific Waves¶

Detide for specific waves (e.g., M2, S2, K1):

detidor input_file.txt -w M2 S2 K1 -o output_prefix

Detiding with Tidal Atlas¶

Detide using a predefined tidal atlas:

detidor input_file.txt -tides tides_atlas.nc -o output_prefix

Detiding for Altimetry Comparison¶

Detide for comparison with altimetry data:

detidor --no-date -tides $DATA_DIR/tides/FES2022/DOI/WAVE.FES2022.nc -spectrum COASTAL-HF -o output_prefix

Detiding with Time Averaging¶

Specify a time-averaging interval of [-3600:0] (1 hour backward):

detidor input_file.txt --averaging-interval "[-3600:0]" -o output_prefix

Detiding with Custom Mooring Information¶

Detide with mooring metadata:

detidor input_file.txt --mooring="lon=2.35 lat=48.85 code=STN01 name=Station1 depth=10" -o output_prefix

Detiding with Multiple Columns¶

Detide a file with 2 columns:

detidor input_file.txt -n 2 -o output_prefix

Detiding with CTOH Context¶

Organize outputs in a structured directory for CTOH:

detidor input_file.txt -context ctoh -o output_prefix

Detiding with FFT and PSD¶

Compute and save FFT and power spectral density:

detidor input_file.txt --FFT=yes --save_psd -o output_prefix

Environment Variables¶

detidor does not explicitly rely on environment variables, but its performance can be influenced by system-level settings, such as:

OMP_NUM_THREADS: Number of threads for parallel processing (if OpenMP is used internally).
OMP_SCHEDULE: Runtime schedule type and chunk size for OpenMP.

Example:

OMP_NUM_THREADS=4 detidor input_file.txt -o output_prefix

Notes¶

Input Files:

Must be in ASCII format.
Supported formats include GLOSS, GNU, BODC, NETCDF, etc.

Output Files:

Detided time series, harmonic constants (*.mgr), and residual files are generated.
Use -o to specify the output prefix.
Use --no-date to disable dates in output file names.

Performance:

For large datasets, consider splitting the time series using -step (e.g., -step 1y for yearly chunks).
Use -context ctoh to automatically organize outputs in a structured directory.

Harmonic Analysis:

The default spectrum is COASTAL. Use -spectrum to specify a different spectrum.
Use -w to specify a custom list of waves for prediction.

Debugging:

Use --debug to enable debug mode for troubleshooting.

Backward Compatibility:

The --discrete_parsing option enables old/obsolete parsing methods for compatibility.