# 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**:

1. Time
2. Elevation
3. Zonal velocity
4. Meridional velocity
5. Inverse barometer

**Specificity:** Supports **time averaging** for the extracted time series.

---

## Usage

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

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

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

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

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

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

1. **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`.
2. **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.
3. **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.
4. **Time Averaging:**
  - The `-a` option enables time averaging over the specified period (in seconds).
  - If `-a` is set to `0`, no averaging is applied.
5. **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.

---

## See Also

- [T-UGOm Documentation](https://www.tugo-model.fr/) (for input file formats and conventions)
- [`detidor`](https://www.comodo-ocean.fr/) (for generating station list files)