# tides-diagnostics v3.2.3

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

---

## Description

`tides-diagnostics` is a tool designed to **validate tidal atlases** based on harmonic analyses from tide gauges. It ensures the accuracy and reliability of tidal models by comparing them against observed data.

---

## Usage

```bash
tides-diagnostics -g file.mgr -a WAVE-file.nc wave1 [wave2 ...]
```

---

## Options


| Option                               | Description                                                                   |
| ------------------------------------ | ----------------------------------------------------------------------------- |
| `-b <file>`                          | Bathymetry database file.                                                     |
| `-d`                                 | Print differences between data and model outputs.                             |
| `-l`                                 | Output results in LaTeX format.                                               |
| `-m <convention>`, `-a <convention>` | **Deprecated.** Naming convention for tidal atlases. Use `-a` instead.        |
| `-p <path>`                          | Path to the directory containing tidal atlases.                               |
| `-o <file>`                          | Output file name.                                                             |
| `-c <file>`, `-g <file>`             | Harmonic data input file.                                                     |
| `-v <var1> <var2>`                   | Variables to analyze. Default: `Ha Hg`.                                       |
| `-x <order>`                         | Output order: `FILE`, `ALPHA`, `LAT`, `LON`, or `IMMERSION`.                  |
| `-h`                                 | Display help and exit.                                                        |
| `--unstructured <type>`              | Specify discretization type (`LGP1` or `LGP2`) for unstructured NetCDF files. |
| `--regions <file>`                   | Path to a file defining regions for analysis.                                 |
| `--polygons <file>`                  | Path to a file defining polygons for analysis.                                |
| `-i <index>`                         | Iteration index for analysis.                                                 |


---

## Examples

### **Basic Validation**

Validate a tidal atlas for waves `M2` and `S2`:

```bash
tides-diagnostics -g bathymetry.mgr -a M2-S2-atlas.nc M2 S2
```

### **Compare Data and Model**

Print differences between observed data and model outputs:

```bash
tides-diagnostics -g bathymetry.mgr -a M2-atlas.nc M2 -d
```

### **Output in LaTeX Format**

Generate results in LaTeX format for waves `K1` and `O1`:

```bash
tides-diagnostics -g bathymetry.mgr -a K1-O1-atlas.nc K1 O1 -l
```

### **Custom Output File**

Save results to a custom output file:

```bash
tides-diagnostics -g bathymetry.mgr -a M2-atlas.nc M2 -o results.txt
```

### **Specify Variables**

Analyze custom variables `amplitude` and `phase`:

```bash
tides-diagnostics -g bathymetry.mgr -a M2-atlas.nc M2 -v amplitude phase
```

### **Unstructured NetCDF File**

Validate an unstructured NetCDF file with `LGP2` discretization:

```bash
tides-diagnostics -g bathymetry.mgr -a unstructured-atlas.nc M2 --unstructured LGP2
```

### **Custom Output Order**

Specify the output order as `LAT`, `LON`:

```bash
tides-diagnostics -g bathymetry.mgr -a M2-atlas.nc M2 -x LAT LON
```

### **Use Regions and Polygons**

Validate using specific regions and polygons:

```bash
tides-diagnostics -g bathymetry.mgr -a M2-atlas.nc M2 --regions regions.txt --polygons polygons.plg
```

---

## Environment Variables

`tides-diagnostics` does not rely on specific environment variables. However, ensure that:

- Input files (bathymetry, tidal atlases, etc.) are accessible.
- Output directories have write permissions.

---

## Notes

1. **Deprecated Options:**
  - `-m` is deprecated. Use `-a` for naming conventions instead.
2. **Input Files:**
  - The harmonic data input file (`-c` or `-g`) must be in a compatible format.
  - For unstructured NetCDF files, specify the discretization type (`LGP1` or `LGP2`) using `--unstructured`.
3. **Output:**
  - If no output file is specified (`-o`), results are printed to the standard output.
  - Use `-l` to generate LaTeX-formatted output for reports or publications.
4. **Variables:**
  - By default, `Ha` (amplitude) and `Hg` (phase) are used. Override with `-v`.
5. **Performance:**
  - For large datasets, ensure sufficient disk space and memory.

---

## See Also

- [CF Conventions](http://cfconventions.org/) (for NetCDF file standards)
- [Tide Gauge Harmonic Analysis](https://www.ngdc.noaa.gov/mgg/tides/) (for reference data)