# tides-sample v3.2.3

**Mercurial revision 5770:c90c3015e72d | 2026-05-22**

---

## Description

`tides-sample` extracts specific locations from a **tidal atlas** into **MGR files** to build **synthetic tide gauges**. This tool is useful for generating time series of tidal predictions at specified locations based on precomputed tidal atlases.

---

## Usage

```bash
tides-sample [OPTIONS] wave1 [wave2 ...]
```

---

## Options


| Option            | Description                                                                                                                |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `-h`, `--help`    | Show this help and exit.                                                                                                   |
| `-l <file>`       | File listing all the locations to extract. The file should contain the coordinates (longitude, latitude) of each location. |
| `-a <convention>` | Naming convention for the atlas files. See [Convention](#convention43) below.                                                |
| `-p <path>`       | Path to the list of control points. This can be:                                                                           |


- An **ASCII file** with the number of control points followed by their coordinates (longitude, latitude).
- A **pattern of NetCDF files** containing `latitude`, `longitude`, and `time` variables (see also `-o` option).
- If not provided, predictions are made for **all points** in the atlas. |  
| `-o <path>` | Path for the output file. The output format depends on the input:
- **NetCDF** if:
  - `-p` is not provided, **or**
  - `-p` specifies a NetCDF file with a `time` variable, **or**
  - `-o` is followed by a `.nc` extension.
- **ASCII** otherwise. |

---

(convention43)=
## Convention

The atlas file naming convention supports the following placeholders:

- `WAVE`: Replaced by the **uppercase** name of the wave (e.g., `M2`).
- `wave`: Replaced by the **lowercase** name of the wave (e.g., `m2`).
- `Wave`: Replaced by the **capitalized** name of the wave (e.g., `M2`).

> **Note:** If the file exists without any replacements, no substitution is performed.

---

## Examples

### **Extract Tidal Data for Specific Locations**

Extract tidal data for locations listed in `locations.txt` using the default atlas convention:

```bash
tides-sample -l locations.txt M2 S2 K1 O1
```

### **Specify a Custom Atlas Convention**

Use a custom naming convention for atlas files (e.g., `tidal_atlas_{WAVE}.nc`):

```bash
tides-sample -a "tidal_atlas_{WAVE}.nc" -l locations.txt M2 S2
```

### **Extract Data for All Points in the Atlas**

Extract tidal data for all points in the atlas (no `-p` option):

```bash
tides-sample -o output.nc M2 S2 K1
```

### **Output to ASCII File**

Extract tidal data and save to an ASCII file:

```bash
tides-sample -l locations.txt -o output.txt M2 S2
```

### **Use NetCDF Control Points**

Specify control points from a NetCDF file containing `latitude`, `longitude`, and `time` variables:

```bash
tides-sample -p control_points.nc -o output.nc M2 S2 K1
```

---

## Environment Variables

This tool does not rely on specific environment variables. However, ensure that:

- Input files (atlas, locations, control points) are accessible.
- Output directories have **write permissions**.

---

## Notes

1. **Input Files:**
  - The `-l` file must contain valid coordinates (longitude, latitude) for each location.
  - If `-p` is not provided, predictions are made for **all points** in the atlas.
2. **Output Format:**
  - The output format (NetCDF or ASCII) is determined automatically based on the input options.
  - If `-o` ends with `.nc`, the output is always in **NetCDF** format.
3. **Wave List:**
  - Waves must be specified as arguments (e.g., `M2`, `S2`, `K1`).
  - The tool supports **any valid tidal constituent** recognized by the atlas.
4. **Atlas Convention:**
  - The `-a` option allows flexibility in specifying the naming pattern for atlas files.
  - Placeholders (`WAVE`, `wave`, `Wave`) are replaced dynamically.
5. **Unused Options:**
  - `-c`: Name of the output MGR file (**not used** in the current version).
  - `-m`: Mesh file of the atlas (**not used** in the current version).

---

## See Also

- [Tidal Atlas Documentation](https://www.comodo-ocean.fr/)
- [MGR File Format](https://www.comodo-ocean.fr/)
- [NetCDF Conventions](https://www.unidata.ucar.edu/software/netcdf/)