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¶

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:

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:

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:

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:

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:

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¶

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.

Time Correction:
Use --time-correction to adjust timestamps by a fixed number of seconds.
Offset:
The --offset option applies a constant sea level offset (in meters) to the data.
Default Values:

If no --data or --simulation is provided, default files are used (see code for details).
Default task: validation.

Bugs:

The ocean-zero task requires hardcoding stations in the source code and recompiling the tool.