Metadata-Version: 2.4
Name: istsa
Version: 1.1.2
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
Requires-Dist: requests
Requires-Dist: geopandas
Requires-Dist: shapely
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, each with a
> 1σ uncertainty.

ITSA fits the full **trajectory model** of GNSS position time series. It locates
the discontinuities for you — earthquakes, equipment changes, slow-slip — and
estimates offsets, post-seismic transients, seasonal signals, a linear velocity
and (optionally) acceleration. You get ready-to-use parameters and publication
plots without touching a config file.

And it is not only a fitter: ITSA ships a small, dependency-light **geodesy
toolbox** you can call on its own — reference-frame changes (ITRF↔ITRF,
plate-fixed, ETRF2020), coordinate conversions, Euler-pole velocities and
multi-format time-series I/O.

Built in the **ISTerre Cycle** team by Lou Marill.

---

## Why ITSA

- **One function, the whole model** — `tsanalysis(...)`. No CLI to wire up, no
  configuration files.
- **Discontinuities handled for you** — ITSA pulls the station **site log** and a
  **live earthquake catalogue** (USGS / EMSC / ISC, updated to today), so you
  never hand-collect offset dates. Miss no recent co-seismic jump.
- **Physically meaningful parameters** — velocity, seasonal amplitudes and each
  offset come out **with formal uncertainties**, ready for strain, InSAR
  referencing or deformation studies.
- **Any input format** — PBO, GipsyX, NGL, F3, SPOTGINS (.enu) and JPL (.series) are auto-detected; stations are
  keyed by their 4- or full **9-character IGS code**, never truncated.
- **Publication-ready outputs** — a parameter table, the observed + modelled
  series, and diagnostic plots, per station.

---

## More than a fitter — a GNSS geodesy toolbox

Every building block is importable on its own and operates on plain NumPy
arrays or a lightweight `Gts` object — no full analysis required.

| You want to… | Use | Highlight |
|--------------|-----|-----------|
| Change reference frame | `itsa.transform.helmert_transform`, `Gts.itrf_convert` | 14-parameter Helmert between any tabulated ITRF/IGS |
| Put a series in a plate-fixed frame | `itsa.transform.change_frame_file`, `Gts.fixed_plate` | ITRF2020 PMM poles, **ETRF2020** convention, optional **Origin Rate Bias** (horizontal-only) |
| Predict a plate-motion velocity | `itsa.transform.plate_fixed_velocity` | Euler-pole velocity at a site, in mm/yr |
| Estimate a robust velocity | `itsa.lib.midas` | MIDAS trend estimator (no step detection needed) |
| Convert coordinates | `itsa.lib.coordinates` | ECEF ↔ geodetic ↔ spherical, ENU rotation matrices |
| Work with Euler poles | `itsa.lib.euler` | rotation-rate vector ↔ Euler pole, site velocity |
| Read/write any TS format | `itsa.transform.read_pos`, `Gts.write_PBOpos` | one call, format auto-detected |
| Convert dates | `itsa.lib.astrotime` | decimal-year ↔ calendar ↔ MJD ↔ DOY |

```python
# Re-express a GNSS series in the Eurasia-fixed frame — one call, no analysis
from itsa.transform import change_frame_file
change_frame_file("BRST00FRA.pos", "out/", plate="EURA",
                  itrf_ref="ITRF2020", apply_orb=True)
```

---

## Install

```bash
pip install istsa
```

Python ≥ 3.7 · depends on `numpy`, `scipy`, `pandas`, `matplotlib`, `pyarrow`,
`requests`, `geopandas`, `shapely` (installed automatically).

---

## Quick start

