grid-track v3.2.3¶

Mercurial revision 5770:c90c3015e72d | 2026-05-22

Description¶

grid-track computes grid-based statistics (average, standard deviation, min, max, and count) for specified variables along a track defined by latitude and longitude in NetCDF files. It is useful for analyzing spatial distributions of variables over a predefined grid.

Usage¶

grid-track [OPTIONS]

Options¶

Option	Description
`-h`, `--help`	Display help and exit.
`-p <pattern>`	Required. Pattern for NetCDF input files containing latitude, longitude, and variables to analyze.
`-f <suffix>`	Suffix of the first path to process. Default: First file matching the pattern.
`-l <suffix>`	Suffix of the last path to process. Default: Last file matching the pattern.
`-v <var1> [var2 ...]`	Required. Names of the variables to compute statistics for.
`-r <resolution>`	Resolution of the grid in degrees. Default: `2`. If negative, an offset is added to the grid.
`-o <path>`	Required. Path for the output NetCDF file.
`--debug-lon-lat <lon> <lat>`	Specify a debug point (longitude and latitude) to extract data for. Default: None.

Examples¶

Basic Usage¶

Compute statistics for variables ssh and sst from NetCDF files matching the pattern data_*.nc and save results to output.nc:

grid-track -p "data_*.nc" -v ssh sst -o output.nc

Custom Grid Resolution¶

Use a grid resolution of 0.5 degrees:

grid-track -p "data_*.nc" -v ssh -r 0.5 -o output.nc

Process a Subset of Files¶

Process files starting with data_2020 and ending with data_2022:

grid-track -p "data_*.nc" -f "2020" -l "2022" -v ssh -o output.nc

Debug Mode¶

Extract data for a specific point (longitude 10.5, latitude 45.2) and save to a debug file:

grid-track -p "data_*.nc" -v ssh --debug-lon-lat 10.5 45.2 -o output.nc

Negative Resolution (Offset Grid)¶

Use a resolution of -2 to add an offset to the grid:

grid-track -p "data_*.nc" -v ssh -r -2 -o output.nc

Environment Variables¶

grid-track does not rely on external environment variables for its core functionality. However, it uses standard system libraries (e.g., glob for file pattern matching), which may be influenced by system-level configurations.

Notes¶

Input Files:

Must be NetCDF files containing latitude, longitude, and the specified variables.
The -p option supports wildcards (e.g., data_*.nc) for matching multiple files.

Output:

The output is a NetCDF file containing the following variables for each input variable:
- <var>_count: Number of data points in each grid cell.
- <var>_average: Mean value of the variable in each grid cell.
- <var>_std: Standard deviation of the variable in each grid cell.
- <var>_min: Minimum value of the variable in each grid cell.
- <var>_max: Maximum value of the variable in each grid cell.
The output file also includes the grid coordinates and metadata (e.g., source, history).

Grid Handling:

The grid is automatically generated based on the resolution (-r).
If the resolution is negative, an offset is applied to the grid boundaries.
The grid covers the entire globe by default (-90 to +90 latitude, 0 to +360 longitude).

Debug Mode:

If --debug-lon-lat is specified, a debug file (e.g., +10.5E+45.2N.dat) is created in the output directory, containing time series data for the specified point.

Performance:

The tool processes files sequentially. For large datasets, ensure sufficient disk space and memory.