metocean v3.2.3¶

Mercurial revision 5770:c90c3015e72d | 2026-05-22

Description¶

metocean is a tool designed to compute statistics on NetCDF files. It takes one or more files as input and generates statistical atlases (e.g., mean, standard deviation, min/max values) for the specified variables.

Usage¶

metocean file1 [file2 ...] [OPTIONS]

Options¶

Option	Description
`-h`, `--help`	Display help and exit.
`--take-first`	If time frames are simultaneous, use the first one.
`--take-last`	If time frames are simultaneous, use the last one.
`-c <convention>`	Currently without effect. Specify a convention (deprecated).
`-l <file>`	Path to a file containing a list of input files (overrides command-line file list).
`-g <file>`	Path to the grid file.
`-s <date>`	Start date for analysis. See Date Formats.
`-f <date>`	End date for analysis. See Date Formats.
`--time-origin <date>`	Default date origin. Replaces the deprecated `-o` option.
`-v <var1> [var2 ...]`	List of variables to compute statistics for.
`-z`	Use complex statistics. Requires 3 variables per field: amplitude, phase, and output.
`--vector`	Compute statistics for vector fields (e.g., currents).
`--output <dir>`	Output directory for results.
`-deflate <level>`	Set compression level (0-9) for output NetCDF files.

Date Formats¶

Supported formats:

yyyy/mm/dd HH:MM:SS.SSS
dd/mm/yyyy HH:MM:SS.SSS
mm/yyyy

Notes:

The least significant parts (seconds, minutes, hours, days, months) are optional.

The separator can be any non-numeric character (e.g., /, -, `` ).

End dates are inclusive. Examples:

2000 → 2001/01/01 00:00:00

2000/01 → 2000/02/01 00:00:00

2000/01/01 → 2000/01/02 00:00:00

2000/01/01 00 → 2000/01/01 01:00:00

2000/01/01 00:00 → 2000/01/01 00:01:00

Examples¶

Basic Statistics for a Single Variable¶

Compute statistics for the variable ssh (sea surface height):

metocean -v ssh input_file.nc

Statistics for Multiple Variables¶

Compute statistics for ssh, tem (temperature), and sal (salinity):

metocean -v ssh tem sal input_file1.nc input_file2.nc

Statistics with a File List¶

Use a file containing a list of NetCDF files:

metocean -l file_list.txt -v ssh tem

Time Range Selection¶

Compute statistics for a specific time range:

metocean -s 01/01/2020 -f 31/12/2020 -v ssh input_file.nc

Complex Statistics¶

Compute complex statistics for amplitude, phase, and output variables:

metocean -z -v amplitude phase output input_file.nc

Vector Statistics¶

Compute statistics for vector fields (e.g., currents u and v):

metocean --vector -v u v input_file.nc

Output to a Specific Directory¶

Save results in a custom directory:

metocean --output /path/to/output -v ssh input_file.nc

Compression for Output Files¶

Set compression level for output NetCDF files (e.g., level 5):

metocean -deflate 5 -v ssh input_file.nc

Handling Simultaneous Time Frames¶

Use the first or last time frame if multiple frames are simultaneous:

metocean --take-first -v ssh input_file.nc

metocean --take-last -v ssh input_file.nc

Environment Variables¶

metocean uses OpenMP (version 201511) for parallelization. Key environment variables:

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 metocean -v ssh input_file.nc

Note: If running on a busy machine, limit threads to the number of free CPUs to avoid performance degradation.

Notes¶

Input Files:

Must be NetCDF files.
The time variable must follow CF conventions (if applicable).

Output:

Statistical atlases are generated for each specified variable.
Results are saved in the specified output directory (--output).

Complex Statistics (-z):

Requires 3 variables per field: amplitude, phase, and output.
Example: -v amp phase output computes complex statistics for the field defined by these three variables.

Vector Statistics (--vector):

Used for vector fields (e.g., currents u and v).
Computes statistics for each component separately.

Simultaneous Time Frames:

Use --take-first or --take-last to handle cases where multiple time frames have the same timestamp.

Deprecated Options:

-o is deprecated. Use --time-origin instead.
-c is currently without effect.