# extract-nf-v2 v3.2.3

**Mercurial revision 5770:c90c3015e72d | 2026-05-22**

---

## Description

`extract-nf-v2` 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** (sea surface height)
- **ubar** (zonal velocity)
- **vbar** (meridional velocity)
- **Pa** or **ibd** (inverse barometer)

The output is in **ASCII format** with **5 columns**:

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

> **Specificity**: Supports **time averaging** for processed data.

---

## Usage

```bash
extract-nf-v2 [OPTIONS]
```

---

## Options


| Option             | Description                                                                                                             |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `--help`           | Show this help and exit.                                                                                                |
| `-r <dir>`         | Directory of 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. **Default:** `./`                                                                                     |
| `-e`               | Activate **LGP1 interpolation** to exact position. ⚠️ **Warning:** May produce bad results. Deactivate if issues occur. |
| `-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 time averaging over 1800 seconds:

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

### **Extract with Custom Archive and Forcing Files**

Extract data using custom root names for analysis and forcing files:

```bash
extract-nf-v2 -i station_list.txt -h custom_analysis -p custom_forcing -d output/ -start 06/2020 -end 12/2020
```

### **Extract with Exact Position Interpolation**

Enable LGP1 interpolation for precise station positions:

```bash
extract-nf-v2 -i station_list.txt -e -r ~/data/archives/ -start 01/2022 -end 12/2022
```

### **Extract with Default Settings**

Use default directories and root names:

```bash
extract-nf-v2 -i station_list.txt -start 01/2023 -end 06/2023
```

### **Extract with High-Frequency Sampling**

Extract data with a sampling period of 300 seconds (5 minutes):

```bash
extract-nf-v2 -i station_list.txt -s 300 -r ~/data/archives/ -start 01/2021 -end 01/2021
```

---

## Environment Variables

`extract-nf-v2` does not rely on specific environment variables. However, ensure that:

- Input and output directories are **accessible** and **writable**. 
- The **T-UGOm outputs** are properly formatted and available in the specified archive directory.

---

## Notes

1. **Input Files:**
  - The station list file (`-i`) must be formatted as produced by `detidor`.
  - Archive files must follow the naming convention: `ROOTNAME-YYYY.MM.nc`.
2. **Output Files:**
  - Output files are saved in the directory specified by `-d`.
  - Each station's time series is saved in a separate file named `sample.<station_number>`.
  - A metadata file (`sample.info`) is generated, containing station coordinates, names, and depths.
3. **Time Averaging:**
  - If `-a` is set to a non-zero value, the tool computes **time-averaged** values over the specified period.
  - The averaging is performed symmetrically around each time step.
4. **Interpolation:**
  - The `-e` option enables **LGP1 interpolation** for exact station positions. 
  - **Warning:** This option may produce inaccurate results in some cases. Deactivate it if unexpected behavior occurs.
5. **Date Format:**
  - Start (`-start`) and end (`-end`) dates must be provided in `MM/YYYY` format.
6. **Performance:**
  - For large datasets, ensure sufficient **disk space** and **memory** are available.
  - Processing time depends on the number of stations, time steps, and averaging period.

---

## 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)