# 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

```bash
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](#wave-lists-spectra4) 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-lists-spectra4)=
## Wave List and Spectra

You can specify:

1. **Individual waves**  (run [showarg](../infos/showarg.md) to see the full list of available waves):
  - Majors ones are Q1 O1 P1 K1 N2 M2 S2 K2 M4 MS4. 
2. **Predefined spectra** (run [showarg](../infos/showarg.md) <spectra> 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:

```bash
detidor input_file.txt -o output_prefix
```

### **Detiding with a Custom Spectrum**

Detide using the `COASTAL-HF` spectrum:

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

### **Detiding with Specific Waves**

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

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

### **Detiding with Tidal Atlas**

Detide using a predefined tidal atlas:

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

### **Detiding for Altimetry Comparison**

Detide for comparison with altimetry data:

```bash
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):

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

### **Detiding with Custom Mooring Information**

Detide with mooring metadata:

```bash
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:

```bash
detidor input_file.txt -n 2 -o output_prefix
```

### **Detiding with CTOH Context**

Organize outputs in a structured directory for CTOH:

```bash
detidor input_file.txt -context ctoh -o output_prefix
```

### **Detiding with FFT and PSD**

Compute and save FFT and power spectral density:

```bash
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:**

```bash
OMP_NUM_THREADS=4 detidor input_file.txt -o output_prefix
```

---

## Notes

1. **Input Files:**
  - Must be in **ASCII format**.
  - Supported formats include `GLOSS`, `GNU`, `BODC`, `NETCDF`, etc.
2. **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.
3. **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.
4. **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.
5. **Debugging:**
  - Use `--debug` to enable debug mode for troubleshooting.
6. **Backward Compatibility:**
  - The `--discrete_parsing` option enables old/obsolete parsing methods for compatibility.

---

## See Also

- [`showarg`](https://www.comodo-ocean.fr/): List available waves for a spectrum.
- [CF Conventions for Time Coordinates](http://cfconventions.org/cf-conventions/cf-conventions.html#time-coordinate): Time formatting standards.