# altimetry-decimate v3.2.3

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

---

## Description

`altimetry-decimate` is a tool designed to **decimate altimetric analysis databases**. It processes harmonic constants and applies filters based on depth, resolution, and error thresholds to refine the dataset.

---

## Usage

```bash
altimetry-decimate [OPTIONS] input
```

---

## Options


| Option                      | Description                                                                             |
| --------------------------- | --------------------------------------------------------------------------------------- |
| `--help`, `-h`              | Display help and exit.                                                                  |
| `-g <file>`                 | Path to the **harmonic constants database** (input).                                    |
| `-merge <file>`             | Optional harmonic constants database to **merge with the execution output**.            |
| `-b <file>`                 | Path to the **bathymetry file** (used for deep/shelf separation).                       |
| `-p <file>`                 | Path to the **selection polygon file** (for spatial filtering).                         |
| `-z <name>`                 | Name of the **selection zone**.                                                         |
| `-resolution_deep <value>`  | Targeted **along-track resolution in deep ocean** (default: `200.0`).                   |
| `-resolution_shelf <value>` | Targeted **along-track resolution in shelf seas** (default: `20.0`).                    |
| `-min_depth <value>`        | **Minimum eligible depth** (default: `0.0`).                                            |
| `-max_depth <value>`        | **Maximum eligible depth** (default: `-20000.0`).                                       |
| `-error <value>`            | **Maximum eligible analysis error** (default: `0.005`).                                 |
| `-max_ratio <value>`        | **Maximum eligible noise/signal ratio** (default: `1e+35`, presumably less than `1.0`). |
| `-c <convention>`           | Atlas file naming **convention**.                                                       |
| `-o <file>`                 | Path to the **output file** (default: `filtered.mgr`).                                  |


---

## Examples

### **Basic Decimation**

Decimate a harmonic constants database with default parameters:

```bash
altimetry-decimate -g harmonic_constants.mgr M2
```

### **Decimate with Custom Resolution**

Set custom resolutions for deep ocean and shelf seas:

```bash
altimetry-decimate -g harmonic_constants.mgr \
  -resolution_deep 150.0 \
  -resolution_shelf 10.0 \
  M2 S2
```

### **Filter by Depth**

Apply depth filters to exclude shallow or deep areas:

```bash
altimetry-decimate -g harmonic_constants.mgr \
  -min_depth 10.0 \
  -max_depth -5000.0 \
  M2
```

### **Filter by Error and Noise/Signal Ratio**

Exclude data with high analysis error or noise/signal ratio:

```bash
altimetry-decimate -g harmonic_constants.mgr \
  -error 0.01 \
  -max_ratio 0.5 \
  M2 K1
```

### **Merge with Additional Database**

Merge the output with an existing harmonic constants database:

```bash
altimetry-decimate -g harmonic_constants.mgr \
  -merge additional_constants.mgr \
  -o merged_output.mgr \
  M2
```

### **Spatial Filtering with Polygon**

Apply spatial filtering using a polygon file:

```bash
altimetry-decimate -g harmonic_constants.mgr \
  -p selection_polygon.txt \
  -z "North Atlantic" \
  M2 S2
```

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

Combine multiple filters and options:

```bash
altimetry-decimate -g harmonic_constants.mgr \
  -b bathymetry.nc \
  -p selection_polygon.txt \
  -z "North Atlantic" \
  -resolution_deep 150.0 \
  -resolution_shelf 10.0 \
  -min_depth 10.0 \
  -max_depth -5000.0 \
  -error 0.01 \
  -max_ratio 0.5 \
  -o filtered_output.mgr \
  M2 S2 K1 O1
```

---

## Environment Variables

`altimetry-decimate` uses **OpenMP** (version 201511) for parallelization. The following environment variables can be used to control its behavior:


| 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-decimate -g harmonic_constants.mgr M2
```

> **Note:** If running on a machine with high CPU load, limit the number of threads to the number of **free CPUs** to avoid performance degradation.

---

## Notes

1. **Input Requirements:**
  - The input must be a **harmonic constants database** (e.g., `.mgr` file).
  - At least **one tidal wave** must be specified (e.g., `M2`, `S2`, `K1`).
2. **Output:**
  - By default, the output is saved as `filtered.mgr`.
  - Use `-o` to specify a custom output file.
3. **Bathymetry:**
  - The `-b` option is required for **deep/shelf separation**.
4. **Polygon Selection:**
  - The `-p` option requires a **polygon file** to define the spatial selection area.
  - The `-z` option assigns a **name** to the selection zone.
5. **Resolution:**
  - `-resolution_deep` and `-resolution_shelf` control the **along-track resolution** for decimation.
6. **Error and Ratio Filters:**
  - `-error` filters out data with analysis errors exceeding the specified threshold.
  - `-max_ratio` filters out data with a noise/signal ratio exceeding the specified threshold.

---

## See Also

- [OpenMP Documentation](https://www.openmp.org/) (for environment variables and parallelization)
- [CF Conventions](http://cfconventions.org/) (for time and coordinate standards in NetCDF files)