# 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

```bash
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](#spectra) 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. |


---

(spectra)=
## Spectrum

The spectrum can be specified as:

1. **Predefined spectra** (run [showarg](../infos/showarg.md) <spectra> 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`
2. **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:

```bash
altimetry-detidor input.nc
```

### **Custom Spectrum and Output Format**

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

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

### **Disable GDR Corrections**

Detide without applying GDR DAC or tide corrections:

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

### **Custom Ocean Tide Correction**

Apply a custom ocean tide correction using a specific atlas:

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

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

### **GLORYS Corrections**

Apply GLORYS corrections for dealiasing:

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

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

### **Parallel Processing**

Use 4 CPU cores for parallel processing:

```bash
altimetry-detidor -np 4 input.nc
```

### **Save Power Spectral Density**

Save the power spectral density for error budget analysis:

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

### **Custom SLA Range**

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

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

### **GNU Plot Output**

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

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

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

1. **Input Files:**
  - Must be **X-TRACK SLA reference** files (e.g., `input.nc`).
2. **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).
3. **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`
4. **Error Budgets:**
  - Requires `-r` (repetitivity) and `-b` (budget type, e.g., `psd`).
  - `--save_psd` saves the power spectral density for further analysis.
5. **Parallelization:**
  - Using `-np > 1` enables OpenMP and disables residual output.
  - `-gnu=yes` is disabled if `-np` is used.
6. **Deprecated Options:**
  - `-satellite`: No longer used (ignored if provided).

---

## See Also

- [X-TRACK Documentation](https://www.legos.obs-mip.fr/en/soa/duacs/)
- [CTOH (Centre de Topographie des Océans et de l'Hydrosphère)](https://ctoh.legos.obs-mip.fr/)
- [OpenMP Documentation](https://www.openmp.org/)