# extract-nf-v1 v3.2.3

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

---

## Description

`extract-nf-v1` 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` (and `elevation_detided`)
- `ubar` (and `ubar_detided`)
- `vbar` (and `vbar_detided`)
- `Pa` (inverse barometer)

**Specificity:** Supports **binary input files** in addition to NetCDF.

**Output Format:**  
The output ASCII files contain **5 columns**:

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

---

## Usage

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

---

## Options


| Option             | Description                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| `--help`           | Show help and exit.                                                                              |
| `-format <format>` | Output format. If specified, output will be in **NetCDF**; otherwise, it defaults to **binary**. |
| `-c <convention>`  | Input file name convention (NetCDF format only).                                                 |
| `--mesh <file>`    | Input mesh file (required if mesh is not present in data files).                                 |
| `-r <dir>`         | Directory of archive files (binary format). Default: `./`                                        |
| `-h <name>`        | Root name for analysis files (binary format). Default: `analysis`                                |
| `-p <name>`        | Root name for forcing files (binary format). Default: `forcing`                                  |
| `-i <file>`        | Station list file (as produced by `detidor`). **Required.**                                      |
| `-t <file>`        | Path to translation file. Default: `translation`                                                 |
| `-d <dir>`         | Output directory. Default: `./`                                                                  |
| `-cm`              | Scale output values to **centimeters**.                                                          |
| `-e`               | Enable **LGP1 interpolation** to exact position. **Note:** Only supported for binary format.     |
| `-start <date>`    | Start date in `MM/YYYY` format.                                                                  |
| `-end <date>`      | End date in `MM/YYYY` format.                                                                    |
| `-s <seconds>`     | Sampling period in seconds. Default: `3600` (1 hour).                                            |


---

## Examples

### **Extract Time Series in Binary Format**

```bash
extract-nf-v1 -i ../h4_list_stat -s 3600 -cm \
  -r ~/tugo/data/archives/global-MR/ \
  -start 01/2001 -end 01/2001
```

### **Extract Time Series in NetCDF Format**

```bash
extract-nf-v1 -format NETCDF -i ../h4_list_stat -s 3600 -cm \
  -c /models/tugo/global-MR/global-MR.YYYY.MM.nc \
  -start 01/2001 -end 01/2001
```

### **Use Custom Output Directory and Translation File**

```bash
extract-nf-v1 -i station_list.txt -d /output/path/ \
  -t custom_translation.txt -start 06/2020 -end 12/2020
```

### **Enable LGP1 Interpolation (Binary Only)**

```bash
extract-nf-v1 -i station_list.txt -e \
  -r ~/data/archives/ -start 01/2022 -end 06/2022
```

### **Scale Output to Centimeters**

```bash
extract-nf-v1 -i station_list.txt -cm \
  -r ~/data/archives/ -start 01/2023 -end 01/2023
```

---

## Environment Variables

None specifically required. However, ensure that:

- Input files (binary or NetCDF) are accessible.
- Output directories have **write permissions**.

---

## Notes

1. **Binary vs. NetCDF:**
  - If `-format` is **not specified**, the output defaults to **binary**.
  - If `-format NETCDF` is used, the `-c` option **must** be provided to specify the input file naming convention.
2. **LGP1 Interpolation (`-e`):**
  - Only works with **binary format**. Using `-e` with NetCDF may produce incorrect results.
3. **Date Format:**
  - Only `MM/YYYY` is supported for `-start` and `-end`.
4. **Sampling Period (`-s`):**
  - Defaults to `3600` seconds (1 hour) if not specified.
5. **Station List (`-i`):**
  - **Required.** Must be provided as a file path.
6. **Output Files:**
  - ASCII files contain 5 columns: time, elevation, zonal velocity, meridional velocity, and inverse barometer.
  - A `sample.info` file is generated with station metadata (longitude, latitude, name, code, depth, and index).

---

## See Also

- [T-UGOm Documentation](https://www.tugo-model.org/)
- [detidor](https://www.comodo-ocean.fr/) (for generating station list files)