```python
from itsa.tsanalysis import tsanalysis

tsanalysis(
    time_series_file="BRST00FRA.pos",   # PBO / GipsyX / NGL / F3 / SPOTGINS / JPL .series (auto-detected)
    path_workdir="./work",              # inputs + results are written here
    position=(48.380, -4.497),          # (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 `./work/RESULTS/<STATION>/`.

Useful knobs: `Mw_min` (min. earthquake magnitude), `ref_frame`, `save_frame`
(output frame / plate), `acc=True` (fit acceleration), `tau_post` (post-seismic
relaxation time), `parallel`. **The full guide, with a real worked example and
every option, is on the [wiki — *Use ITSA as a Python module*](https://gricad-gitlab.univ-grenoble-alpes.fr/isterre-cycle/itsa/-/wikis/Use-ITSA-as-a-Python-module).**

---

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

| File | Content |
|------|---------|
| `<STATION>_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`) |
| `<STATION>_data.png` + `_data_model.txt` | Time series with the fitted model, plus an aligned table (decimal year, ISO date, MJD, observed & modelled N/E/U) |
| `<STATION>_res.png` | Post-fit residuals |
| `<STATION>_events.txt` | Seismic & aseismic event catalogue behind the offsets — antenna change, earthquake, post-seismic and SSE dates with type/location/magnitude |
| `<STATION>.pos` | Copy of the **raw input** series that was read (kept for traceability) |
| `OTHER/` | Full output tree — `OUTPUT_FILES/` (Green's matrix, model amplitudes, JPS catalogue, QC) and `PLOTS/` (all diagnostic figures). Wiped and rebuilt on every run |
| `METADATA/` *(if `keep_metadata=True`)* | The staDB and site log(s) actually used for the equipment offsets |

---

## Accepted inputs

- **GNSS time series** in **PBO**, **GipsyX** (`YYYY MM DD X Y Z …`), **NGL**,
  **F3**, **SPOTGINS** (`.enu`) or **JPL** (`.series`) format — auto-detected from
  the file *content*, so the extension does not matter. Name the file with the
  station's 4-character code (`ATAL.pos`) or full 9-character IGS code
  (`ATAL00GRC.pos`). JPL `.series` files carry no reference position, so a
  `position=(lat, lon)` is required for those.
- **Station coordinates** `(latitude, longitude)` — for the earthquake–station
  distance and, if needed, the site-log lookup (not required when the file name
  already carries the 9-character code).
- *(optional)* your own station metadata (IGS site log or `staDB`) and
  discontinuity dates.

---

## What's new in 1.1.2

- **Two new native formats** — **SPOTGINS** (`.enu`) and **JPL** (`.series`) are
  now auto-detected and read like the others (JPL needs a `position=(lat, lon)`,
  as its files carry no reference position).
- **Robust PBO reader** — the data start and header fields are located by label /
  column marker, so PBO variants with extra or reordered header lines (e.g. the
  CNRS-UGA / ISTerre GipsyX product) read correctly.
- **Metadata is now mandatory with explicit errors** — if no staDB / site log can
  be obtained, or a provided one is invalid, the run stops with an actionable
  message instead of silently dropping equipment offsets or crashing obscurely.
- **Fresh reprocessing** — each run wipes the station's full output tree
  (`RESULTS/<station>/OTHER/`) and refreshes the curated essentials, so nothing
  stale lingers; other stations are never touched.
- **Python 3.11 / 3.12 compatible** — the `Jps` dataclass no longer uses mutable
  NumPy defaults.

See [`CHANGELOG.md`](CHANGELOG.md) for details.

---

## Documentation

- **[Wiki — *Use ITSA as a Python module*](https://gricad-gitlab.univ-grenoble-alpes.fr/isterre-cycle/itsa/-/wikis/Use-ITSA-as-a-Python-module)**
  — complete user guide: worked example, inputs, station metadata, outputs, the
  full option reference, and the geodesy toolbox (frame changes, coordinates,
  Euler poles, catalogues).
- **[Wiki home](https://gricad-gitlab.univ-grenoble-alpes.fr/isterre-cycle/itsa/-/wikis/home)**
  — modelling background and the original command-line workflow.

---

## License & credits

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

Developed at **ISTerre** (Université Grenoble Alpes) by Lou Marill and the
ISTerre Cycle team. If ITSA supports your research, please cite it and
acknowledge ISTerre.
