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¶

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:

altimetry-decimate -g harmonic_constants.mgr M2

Decimate with Custom Resolution¶

Set custom resolutions for deep ocean and shelf seas:

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:

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:

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:

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:

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:

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:

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¶

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

Output:

By default, the output is saved as filtered.mgr.
Use -o to specify a custom output file.

Bathymetry:

The -b option is required for deep/shelf separation.

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.

Resolution:

-resolution_deep and -resolution_shelf control the along-track resolution for decimation.

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.