# timeseries-validate v3.2.3

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

---

## Description

`timeseries-validate` is a tool for performing **operations on time series data**. It supports three main tasks:

- **Validation**: Compare time series between `--data` and `--simulation` inputs.
- **Ocean-zero**: Compute statistics for `[(msl - mdt) over geoid(s)]` for each station, each year.
- **Operation**: Add time series from `--data` and `--simulation` inputs.

---

## Usage

```bash
timeseries-validate <file> [options]
```

---

## Options

### **General Options**


| Option         | Description            |
| -------------- | ---------------------- |
| `-h`, `--help` | Display help and exit. |


---

### **Task Options**


| Option          | Description                                                                                  |
| --------------- | -------------------------------------------------------------------------------------------- |
| `--task <task>` | Specify the task to perform. **Options:** `ocean-zero`, `validation` (default), `operation`. |


> **Task Details:**
>
> - **`validation`**: Compares time series between `--data` and `--simulation` inputs.
> - **`ocean-zero`**: Computes `[(msl - mdt) over geoid(s)]` statistics for each station, each year.
> - **`operation`**: Adds time series from `--data` and `--simulation` inputs.

---

### **Input/Output Options**


| Option                | Description                                                                               |
| --------------------- | ----------------------------------------------------------------------------------------- |
| `<file>`              | Input file to process.                                                                    |
| `-s <dd/mm/yyyy>`     | Start date for the time series.                                                           |
| `-f <dd/mm/yyyy>`     | End date for the time series.                                                             |
| `-o <name>`           | Prefix for output files.                                                                  |
| `--offset <value>`    | Sea level offset in meters.                                                               |
| `--data <info>`       | Data input information. Format: `"file=<path> column=<n> format=<format> units=<unit>"`.  |
| `--simulation <info>` | Model input information. Format: `"file=<path> column=<n> format=<format> units=<unit>"`. |


---

### **Deprecated Options**

> **Note:** These options are **deprecated** and may not be fully supported.


| Option                               | Description                                                                                            |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `--mooring_info=<info>`              | Input information about mooring (e.g., `"lon=<lon> lat=<lat> code=<code> name=<name> depth=<depth>"`). |
| `--header_format=<format>`           | Format to decode mooring info from file.                                                               |
| `-n <nb>`                            | Number of columns for input GNU format (default: `1`).                                                 |
| `--step=<n_years>y` or `<n_months>m` | Split time series per `n` years or months.                                                             |
| `--time-correction`                  | Additional time to add to timestamps, in seconds.                                                      |
| `--gnu_nice`                         | Always set to `True` (deprecated).                                                                     |


---

## Examples

### **Validation Task**

Compare data and simulation time series:

```bash
timeseries-validate \
  --task validation \
  --data "file=/path/to/data.gnu column=1 format=GNU units=m" \
  --simulation "file=/path/to/simulation.gnu column=1 format=GNU units=m" \
  -s 01/01/2020 \
  -f 31/12/2020 \
  -o output_prefix
```

### **Ocean-Zero Task**

Compute ocean-zero statistics for a specific period:

```bash
timeseries-validate \
  --task ocean-zero \
  -s 01/01/2020 \
  -f 31/12/2020 \
  --offset 0.5
```

> **Note:** For `ocean-zero`, stations must be **predefined in the code** and the tool must be **recompiled**.

### **Operation Task**

Add two time series:

```bash
timeseries-validate \
  --task operation \
  --data "file=/path/to/data1.gnu column=0 format=GNU units=m" \
  --simulation "file=/path/to/data2.gnu column=0 format=GNU units=m" \
  -s 01/01/2020 \
  -f 31/12/2020 \
  -o sum_output
```

### **Using Custom Date Range**

Process time series for a custom date range:

```bash
timeseries-validate \
  input.gnu \
  -s 15/06/2020 \
  -f 15/08/2020 \
  --offset 0.2
```

### **Splitting Time Series**

Split time series into chunks of 2 years:

```bash
timeseries-validate \
  input.gnu \
  --step=2y \
  -o split_output
```

---

## Environment Variables

This tool does **not** require specific environment variables. However, ensure your system has the necessary permissions to read input files and write output files.

---

## Notes

1. **Input File Formats:**  
 Supported formats include:
  - **GNU, DMY, YMD**: ASCII with at least 2 columns (`time slv1`). Use `-n <ncolumns>` for additional columns.
  - **SONEL\_HR**: `YYYY-MM-DD HH:MM:SS slv_float` (e.g., `1995-08-10 11:50:00 3.050`). File extension: `.slv`.
  - **LIST**: `cnes_date float_value_of_slv` (Julian date from 1950/01/01).
  - **PROFILERS**: Binary format: `nbin ntime YYYY MM DD HH MM SS bin1 bin2 ...` (all values are floats).
  - Other supported formats: **GLOSS, HAWAII, SEINE, RADAR, FOREMAN, MINH, LIST2, JMA, LEGEND, BODC, DART, RMN, PAB**.
2. **Time Correction:**  
 Use `--time-correction` to adjust timestamps by a fixed number of seconds.
3. **Offset:**  
 The `--offset` option applies a **constant sea level offset** (in meters) to the data.
4. **Default Values:**
  - If no `--data` or `--simulation` is provided, default files are used (see code for details).
  - Default task: `validation`.
5. **Bugs:**
  - The `ocean-zero` task requires **hardcoding stations** in the source code and **recompiling** the tool.

---

## See Also

- [CF Conventions for Time Coordinates](http://cfconventions.org/cf-conventions/cf-conventions.html#time-coordinate)
- [SONEL Data Format](https://www.sonel.org/)
- [GNU Data Format](https://www.gnu.org/software/gawk/)