# 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

```bash
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`:

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

### **Custom Grid Resolution**

Use a grid resolution of `0.5` degrees:

```bash
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`:

```bash
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:

```bash
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:

```bash
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

1. **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.
2. **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).
3. **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).
4. **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.
5. **Performance:**
  - The tool processes files sequentially. For large datasets, ensure sufficient disk space and memory.

---

## See Also

- [NetCDF Documentation](https://www.unidata.ucar.edu/software/netcdf/)
- [CF Conventions](http://cfconventions.org/) (for NetCDF metadata standards)