# analysis-tugo v3.2.3

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

---

## Description

`analysis-tugo` is a tool designed to **analyze filtered or detided TUGOm sample files**. It processes observational and model data to generate statistical outputs, filtered time series, and spectral analyses (FFT).

---

## Usage

```bash
analysis-tugo [OPTIONS]
```

---

## Options


| Option             | Description                                                                                  |
| ------------------ | -------------------------------------------------------------------------------------------- |
| `-h`, `--help`     | Show this help message and exit.                                                             |
| `-start <mm/yyyy>` | Start date for analysis in `mm/yyyy` format.                                                 |
| `-end <mm/yyyy>`   | End date for analysis in `mm/yyyy` format.                                                   |
| `-cm`              | Scale output values to **centimeters** (default: scale factor of 100.0).                     |
| `-check`           | Produce **filtered time series** for observations, model, and inverse barometer corrections. |
| `--no-fft`         | Disable the production of **Fast Fourier Transforms (FFT)**.                                 |
| `--save_psd`       | Save the **Power Spectral Density (PSD)** in `psd_r1_c.py` (requires FFTs).                  |
| `-d <directory>`   | Path to the **observations directory** (default: `./`).                                      |
| `-e <extension>`   | File extension for observations (default: `.res.65.mlf.obs`).                                |
| `-m <directory>`   | Path to the **samples directory** (default: `./`).                                           |
| `-t <file>`        | Path to the **translation file** (maps station names to model data).                         |
| `-i <file>`        | Path to the **stations list file** (contains station metadata).                              |


---

## Examples

### **Basic Analysis**

Run analysis on default directories with a specified date range:

```bash
analysis-tugo -start 01/2020 -end 12/2021
```

### **Scale to Centimeters**

Scale output values to centimeters:

```bash
analysis-tugo -start 01/2020 -end 12/2021 -cm
```

### **Generate Filtered Time Series**

Produce filtered time series for observations and model data:

```bash
analysis-tugo -start 01/2020 -end 12/2021 -check
```

### **Disable FFTs**

Disable FFT computations to save processing time:

```bash
analysis-tugo -start 01/2020 -end 12/2021 --no-fft
```

### **Save Power Spectral Density**

Save the PSD for further analysis:

```bash
analysis-tugo -start 01/2020 -end 12/2021 --save_psd
```

### **Custom Directories and Extensions**

Specify custom directories and file extensions for observations and samples:

```bash
analysis-tugo -start 01/2020 -end 12/2021 \
  -d /path/to/observations \
  -e .custom.ext \
  -m /path/to/samples
```

### **Use Translation and Stations Files**

Use a translation file to map station names and a stations list for metadata:

```bash
analysis-tugo -start 01/2020 -end 12/2021 \
  -t translation.txt \
  -i stations.list
```

### **Full Example**

Combine multiple options for a comprehensive analysis:

```bash
analysis-tugo -start 01/2020 -end 12/2021 \
  -d /data/observations \
  -e .res.65.mlf.obs \
  -m /data/samples \
  -t translation.txt \
  -i stations.list \
  -cm -check --save_psd
```

---

## Environment Variables

`analysis-tugo` does not explicitly rely on environment variables. However, it uses **OpenMP** for parallel processing if available. You can control parallelism using:


| Variable          | Description                                |
| ----------------- | ------------------------------------------ |
| `OMP_NUM_THREADS` | Number of threads for parallel processing. |


**Example:**

```bash
OMP_NUM_THREADS=4 analysis-tugo -start 01/2020 -end 12/2021
```

---

## Notes

1. **Input Files:**
  - Observations must be in the specified directory (`-d`) with the given extension (`-e`).
  - The **translation file** (`-t`) maps station names to model data.
  - The **stations list** (`-i`) provides metadata for each station (e.g., coordinates).
2. **Output Files:**
  - Filtered time series are saved with extensions like `.1`, `.p.dif`, `.h.dif`.
  - FFT outputs are saved with `.fft` extensions.
  - Statistics are appended to the `statistics` file.
  - A legend file (`statistics.lgd`) is generated for visualization.
3. **Date Handling:**
  - Dates are specified in `mm/yyyy` format (e.g., `01/2020` for January 2020).
  - The tool processes data between the start and end dates (inclusive).
4. **Masking:**
  - Missing or invalid data is masked with a default value of `999.9`.
5. **Performance:**
  - Disabling FFTs (`--no-fft`) can significantly reduce computation time for large datasets.
  - Use `-check` to generate filtered time series if needed.

---

## See Also

- [TUGOm Data Format](https://www.tugom.fr/) (for input file specifications)
- [OpenMP Documentation](https://www.openmp.org/) (for parallel processing options)