# 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

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

---

(convention45)=
## 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:
```bash
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:
```bash
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:
```bash
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:
```bash
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

1. **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).

2. **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.

3. **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.

4. **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.

5. **Performance:**
   - The tool processes soundings **sequentially**. For large datasets, consider splitting the input file into smaller chunks.

---

## See Also

- [CF Conventions for Time Coordinates](http://cfconventions.org/cf-conventions/cf-conventions.html#time-coordinate) (for time handling best practices)
- [`comodo-detidor`](https://www.comodo-ocean.fr/) (for generating tidal atlases)
- [`showarg`](https://www.comodo-ocean.fr/) (for listing available tidal waves)