Metadata-Version: 2.4
Name: istsa
Version: 1.1.1
Summary: Trajectory-model analysis of GNSS time series: velocity, seasonal signals, co-seismic and post-seismic offsets.
Author-email: Lou Marill <lou.marill@univ-grenoble-alpes.fr>, Anne SOCQUET <anne.socquet@univ-grenoble-alpes.fr>
Maintainer-email: Gaël JANEX <gael.janex@univ-grenoble-alpes.fr>, Oliver HENRIOT <Oliver.Henriot@univ-grenoble-alpes.fr>, Aubin TSAPONG TSAGUE <tsaponga@univ-grenoble-alpes.fr>
Project-URL: Documentation, https://gricad-gitlab.univ-grenoble-alpes.fr/isterre-cycle/itsa/-/wikis/home
Project-URL: Repository, https://gricad-gitlab.univ-grenoble-alpes.fr/isterre-cycle/itsa
Project-URL: Issues, https://gricad-gitlab.univ-grenoble-alpes.fr/isterre-cycle/itsa/-/issues
Keywords: gnss,gps,Time Series,Analysis,trajectory model
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: matplotlib
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: pyarrow
Requires-Dist: numpy
Dynamic: license-file

# ITSA — ISTerre Time Series Analysis

[![PyPI](https://img.shields.io/pypi/v/istsa.svg)](https://pypi.org/project/istsa/)
[![Python](https://img.shields.io/pypi/pyversions/istsa.svg)](https://pypi.org/project/istsa/)
[![License: CC BY-NC 4.0](https://img.shields.io/badge/license-CC--BY--NC%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc/4.0/)

> **One call turns a raw GNSS `.pos` file into a clean trajectory model** —
> velocity, seasonal terms, and every earthquake / antenna offset, with 1σ
> uncertainties.

ITSA fits the full trajectory model of GNSS position time series. It finds the
discontinuities for you (earthquakes, equipment changes, slow-slip), estimates
offsets, post-seismic transients, seasonal signals, linear velocity and optional
acceleration — and writes ready-to-use parameters and plots. Built by Lou Marill
in the ISTerre Cycle team.

## Why ITSA

- **One function, full model** — `tsanalysis(...)`; no config files, no CLI to wire up.
- **Discontinuities handled automatically** — pulls the station **site log** and a
  **live earthquake catalogue** (USGS / EMSC / ISC, kept current), so you never
  hand-collect offset dates.
- **Physically meaningful parameters** — velocity, seasonal amplitudes and each
  offset come out **with formal uncertainties**, ready for strain, InSAR
  referencing or deformation studies.
- **Publication-ready outputs** — a parameter table, modelled series and
  diagnostic plots per station.

## Install

```bash
pip install istsa
```

Python ≥ 3.7 · depends on `numpy`, `scipy`, `pandas`, `matplotlib`, `pyarrow`.

## Quick start

```python
from itsa.tsanalysis import tsanalysis

tsanalysis(
    time_series_file="STAT.pos",   # GNSS time series in PBO .pos format
    path_workdir="./work",         # inputs + results are written here
    position=(45.19, 5.72),        # (latitude, longitude) in degrees
    provider="usgs",               # seismic catalogue: "usgs", "emsc" or "isc"
)
```

That single call fetches the site log and seismic catalogue it needs, fits the
trajectory model, and writes everything to `RESULTS/<STAT>/`.

Useful knobs: `Mw_min` (min. earthquake magnitude), `ref_frame`, `acc=True`
(fit acceleration), `tau_post` (post-seismic relaxation time),
`skip_outliers_filter`. Full list in the `tsanalysis` docstring.

## Inputs

- GNSS time series in **PBO**, **GipsyX** (`YYYY MM DD X Y Z …`), **NGL** or
  **F3** format (auto-detected), named with the station's **4-character** code
  (`ATAL.pos`) or full **9-character** IGS code (`ATAL00GRC.pos`)
- station coordinates *(latitude, longitude)* — for the earthquake–station
  distance and, if needed, to look up the site log (not required when the file
  name already carries the 9-character code)
- *(optional)* user-supplied station metadata (site log or `staDB`) and
  discontinuity dates; see the wiki for the manual-input layout

## Outputs — `RESULTS/<STAT>/`

| File | Content |
|------|---------|
| `<STAT>_parameters.txt` | Fitted parameters with 1σ: constant, **velocity** (mm/yr, N/E/U), annual & semi-annual seasonal terms, and every offset (antenna `_A`, co-seismic `_E`, post-seismic `_P`) |
| `<STAT>_model.txt` | Observed and modelled N/E/U series per epoch |
| `<STAT>_data.png` | Time series with the fitted trajectory model |
| `<STAT>_res.png` | Post-fit residuals |

## Options reference

Only `time_series_file` and `path_workdir` are required (plus `position` when
no `metadata_file` is given). Everything else has a sensible default.

**Data, frame & catalogue**

| Option | Default | Meaning |
|--------|---------|---------|
| `time_series_file` | — | Path to the GNSS time series (PBO `.pos`). **Required.** |
| `path_workdir` | — | Working directory; `INPUT_FILES/` and `RESULTS/` are written here. **Required.** |
| `position` | `(None, None)` | `(latitude, longitude)` in degrees — earthquake–station distance and site-log lookup. |
| `metadata_file` | `None` | Station site log / staDB path. If `None`, it is downloaded using `position`. |
| `provider` | `"usgs"` | Seismic catalogue source: `"usgs"`, `"emsc"` or `"isc"`. |
| `ref_frame` | `"IGS14"` | Reference frame of the input positions. |
| `save_frame` | `"IGS14"` | Output frame / tectonic plate (`EURA`, `NOAM`, `SOAM`, `PCFC`, …). |
| `software` | `"GipsyX"` | Software that produced the positions (`"GipsyX"`, `"GAMIT"`). |
| `station_input_type` | `None` | Metadata format: `"gipsyx"`, `"gamit"`, `"all"` (`None` → gipsyx). |
| `station_input_name` | `None` | Metadata file/folder name (`None` → `staDB`). |

**Time window, inversion & outliers**

| Option | Default | Meaning |
|--------|---------|---------|
| `ini_time` | `None` | Analysis start `[year, month, day]` (`None` → first epoch). |
| `fin_time` | `None` | Analysis end `[year, month, day]` (`None` → last epoch). |
| `skip_inversion` | `False` | Only write the PBO `.pos`, skip the modelling. |
| `auto_skip_inversion` | `True` | Auto-skip inversion when fewer than 100 valid points. |
| `skip_outliers_filter` | `False` | Bypass outlier filtering. |
| `thresh` | `5` | Outlier threshold, in multiples of the window MAD. |
| `window_len` | `60` | Sliding-window length (days) for outlier filtering. |
| `perc_ts` | `0` | Minimum % of valid data required (`0` = keep all). |

**Event detection — magnitude & distance**

| Option | Default | Meaning |
|--------|---------|---------|
| `Mw_min` | `5.1` | Minimum magnitude for any seismic event considered. |
| `Mw_post` | `6.1` | Minimum magnitude to add a post-seismic transient. |
| `Mw_spe` | `8` | Minimum magnitude for a special (distinct-model) post-seismic. |
| `dco` | `1.15` | Co-seismic influence-radius factor (distance scaling). |
| `dpost` | `1.3` | Post-seismic influence-radius factor. |
| `dsse` | `1` | Slow-slip-event influence-radius factor. |
| `dsw` | `1.0` | Swarm influence-radius factor. |

**Post-seismic model**

| Option | Default | Meaning |
|--------|---------|---------|
| `pre_post` | `False` | Include the last pre-period post-seismic event (`True`), or if within `N` days (`int`). |
| `mod_post` | `"log10"` | Relaxation model: `"log10"` (logarithmic) or `"exp"` (exponential). |
| `jps_window_data` | `365` | Window (days) for modelling jumps. |
| `post_window_data` | `730` | Window (days) for the post-seismic fit. |
| `tau_jps` | `10` | Relaxation time (days) for jump windows. |
| `tau_post` | `30` | Relaxation time (days) for post-seismic. |
| `tau_spe` | `1` | Relaxation time for special post-seismic. |
| `acc` | `False` | Also fit an acceleration term. |

**Figures, by-products & parallelism**

| Option | Default | Meaning |
|--------|---------|---------|
| `disp_window` | `True` | Save/show the sliding-window figure. |
| `byp_make` | `False` | Generate by-products (residuals, detrended series, per-component corrections). |
| `byp_names` | `["RESIDUALS","PHY","GEO"]` | Output folder names for the by-products. |
| `byp_vel` | `[True,False,True]` | Per by-product: remove velocity/acceleration. |
| `byp_seas` | `[True,False,True]` | Per by-product: remove seasonal (annual + semi-annual). |
| `byp_ant` | `False` | Correct antenna-change offsets in the by-products. |
| `byp_co` | `[True,False,True]` | Per by-product: handle co-seismic jumps. |
| `byp_sw` | `[True,False,True]` | Per by-product: handle swarm events. |
| `byp_sse` | `[True,False,True]` | Per by-product: handle slow-slip events. |
| `byp_post` | `[True,False,True]` | Per by-product: handle post-seismic. |
| `disp_byp` | `[False,True,True]` | Per by-product: display figures. |
| `parallel` | `False` | Process multiple stations in parallel (joblib). |
| `n_jobs` | `1` | Number of parallel jobs when `parallel=True`. |

## What's new in 1.1.0

The seismic catalogue is now **live and incremental**: ITSA downloads a baseline
once, then appends new events from the provider's service (USGS / EMSC / ISC) up
to today — so recent co-seismic offsets are no longer missed. Network hiccups
are non-fatal. Details in [`CHANGELOG.md`](CHANGELOG.md).

## Documentation

**Using the PyPI package (Python API):**
https://gricad-gitlab.univ-grenoble-alpes.fr/isterre-cycle/itsa/-/wikis/Use-ITSA-as-a-Python-module

That page has a complete, self-contained usage guide with a practical example
(install, inputs, station metadata, outputs, options).  The *Quick start* above
is all you need to get going.

For the modelling background and the original command-line workflow, see the
wiki home: https://gricad-gitlab.univ-grenoble-alpes.fr/isterre-cycle/itsa/-/wikis/home

## License

**CC BY-NC 4.0** — https://creativecommons.org/licenses/by-nc/4.0/
