# extract-sections v3.2.3

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

---

## Description

`extract-sections` interpolates **georeferenced datasets** onto a **regular grid**. It is designed to work with **monthly archive files** following the naming convention:

```
ROOTNAME.YYYY.MM.nc
```

**Native support** is provided for **T-UGOm archives**. For other implementations, contact the developers.

---

## Usage

```bash
extract-sections [OPTIONS]
```

---

## Options


| Option             | Description                                                           |
| ------------------ | --------------------------------------------------------------------- |
| `--help`           | Display help and exit.                                                |
| `-r <path>`        | Path to input files. If not set, the current directory is used.       |
| `-d <path>`        | Path to the output directory.                                         |
| `-h <rootname>`    | Root name of input files (e.g., `ROOTNAME` in `ROOTNAME.YYYY.MM.nc`). |
| `-i <file>`        | Path to the file containing positions for interpolation.              |
| `-start <YYYY/MM>` | Starting date for processing (format: `YYYY/MM`).                     |
| `-end <YYYY/MM>`   | Ending date for processing (format: `YYYY/MM`).                       |
| `-s <seconds>`     | Time sampling interval in seconds.                                    |
| `-a <seconds>`     | Time average interval in seconds.                                     |
| `-e`               | Enable interpolation on **exact positions**.                          |


---

## Date Format

The only supported date format is:

```
YYYY/MM
```

For additional formats, contact the developers.

---

## Examples

### **Basic Interpolation**

Interpolate data from files with root name `mydata` in the current directory:

```bash
extract-sections -h mydata -i positions.txt
```

### **Specify Input and Output Directories**

Interpolate data from a custom input directory and save results to a custom output directory:

```bash
extract-sections -r /path/to/input -d /path/to/output -h mydata -i positions.txt
```

### **Process a Specific Time Range**

Interpolate data for a specific time range (from January 2020 to December 2021):

```bash
extract-sections -h mydata -i positions.txt -start 2020/01 -end 2021/12
```

### **Custom Time Sampling**

Set a custom time sampling interval of 3600 seconds (1 hour):

```bash
extract-sections -h mydata -i positions.txt -s 3600
```

### **Time Averaging**

Apply a time average over 86400 seconds (1 day):

```bash
extract-sections -h mydata -i positions.txt -a 86400
```

### **Exact Position Interpolation**

Enable interpolation on exact positions:

```bash
extract-sections -h mydata -i positions.txt -e
```

### **Full Example**

Combine multiple options to process data for a specific time range with custom sampling and exact interpolation:

```bash
extract-sections -r /input/data -d /output/results \
  -h mydata -i positions.txt \
  -start 2020/01 -end 2021/12 \
  -s 3600 -a 86400 -e
```

---

## Environment Variables

This tool does not rely on specific environment variables. However, ensure your system has the necessary permissions to read input files and write to the output directory.

---

## Notes

1. **Input Files:**
  - Must follow the naming convention: `ROOTNAME.YYYY.MM.nc`.
  - Only **monthly archive files** are supported.
2. **Output:**
  - Results are saved in the directory specified by `-d`. If not provided, the current directory is used.
3. **Time Handling:**
  - The `-start` and `-end` options use the `YYYY/MM` format.
  - Time sampling (`-s`) and averaging (`-a`) are specified in **seconds**.
4. **Position File:**
  - The file specified with `-i` must contain the coordinates for interpolation.
5. **Exact Interpolation:**
  - Use `-e` to ensure interpolation is performed on exact positions. This is useful for precise spatial analysis.

---

## See Also

- [T-UGOm Archives](https://www.umr-cnrm.fr/) (for compatible input file formats)
- Contact the developers for support or additional implementations.