# timeseries-extractor v3.2.3

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

---

## Description

`timeseries-extractor` extracts **time series at specific locations** from altimetric datasets or simulation outputs. The input `position_file` must contain a list of positions in the format:

```
LON LAT NUMBER
```

where:

- `LON` is the longitude,
- `LAT` is the latitude,
- `NUMBER` is an identifier for the position.

---

## Usage

```bash
timeseries-extractor position_file [options]
```

---

## Options


| Option                      | Description                                                                                              |
| --------------------------- | -------------------------------------------------------------------------------------------------------- |
| `--help`, `-h`              | Display help and exit.                                                                                   |
| `-s <dd/mm/yyyy>`           | Start date for the time series extraction.                                                               |
| `-f <dd/mm/yyyy>`           | End date for the time series extraction.                                                                 |
| `--time-sampling <seconds>` | Time sampling interval in seconds.                                                                       |
| `--data-info <string>`      | Model information string in the format: `"dataDirectory= dataTemplate= meshFile= variable= gridClass="`. |
| `-o <name>`                 | Prefix for output files. Extracted time series will be saved with this prefix.                           |


---

## Examples

### **Basic Extraction**

Extract time series from a position file with default settings:

```bash
timeseries-extractor positions.txt
```

### **Extract Time Series for a Specific Period**

Extract time series from `positions.txt` between January 1, 2020, and December 31, 2020:

```bash
timeseries-extractor positions.txt -s 01/01/2020 -f 31/12/2020
```

### **Custom Time Sampling**

Extract time series with a sampling interval of 3600 seconds (1 hour):

```bash
timeseries-extractor positions.txt --time-sampling 3600
```

### **Specify Model Information**

Extract time series with custom model information:

```bash
timeseries-extractor positions.txt \
  --data-info "dataDirectory=/path/to/data dataTemplate=template.nc meshFile=mesh.nc variable=ssh gridClass=regular"
```

### **Custom Output Prefix**

Save output files with a custom prefix (e.g., `output_`):

```bash
timeseries-extractor positions.txt -o output_
```

### **Full Example**

Extract time series for a specific period, with custom sampling and model information:

```bash
timeseries-extractor positions.txt \
  -s 01/01/2020 -f 31/12/2020 \
  --time-sampling 7200 \
  --data-info "dataDirectory=/path/to/data dataTemplate=template.nc meshFile=mesh.nc variable=ssh gridClass=regular" \
  -o my_output_
```

---

## Environment Variables

`timeseries-extractor` does not rely on specific environment variables. However, ensure that:

- Input files (position file, data files) are accessible.
- Output directory is writable.

---

## Notes

1. **Input File Format:**
  - The `position_file` must contain one position per line in the format: `LON LAT NUMBER`.
  - Example:
    ```
    2.3522 48.8566 1
    -1.2920 47.8942 2
    ```
2. **Date Format:**
  - Dates must be provided in `dd/mm/yyyy` format.
3. **Model Information:**
  - The `--data-info` string must include all required fields: `dataDirectory`, `dataTemplate`, `meshFile`, `variable`, and `gridClass`.
4. **Output:**
  - Output files will be saved in the current directory unless a full path is specified in `-o`.

---

## See Also

- [CF Conventions for Time Coordinates](http://cfconventions.org/cf-conventions/cf-conventions.html#time-coordinate) (for date formatting)
- Related tools: `comodo-detidor`, `showarg`