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¶

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 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.

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:

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:

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:

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:

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:

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