# ensemble-extract v3.2.3

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

---

## Description

`ensemble-extract` is a tool designed to **extract specific tidal waves and ensemble members** from a **T-UGOm ensemble set**. It allows users to select specific waves and members, apply spatial limits, and customize the output file naming conventions.

---

## Usage

```bash
ensemble-extract [OPTIONS] wave1 [wave2 ...]
```

---

## Options


| Option                                    | Description                                                                |
| ----------------------------------------- | -------------------------------------------------------------------------- |
| `-h`, `--help`                            | Display help and exit.                                                     |
| `-p <path>`                               | Path to the **tidal atlas directory**.                                     |
| `-c <template>`                           | **Atlas file name convention**. See [Convention](#convention7) for details. |
| `-v <var1> <var2>`                        | Couple of **complex variables** (amplitude and phase) to extract.          |
| `-n <number>`                             | **Number of ensemble members** to extract.                                 |
| `-o <template>`                           | **Output file name template**.                                             |
| `--discretisation <pair>`                 | Discretisation pair for NetCDF input atlas.                                |
| `--polygons <file>`                       | File containing **polygons** to limit the extraction area.                 |
| `--frame <'lonmin,latmin,lonmax,latmax'>` | **Rectangular frame** (lon/lat bounds) to limit the extraction area.       |


> **Note:** The `--regions` option is **not functional** and should be ignored.

---

(convention7)=
## Convention

The naming convention for tidal atlases supports dynamic placeholders:


| Placeholder | Description                                                                                          |
| ----------- | ---------------------------------------------------------------------------------------------------- |
| `WAVE`      | Replaced by the **uppercase** wave name (e.g., `M2`).                                                |
| `wave`      | Replaced by the **lowercase** wave name (e.g., `m2`).                                                |
| `Wave`      | Replaced by the wave name with **only the first letter uppercase** (e.g., `M2` → `M2`, `K1` → `K1`). |
| `MEMBER`    | Replaced by the **ensemble member name**.                                                            |


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

---

## Examples

### **Extract a Single Wave**

Extract the `M2` wave using default settings:

```bash
ensemble-extract -p /path/to/atlases -c "WAVE_atlas.nc" -o "output_WAVE.nc" -v amp phase M2
```

### **Extract Multiple Waves**

Extract `M2` and `S2` waves:

```bash
ensemble-extract -p /path/to/atlases -c "WAVE_atlas.nc" -o "output_WAVE.nc" -v amp phase M2 S2
```

### **Limit Extraction to a Rectangular Frame**

Extract the `K1` wave within a specific geographic frame:

```bash
ensemble-extract -p /path/to/atlases -c "WAVE_atlas.nc" -o "output_WAVE.nc" \
  -v amp phase --frame "-10,40,10,60" K1
```

### **Limit Extraction to Polygons**

Extract the `O1` wave using a polygon file to define the area:

```bash
ensemble-extract -p /path/to/atlases -c "WAVE_atlas.nc" -o "output_WAVE.nc" \
  -v amp phase --polygons "selection.plg" O1
```

### **Extract a Specific Number of Members**

Extract the first 5 members for the `M2` wave:

```bash
ensemble-extract -p /path/to/atlases -c "WAVE_atlas.nc" -o "output_WAVE.nc" \
  -v amp phase -n 5 M2
```

### **Custom Discretisation**

Extract the `N2` wave with