Running RRINGG¶

Overview¶

RRINGG is executed from the command line. It ingests InSAR raster products and GNSS velocity data, then writes corrected or referenced rasters together with a full set of diagnostic figures and a .meta sidecar file.

Two operations are available:

Correction of an InSAR velocity field (-po correction)
Referencing of an InSAR displacement time series (-po referencing)

Preprocessing — EPOS TCS CSV data¶

Note

Data downloaded from the EPOS Thematic Core Service (product type DTSLOS) are delivered as CSV files. They must be converted to GeoTIFF format with the bundled helper script before being passed to RRINGG.

python src/tools/csv2raster.py \
  --time_series_csv_path input_data.csv \
  --output_path ./rasterized_output/

`csv2raster.py` arguments¶
Argument	Description	Type	Default
`-ts`, `--time_series_csv_path`	Path to the DTSLOS CSV file	`<path>`	required
`-xr`, `--x_resolution`	Pixel size in the X direction (decimal degrees)	`<float>`	None
`-yr`, `--y_resolution`	Pixel size in the Y direction (decimal degrees)	`<float>`	None
`-nv`, `--nodata_value`	Value assigned to no-data pixels	`<float>`	NaN
`-op`, `--output_path`	Directory where rasters and metadata files are written	`<path>`	required

Warning

The script also writes an auxiliary file RRINGG_[NAME]_COORDINATES.txt listing the geographic coordinates of every generated pixel centre. Load this file alongside the raster in a GIS (e.g. QGIS) to verify that the chosen resolution produces the expected pixel grid. A visual quality check at this stage is strongly recommended before proceeding with correction or referencing.

Command syntax¶

rringg [options]

Command-line arguments¶

