# 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 ```bash mgr-rating [options] ``` --- ## Options ### **General Options** | Option | Description | | -------------- | ---------------------- | | `-h`, `--help` | Display help and exit. | --- ### **Input/Output Format Options** | Option | Description | | ---------------------------- | ---------------------------------------------------------- | | `-iF ` | Input format. Default: `GNU`. | | `-oF ` | Output format. Default: `GNU`. | | `-n ` | Number of columns for input GNU format. Default: `1`. | | `-o ` | Prefix for output files. | | `--suffix ` | Suffix to append to output file names. | | `--delimiter ` | 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 ` | Start date for processing. See [Date Formats](#date-formats5). | | `-f ` | End date for processing. See [Date Formats](#date-formats5). | | `--time-format ` | Time format for input/output. Default: `'YYYY-MM-DD HH:MM:SS'`. | | `--time-origin ` | Time origin for input/output. | | `--time-correction ` | 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=` | Split time series into chunks of `nb` years (`y`), months (`m`), or days (`d`). | | `--reconstruct` | Enable time series reconstruction. | | `--resampling ` | 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 ` | Additive correction for local datum (in meters). Applied after units correction. | | `--datum-correction ` | Datum correction (additive, in meters). | | `--units-correction ` | Multiplicative factor to correct data units. Default: `1.0`. | --- ### **Mooring Information Options** | Option | Description | | -------------------------- | ------------------------------------------------------------------------------------------------- | | `--mooring_info=` | Input metadata for mooring (e.g., `"lon= lat= code= name= depth="`). | | `--header_format=` | Format to decode mooring info from file. | --- ### **Advanced Options** | Option | Description | | -------------------- | --------------------------------------------------- | | `--discharge ` | Path to a discharge file for additional processing. | --- (date-formats5)= ## 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: ```bash mgr-rating input.gnu -iF GNU -oF SONEL_HR -o output ``` ### **Specify Number of Columns** Convert a GNU file with 3 columns: ```bash mgr-rating input.gnu -iF GNU -n 3 -o output ``` ### **Resample Data** Resample data to a 3600-second (1-hour) interval: ```bash mgr-rating input.gnu --resampling 3600 -o output ``` ### **Time Correction** Correct time to the `Europe/Paris` time zone: ```bash mgr-rating input.gnu --time-correction Europe/Paris -o output ``` ### **Additive Datum Correction** Apply a local datum correction of 0.5 meters: ```bash mgr-rating input.gnu --local-datum-correction 0.5 -o output ``` ### **Split Time Series** Split time series into monthly chunks: ```bash mgr-rating input.gnu --step=1m -o output ``` ### **Enable Reconstruction** Enable time series reconstruction: ```bash mgr-rating input.gnu --reconstruct -o output ``` ### **Mooring Information** Add mooring metadata (longitude, latitude, code, name, depth): ```bash 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: ```bash mgr-rating input.csv -iF GNU --delimiter "," -o output ``` ### **Multiplicative Units Correction** Apply a units correction factor of 10: ```bash 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: ```bash 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:** ```bash TZ=Europe/Paris mgr-rating input.gnu --time-correction NAN -o output ``` --- ## Notes 1. **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. 2. **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. 3. **Resampling:** - Resampling is performed in seconds. If not specified, no resampling is applied. 4. **Mooring Data:** - Use `--mooring_info` to embed metadata directly in the output files. - The `--header_format` option allows custom parsing of mooring headers. 5. **Discharge Data:** - The `--discharge` option is used for advanced processing involving discharge files (e.g., river flow data). 6. **Deprecated Options:** - The `--format=...` option is deprecated. Use `-iF` and `-oF` instead. --- ## See Also - [CF Conventions for Time Coordinates](http://cfconventions.org/cf-conventions/cf-conventions.html#time-coordinate) (for time handling best practices) - [SONEL Data Format](https://www.sonel.org/) (for `SONEL_HR` format details) - [GNU Time Series Tools](https://www.gnu.org/software/gretl/) (for GNU format compatibility)