istsa 1.1.2

Trajectory-model analysis of GNSS time series: velocity, seasonal signals, co-seismic and post-seismic offsets.

ITSA — ISTerre Time Series Analysis

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

# 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

pip install istsa

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

---

Quick start

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.

---

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 for details.

---

Documentation

• Wiki — 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 — 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.