# 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

```bash
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](#date-formats4).                                   |
| `-f <date>`            | End date for analysis. See [Date Formats](#date-formats4).                                     |
| `--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-formats4)=
## 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):

```bash
metocean -v ssh input_file.nc
```

### **Statistics for Multiple Variables**

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

```bash
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:

```bash
metocean -l file_list.txt -v ssh tem
```

### **Time Range Selection**

Compute statistics for a specific time range:

```bash
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:

```bash
metocean -z -v amplitude phase output input_file.nc
```

### **Vector Statistics**

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

```bash
metocean --vector -v u v input_file.nc
```

### **Output to a Specific Directory**

Save results in a custom directory:

```bash
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):

```bash
metocean -deflate 5 -v ssh input_file.nc
```

### **Handling Simultaneous Time Frames**

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

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

or

```bash
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:**

```bash
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

1. **Input Files:**
  - Must be **NetCDF** files.
  - The time variable must follow **CF conventions** (if applicable).
2. **Output:**
  - Statistical atlases are generated for each specified variable.
  - Results are saved in the specified output directory (`--output`).
3. **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.
4. **Vector Statistics (`--vector`):**
  - Used for **vector fields** (e.g., currents `u` and `v`).
  - Computes statistics for each component separately.
5. **Simultaneous Time Frames:**
  - Use `--take-first` or `--take-last` to handle cases where multiple time frames have the same timestamp.
6. **Deprecated Options:**
  - `-o` is deprecated. Use `--time-origin` instead.
  - `-c` is currently **without effect**.

---

## See Also

- [NetCDF CF Conventions](http://cfconventions.org/cf-conventions/cf-conventions.html)
- [OpenMP Documentation](https://www.openmp.org/)