istsa 1.1.0

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, 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

pip install istsa

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

Quick start

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 .pos format
• station coordinates (latitude, longitude) — for the earthquake–station distance
• (optional) user-supplied discontinuity dates and a list of position outliers

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.

Method & background

The modelling approach and the original command-line workflow are documented on the ISTerre wiki: https://gricad-gitlab.univ-grenoble-alpes.fr/isterre-cycle/itsa/-/wikis/home

This PyPI package exposes the same engine as an importable Python API (itsa.tsanalysis.tsanalysis) — the Quick start above is all you need; no command-line setup required.

License

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