convert-nf v3.2.3¶

Mercurial revision 5770:c90c3015e72d | 2026-05-22

Description¶

convert-nf is a tool used to convert TUGOm outputs. It is utilized by CTOH (Centre de Topographie des Océans et de l’Hydrosphère).

If no grid is provided using -z or -g, the tool produces unstructured outputs.
If a grid is provided, it interpolates the data to a structured grid.

Input Formats:

TUGOm’s binary format (default).

If no binary file is found, it falls back to TUGOm’s NetCDF format.

Usage¶

convert-nf [OPTIONS]

Options¶

General Options¶

Option	Description
`--help`	Display help and exit.
`--mesh <file>`	Input mesh file (used if mesh data is not present in input files).

Input/Output Variables¶

Option	Description
`--ssh <name>`	SSH (Sea Surface Height) variable name in input files.
`--u <name>`	Zonal velocity variable name in input files.
`--v <name>`	Meridional velocity variable name in input files.
`--p <name>`	Pressure variable name in input files.
`--ibd <name>`	Inverse Barometer Departure (IBD) variable name in input files.

Output Content Options¶

Option	Description
`-pressure`	Include pressure in the output.
`-currents`	Include currents in the output.
`-ibd`	Include Inverse Barometer Departure (IBD) in the output.
`-s1`	Enable detiding of the S1 tidal constituent.
`-s2`	Enable detiding of the S2 tidal constituent.
`-sa`	Enable detiding of the Sa tidal constituent.
`-cm`	Scale output values to centimeters.

File and Directory Options¶

Option	Description
`-p <root>`	Root name for forcing files (default: `forcing-`).
`-h <root>`	Root name for analysis files (default: `analysis-`). If used as the last argument, displays help and exits.
`-d <dir>`	Input directory (default: `.`).
`-o <dir>`	Output directory (default: `.`).
`-z <name>`	Output grid zone name.
`-g <file>`	Output grid file.

Processing Options¶

Option	Description
`-s <date>`	Start date in `mm/yyyy` format.
`-e <date>`	End date in `mm/yyyy` format.
`-f <format>`	Output format: `cdf` (NetCDF, default) or `ascii`.
`-r`	Input files are reduced and their names end with `.reduced-6`.
`-i <stride>`	Frame stride (default: `1`).
`--duplicate-varnames`	Allow duplicate variable names in the output.
`-deflate <level>`	Set the compression level for NetCDF output (default: `4`).
`--mapping <string>`	Mapping string to define the output grid.

Examples¶

Basic Conversion to NetCDF¶

Convert TUGOm outputs to NetCDF with default settings:

convert-nf -d /path/to/input -o /path/to/output

Convert with Custom Variable Names¶

Specify custom variable names for SSH, zonal velocity, and meridional velocity:

convert-nf --ssh sea_surface_height --u u_velocity --v v_velocity -d /input -o /output

Include Pressure and Currents¶

Convert and include pressure and currents in the output:

convert-nf -pressure -currents -d /input -o /output

Detide Specific Constituents¶

Enable detiding for S1, S2, and Sa constituents:

convert-nf -s1 -s2 -sa -d /input -o /output

Scale Output to Centimeters¶

Convert and scale output values to centimeters:

convert-nf -cm -d /input -o /output

Use a Structured Grid¶

Interpolate to a structured grid using a grid file:

convert-nf -g /path/to/grid.nc -d /input -o /output

Convert Reduced Files¶

Process reduced input files (names ending with .reduced-6):

convert-nf -r -d /input -o /output

Custom Output Format (ASCII)¶

Convert to ASCII format instead of NetCDF:

convert-nf -f ascii -d /input -o /output

Specify Date Range¶

Convert files for a specific date range (e.g., January 2020 to December 2020):

convert-nf -s 01/2020 -e 12/2020 -d /input -o /output

Use Custom Root Names¶

Specify custom root names for forcing and analysis files:

convert-nf -p custom_forcing -h custom_analysis -d /input -o /output

Enable Detiding and Include IBD¶

Enable detiding for S2 and include Inverse Barometer Departure (IBD):

convert-nf -s2 -ibd -d /input -o /output

Environment Variables¶

convert-nf does not explicitly rely on environment variables for its core functionality. However, it may inherit environment settings from the system or parent processes, such as:

PATH: For locating executable files.
LD_LIBRARY_PATH: For locating shared libraries (if applicable).

Notes¶

Input Files:

The tool expects TUGOm binary or NetCDF files as input.
If no grid is provided (-z or -g), outputs will be unstructured.

Output Files:

By default, outputs are saved in NetCDF format (cdf).
Use -f ascii for ASCII output.

Detiding:

Detiding is optional and can be enabled for S1, S2, or Sa constituents using -s1, -s2, or -sa.

Grid Interpolation:

If a grid is provided (-g or -z), the tool interpolates data to a structured grid.
The --mapping option allows defining a custom grid via a string.

Compression:

NetCDF outputs are compressed by default (level 4). Adjust with -deflate <level>.

Reduced Files:

Use -r if input files are reduced and end with .reduced-6.

Frame Stride:

Use -i <stride> to process every n-th frame (e.g., -i 2 processes every other frame).