# tides-compare v3.2.3

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

---

## Description

`tides-compare` is a tool for **statistically comparing** the barotropic tidal harmonics of a reference file against one or more additional files. It specifically looks for the `Ha` (amplitude) and `Hg` (phase) variables in each file.

The comparisons are computed for:

- The **entire domain**.
- **Regions deeper than 500 meters**.

---

## Usage

```bash
tides-compare [OPTIONS] file1 [file2 ...]
```

---

## Options


| Option         | Description                                                                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-h`, `--help` | Display this help message and exit.                                                                                                                              |
| `-o <file>`    | Specify the **output file** for the comparison results. If not provided, a default name (`vector-difference.nc` or `<wave>.vector-difference.nc`) is used.       |
| `-b <file>`    | Specify the **bathymetry file** (must contain a `z` variable). If not provided, the default file `/home/softs/genesis/data/topography/data/gridone.grd` is used. |
| `-w <wave>`    | Specify the **tidal wave** to compare (only one wave is supported at a time).                                                                                    |
| `-c <file>`    | Path to a **tide gauges MGR file** to compute statistics at specific points.                                                                                     |
| `-p <file>`    | Path to a **polygon file** defining the working area for the comparison.                                                                                         |
| `-z <zone>`    | **Deprecated.** Name of a pre-set zone (no longer supported).                                                                                                    |


---

## Examples

### **Basic Comparison**

Compare tidal harmonics between two files:

```bash
tides-compare file1.nc file2.nc
```

### **Compare with Custom Output File**

Save the comparison results to a custom output file:

```bash
tides-compare -o my_comparison.nc file1.nc file2.nc
```

### **Compare for a Specific Tidal Wave**

Compare the `M2` tidal wave between two files:

```bash
tides-compare -w M2 file1.nc file2.nc
```

### **Compare Using a Custom Bathymetry File**

Use a custom bathymetry file for depth-based filtering:

```bash
tides-compare -b my_bathymetry.grd file1.nc file2.nc
```

### **Compare at Tide Gauge Locations**

Compute statistics at specific tide gauge locations:

```bash
tides-compare -c tide_gauges.mgr file1.nc file2.nc
```

### **Compare Within a Polygon Area**

Restrict the comparison to a specific polygon-defined area:

```bash
tides-compare -p my_polygon.txt file1.nc file2.nc
```

### **Full Example with All Options**

```bash
tides-compare -o M2_comparison.nc -b custom_bathy.grd -w M2 -c gauges.mgr -p area.poly file1.nc file2.nc
```

---

## Environment Variables

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

- Input files (NetCDF, bathymetry, MGR, polygon) are accessible.
- Output directories have **write permissions**.

---

## Notes

1. **Input Files:**
  - Must contain `Ha` (amplitude) and `Hg` (phase) variables for tidal harmonics.
  - The first file is used as the **reference** for comparison.
2. **Bathymetry:**
  - If `-b` is not specified, the tool uses the default bathymetry file: `/home/softs/genesis/data/topography/data/gridone.grd`.
  - Depth-based comparisons (e.g., `h > 500m`) are computed using the bathymetry data.
3. **Output:**
  - The output file contains:
    - **Norm** of the complex difference (`a`).
    - **Amplitude difference** (`G`).
    - **Phase lag difference** (in degrees).
    - **Complex error** statistics.
  - Statistics are computed for:
    - The entire domain.
    - Regions deeper than **500 meters**.
    - Regions deeper than **1000 meters**.
    - Tide gauge locations (if `-c` is used).
4. **Tide Gauges:**
  - The MGR file must be in a format compatible with the tool (e.g., `lon lat` pairs).
5. **Polygon:**
  - The polygon file defines the spatial area for the comparison. Points outside the polygon are excluded.
6. **Deprecated Options:**
  - The `-z` option (pre-set zones) is **no longer supported**.

---

## See Also

- [NetCDF Format](https://www.unidata.ucar.edu/software/netcdf/)
- [MGR File Format](https://www.comodo-ocean.fr/) (for tide gauges)
- [Polygon File Format](https://www.comodo-ocean.fr/) (for spatial masking)