extract-nf-v3 v3.2.3¶

Mercurial revision 5770:c90c3015e72d | 2026-05-22

Description¶

extract-nf-v3 produces sample files (time series at specific locations) from T-UGOm outputs, similar to what T-UGOm would generate if explicitly configured to do so. It extracts the following variables:

Elevation (h)
Zonal velocity (u)
Meridional velocity (v)
Inverse barometer (ib)

The output is saved as ASCII files with 5 columns:

Time
Elevation
Zonal velocity
Meridional velocity
Inverse barometer

Specificity: Supports time averaging for the extracted time series.

Usage¶

extract-nf-v3 [OPTIONS] [DATA FILE]

Options¶

Option	Description
`--help`	Show help and exit.
`-r <dir>`	Directory containing archive files. Default: `./`
`-h <name>`	Root name for analysis files (format: `ROOTNAME-YYYY.MM.nc`). Default: `analysis`
`-p <name>`	Root name for forcing files (format: `ROOTNAME-YYYY.MM.nc`). Default: `forcing`
`-i <file>`	Path to the station list file (as produced by `detidor`).
`-d <dir>`	Output directory for sample files. Default: `./`
`-start <MM/YYYY>`	Start date for extraction (format: `MM/YYYY`).
`-end <MM/YYYY>`	End date for extraction (format: `MM/YYYY`).
`-s <seconds>`	Sampling period in seconds. Default: Model sampling rate.
`-a <seconds>`	Time average period in seconds. Default: `0` (no averaging).

Examples¶

Basic Extraction¶

Extract time series for stations listed in ../h4_list_stat with a sampling period of 1800 seconds (30 minutes) and a time average of 1800 seconds:

extract-nf-v3 -i ../h4_list_stat -s 1800 -a 1800 -r ~/tugo/data/archives/global-MR/ -start 01/2001 -end 01/2001

Extract for a Single Month¶

Extract data for January 2001 using default settings:

extract-nf-v3 -i station_list.txt -start 01/2001 -end 01/2001

Custom Output Directory¶

Extract data and save output files to a custom directory:

extract-nf-v3 -i station_list.txt -d /path/to/output/ -start 01/2001 -end 12/2001

Custom Archive and Forcing File Roots¶

Specify custom root names for archive and forcing files:

export-nf-v3 -i station_list.txt -h custom_analysis -p custom_forcing -r /path/to/archives/ -start 01/2001 -end 12/2001

No Time Averaging¶

Extract data without time averaging (default behavior):

extract-nf-v3 -i station_list.txt -s 3600 -start 01/2001 -end 01/2001

Environment Variables¶

extract-nf-v3 does not explicitly rely on environment variables. However, ensure that:

Input and output directories are accessible and writable.
The system has sufficient memory for large datasets (especially when processing long time series or many stations).

Notes¶

Input Files:

The station list file (-i) must be formatted as produced by detidor (e.g., longitude latitude name).
Archive files must follow the naming convention: ROOTNAME-YYYY.MM.nc.

Output Files:

Output files are named sample.<station_index> and saved in the directory specified by -d.
If the output directory does not exist, it will not be created automatically. Ensure it exists before running the tool.

Time Handling:

The -start and -end options use the format MM/YYYY.
If -start or -end is not specified, the tool will process all available data in the archive files.
The -s option (sampling period) defaults to the model’s sampling rate if not specified.

Time Averaging:

The -a option enables time averaging over the specified period (in seconds).
If -a is set to 0, no averaging is applied.

Performance:

For large datasets, ensure sufficient disk space and memory are available.
Processing time scales with the number of stations and the length of the time series.