mgr-rating v3.2.3¶

Mercurial revision 5770:c90c3015e72d | 2026-05-22

Description¶

mgr-rating is a command-line tool designed to convert between different sea-level time series formats. It supports various input and output formats, resampling, time corrections, and additional metadata handling for mooring data.

Usage¶

mgr-rating <file> [options]

Options¶

General Options¶

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

Input/Output Format Options¶

Option	Description
`-iF <format>`	Input format. Default: `GNU`.
`-oF <format>`	Output format. Default: `GNU`.
`-n <columns>`	Number of columns for input GNU format. Default: `1`.
`-o <name>`	Prefix for output files.
`--suffix <suffix>`	Suffix to append to output file names.
`--delimiter <char>`	Column delimiter for input/output. Default: `' '` (space).
`--split=yes` / `--split=no`	Split columns into separate files. Default: `yes`.

Date and Time Options¶

Option	Description
`-s <date>`	Start date for processing. See Date Formats.
`-f <date>`	End date for processing. See Date Formats.
`--time-format <format>`	Time format for input/output. Default: `'YYYY-MM-DD HH:MM:SS'`.
`--time-origin <origin>`	Time origin for input/output.
`--time-correction <offset>`	Time correction offset in seconds. If `NAN`, corrects to local time zone (accounting for daylight saving changes). If followed by a time zone (e.g., `Europe/Paris`), corrects to the specified time zone.

Data Processing Options¶

Option	Description
`–step=<y	m
`--reconstruct`	Enable time series reconstruction.
`--resampling <seconds>`	Resampling period in seconds. If not specified, no resampling is performed.
`--nice=yes` / `--gnu_nice`	Add an empty line at time breaks in GNU format. Default: `yes`.
`--nice=no`	Disable empty lines at time breaks.

Data Correction Options¶

Option	Description
`--local-datum-correction <value>`	Additive correction for local datum (in meters). Applied after units correction.
`--datum-correction <value>`	Datum correction (additive, in meters).
`--units-correction <factor>`	Multiplicative factor to correct data units. Default: `1.0`.

Mooring Information Options¶

Option	Description
`--mooring_info=<info>`	Input metadata for mooring (e.g., `"lon=<lon> lat=<lat> code=<code> name=<name> depth=<depth>"`).
`--header_format=<format>`	Format to decode mooring info from file.

Advanced Options¶

Option	Description
`--discharge <file>`	Path to a discharge file for additional processing.

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

File Formats¶

Supported input/output formats:

GNU: ASCII with at least 2 columns: time slv1 [slv2 ...]. Use -n to specify the number of columns.
DMY: ASCII with date in DD/MM/YYYY format.
YMD: ASCII with date in YYYY/MM/DD format.
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 slv_float where cnes_date is a Julian date from 1950/01/01.
RMN: (Format description not provided in documentation).
PAB: (Format description not provided in documentation).
PROFILERS: Binary format: nbin ntime YYYY MM DD HH MM SS bin1 bin2 ... (all values are floats).
GLOSS
HAWAII
SEINE
RADAR
FOREMAN
MINH
LIST2
JMA
LEGEND
BODC
DART

Examples¶

Basic Conversion¶

Convert a GNU format file to SONEL_HR format:

mgr-rating input.gnu -iF GNU -oF SONEL_HR -o output

Specify Number of Columns¶

Convert a GNU file with 3 columns:

mgr-rating input.gnu -iF GNU -n 3 -o output

Resample Data¶

Resample data to a 3600-second (1-hour) interval:

mgr-rating input.gnu --resampling 3600 -o output

Time Correction¶

Correct time to the Europe/Paris time zone:

mgr-rating input.gnu --time-correction Europe/Paris -o output

Additive Datum Correction¶

Apply a local datum correction of 0.5 meters:

mgr-rating input.gnu --local-datum-correction 0.5 -o output

Split Time Series¶

Split time series into monthly chunks:

mgr-rating input.gnu --step=1m -o output

Enable Reconstruction¶

Enable time series reconstruction:

mgr-rating input.gnu --reconstruct -o output

Mooring Information¶

Add mooring metadata (longitude, latitude, code, name, depth):

mgr-rating input.gnu \
  --mooring_info="lon=2.35 lat=48.85 code=ST01 name=Station1 depth=10" \
  -o output

Custom Delimiter¶

Use a comma as the column delimiter:

mgr-rating input.csv -iF GNU --delimiter "," -o output

Multiplicative Units Correction¶

Apply a units correction factor of 10:

mgr-rating input.gnu --units-correction 10 -o output

Combine Options¶

Convert a GNU file to SONEL_HR format, resample to 1 hour, and apply a datum correction:

mgr-rating input.gnu \
  -iF GNU -oF SONEL_HR \
  --resampling 3600 \
  --datum-correction 0.2 \
  -o output

Environment Variables¶

mgr-rating does not rely on specific environment variables for its core functionality. However, the --time-correction option can use the TZ environment variable to set the time zone for corrections.

Example:

TZ=Europe/Paris mgr-rating input.gnu --time-correction NAN -o output

Notes¶

Input/Output Formats:

The default input and output format is GNU.
For formats like SONEL_HR, LIST, or PROFILERS, ensure the input file matches the expected structure.

Time Handling:

Time corrections can be applied as a fixed offset (in seconds) or dynamically based on a time zone.
Use NAN for --time-correction to automatically correct to the local time zone.

Resampling:

Resampling is performed in seconds. If not specified, no resampling is applied.

Mooring Data:

Use --mooring_info to embed metadata directly in the output files.
The --header_format option allows custom parsing of mooring headers.

Discharge Data:

The --discharge option is used for advanced processing involving discharge files (e.g., river flow data).

Deprecated Options:

The --format=... option is deprecated. Use -iF and -oF instead.