# meteo-filter v3.2.3

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

---

## Description

`meteo-filter` is a tool designed to **filter meteorological forcing data**. It processes input files, applies a harmonic filter to remove unwanted frequencies (such as tidal signals), and outputs the filtered data in a specified format.

---

## Usage

```bash
meteo-filter [OPTIONS]
```

---

## Options


| Option                 | Description                                                              | Default        |
| ---------------------- | ------------------------------------------------------------------------ | -------------- |
| `-h`, `--help`         | Display help and exit.                                                   | -              |
| `-p <dir>`             | Archive directory where input files are stored.                          | `./`           |
| `-c <convention>`      | Archive file name convention. See [Convention](#convention10) for details. | `EA_YYYYMM.EC` |
| `-s <date>`            | Start date for filtering. See [Date Formats](#date-formats3) for details. | **Mandatory**  |
| `-f <date>`            | End date for filtering. See [Date Formats](#date-formats3) for details.   | **Mandatory**  |
| `-v <var1> [var2 ...]` | List of variables to filter (e.g., `temperature`, `wind_speed`).         | **Mandatory**  |
| `--landmask <file>`    | Path to a land mask file (optional).                                     | -              |


---

(convention10)=
## Convention

The file name convention uses placeholders to dynamically generate file names based on dates. The following placeholders are supported:


| Placeholder | Description      | Range     |
| ----------- | ---------------- | --------- |
| `YYYY`      | Year (4 digits)  | 0000–9999 |
| `MM`        | Month            | 01–12     |
| `DD`        | Day of the month | 01–31     |
| `HH`        | Hour of the day  | 00–23     |


**Example:**

- `EA_YYYYMM.EC` → `EA_202605.EC` (for May 2026).

---

(date-formats3)=
## Date Formats

The following date formats are accepted:

- `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 Filtering**

Filter variables `temperature` and `wind_speed` from May 1, 2026, to May 10, 2026:

```bash
meteo-filter -p /path/to/archive \
  -c EA_YYYYMM.EC \
  -s 01/05/2026 \
  -f 10/05/2026 \
  -v temperature wind_speed
```

### **Filtering with Custom Convention**

Use a custom file naming convention (`data_YYYYMMDD.nc`):

```bash
meteo-filter -p /path/to/archive \
  -c data_YYYYMMDD.nc \
  -s 2026/05/01 \
  -f 2026/05/10 \
  -v precipitation
```

### **Filtering with Land Mask**

Apply a land mask during filtering:

```bash
meteo-filter -p /path/to/archive \
  -s 2026/05/01 \
  -f 2026/05/10 \
  -v humidity \
  --landmask /path/to/landmask.nc
```

### **Filtering for a Single Day**

Filter data for a single day (January 15, 2026):

```bash
meteo-filter -p /path/to/archive \
  -s 15/01/2026 \
  -f 15/01/2026 \
  -v pressure
```

---

## Environment Variables

`meteo-filter` uses **OpenMP** for parallelization. Key environment variables:


| Variable          | Description                                       |
| ----------------- | ------------------------------------------------- |
| `OMP_NUM_THREADS` | Number of threads to use for parallel processing. |
| `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=4 meteo-filter -p /path/to/archive -s 01/05/2026 -f 10/05/2026 -v temperature
```

> **Note:** Adjust `OMP_NUM_THREADS` based on your system's available CPU cores to optimize performance.

---

## Notes

1. **Input Files:**
  - Must follow the specified **file name convention** (default: `EA_YYYYMM.EC`).
  - The tool expects files to be stored in the directory specified by `-p`.
2. **Output:**
  - Filtered data is saved in files with the prefix `filtered-` followed by the original file name (e.g., `filtered-EA_202605.EC`).
3. **Performance:**
  - For large datasets, consider using **OpenMP** to speed up processing by setting `OMP_NUM_THREADS`.
  - The tool is optimized for **1-hour ERA5 data** but may require adjustments for other temporal resolutions.
4. **Land Mask:**
  - The `--landmask` option is useful for excluding land areas from the analysis.
5. **Date Handling:**
  - If no end date (`-f`) is provided, it defaults to the start date (`-s`) in an inclusive manner.

---

## See Also

- [OpenMP Documentation](https://www.openmp.org/) (for parallelization options)
- [GRIB-API Documentation](https://confluence.ecmwf.int/display/GRIB) (if compiled with GRIB support)