Argument	Short	Default	Description
`--processing_operation`	`-po`	`correction`	Operation to perform: `correction` or `referencing`
`--geometry_type`	`-gt`	`ground`	Raster geometry: `ground` (EPSG:4326) or `radar`
`--velocity_raster_path`	`-vr`	—	Path to the mean LOS velocity raster (GeoTIFF). Required when `-po correction`
`--time_series_raster_path`	`-ts`	—	Path to the multi-band displacement time-series raster (GeoTIFF). Required when `-po referencing`
`--los_vectors`	`-lo`	—	Path to the LOS unit-vector raster (3-band GeoTIFF, ENU or NEU convention). Always required
`--los_convention`	`-lc`	`auto`	Band ordering of the LOS vector file. `ENU` — bands are [East, North, Up], vector satellite→ground (FLATSIM / GeoTIFF products). `NEU` — bands are [North, East, Up], vector ground→satellite (EPOS TCS CSV products); bands are reordered and sign is inverted automatically. `auto` — inferred from the file content; raises an error if ambiguous.
`--lut_radar`	`-lr`	None	Radar→ground geometry LUT (GeoTIFF). Required when `-gt radar`
`--lut_ground`	`-lg`	None	Ground→radar geometry LUT (GeoTIFF). Required when `-gt radar`
`--referencing_method`	`-rm`	`differential`	Referencing method: `differential` or `mean_velocity`
`--reference_date`	`-rd`	None	Reference date (`YYYY-MM-DD`) matching an acquisition in the time series. Required when `-rm mean_velocity`
`--plate`	`-pl`	`POSI`	ITRF tectonic plate code for plate-motion correction. Common values: `EURA`, `NOAM`, `NUBI`, `POSI`, `ABSO`
`--fitting`	`-fi`	`least_squares`	Plane-fitting algorithm: `least_squares` (IRLS) or `ransac`
`--velocity_file`	`-vf`	None	Path to a user-supplied GNSS velocity text file containing pre-computed ve/vn/vu values. Correction mode only — referencing mode requires full time-series files and will fail without them. When provided, activates standalone mode: no external GNSS data is downloaded.
`--local_timeseries`	`-lt`	None	Path to a directory of local GNSS time-series files used as the exclusive GNSS source — no data is downloaded from EPOS or NGL. Velocities are computed automatically via MIDAS. Works in both correction and referencing modes — the raw `.pos` files are used directly by the referencing trajectory modeller. Accepted file formats: `.pos` — PBO / GipsyX format (directly parsed) `.txt` — GipsyX format (auto-converted to `.pos`) File names must be exactly 4 or 9 characters before the extension (e.g. `BRST.pos`, `BRST00FRA.pos`). Typical use cases: using stations from a regional network (RGP, EUREF, campaign sites) when EPOS/NGL coverage is insufficient, or processing in a fully offline environment. See IV — Local GNSS Time-Series Directory in the Input Data reference for the full PBO `.pos` file format, a minimal example, constraints, and the note on antenna-jump pre-correction (Antenna jumps and sitelogs).
`--remove_stations`	`-rs`	None	One or more station codes to exclude from the processing (space-separated list)
`--output_directory`	`-ou`	From `CFG.io.output_directory`	Directory where corrected rasters, figures, and `.meta` files are written
`--cache_directory`	`-cd`	From `CFG.io.cache_directory`	Directory used to cache downloaded GNSS metadata and time series
`--work_directory`	`-wd`	From `CFG.io.work_directory`	Working directory for temporary intermediate files
`--scale`	`-sc`	From `CFG.spatial.scale_bbox`	Multiplicative scale factor applied to the InSAR bounding box before querying GNSS stations (default 1.2)
`--log-level`	—	`INFO`	Console logging verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR`
`--log-file`	—	None	Path to an optional log file. All levels are written regardless of `--log-level`

Example workflows¶

1 — Velocity-field correction (ground geometry)¶

Minimal invocation. GNSS source is defined in config.py.

rringg \
  -po correction \
  -gt ground \
  -vr data/velocity.tiff \
  -lo data/los_vectors.tiff \
  -ou results/correction

2 — Velocity-field correction with plate override and station exclusion¶

rringg \
  -po correction \
  -vr data/velocity.tiff \
  -lo data/los_vectors.tiff \
  -pl EURA \
  -rs BADSTATION1 BADSTATION2 \
  -fi ransac \
  -ou results/correction_eura

3 — Time-series referencing, differential method (radar geometry)¶

differential uses the full GNSS time series and does not require a reference date. The reference epoch is set automatically to the first InSAR acquisition.

rringg \
  -po referencing \
  -gt radar \
  -ts data/series.tiff \
  -lo data/los_vectors.tiff \
  -lr data/lut_radar.tiff \
  -lg data/lut_ground.tiff \
  -rm differential \
  -ou results/referencing

4 — Time-series referencing, mean-velocity method (ground geometry)¶

mean_velocity assumes linear GNSS motion; --reference_date is required.

rringg \
  -po referencing \
  -gt ground \
  -ts data/series.tiff \
  -lo data/los_vectors.tiff \
  -rm mean_velocity \
  -rd 2021-08-15 \
  -ou results/referencing_mv

5 — Correction with a user-supplied GNSS velocity file (standalone mode)¶

When -vf is provided, RRINGG uses the text file exclusively and performs no external network request.

rringg \
  -po correction \
  -vr data/velocity.tiff \
  -lo data/los_vectors.tiff \
  -vf data/my_stations.txt \
  -ou results/correction_local

6 — Debug run with full logging to file¶

rringg \
  -po correction \
  -vr data/velocity.tiff \
  -lo data/los_vectors.tiff \
  -ou results/correction \
  --log-level DEBUG \
  --log-file results/rringg_debug.log

Notes and best practices¶

Coordinate systems

All rasters (velocity field, time series, LUT) should share the same projection. Ground-geometry products must use EPSG:4326 (WGS-84 geographic).

LOS convention

Verify whether the LOS raster uses ENU or NEU band ordering. If the sign convention is opposite to InSAR convention, pass --los_convention NEU (or -lc NEU) to reorder bands and invert the sign automatically.

Plate-motion correction

Use --plate to select the ITRF plate code appropriate for your study region (e.g. EURA for Europe, NOAM for North America). The default is defined in config.py; see Configuration for the full list of supported codes.

Station exclusion

Use --remove_stations to exclude stations that are known to be noisy, affected by local non-tectonic deformation, or temporally discontinuous.

Referencing method choice

mean_velocity — efficient, assumes linear GNSS motion. Best for stable tectonic or subsidence environments.
differential — uses full GNSS time series. Better when non-linear deformation is present (postseismic, volcanic, seasonal).

Fitting method choice

least_squares (IRLS) — converges robustly with Huber or Tukey reweighting; preferred when the station network is clean.
ransac — more aggressive outlier rejection; useful when a significant fraction of stations may be contaminated.

Cache

Downloaded GNSS data are stored in the cache directory and reused on subsequent runs. To force a fresh download, either clear the cache or point --cache_directory to a new empty directory.