Output Files

---

Overview

Every RRINGG run writes its results to the directory given by --output_directory (default: data/output/). Outputs fall into three categories:

1. Corrected raster — the primary geodetic product (GeoTIFF).

2. Processing metadata — a JSON file documenting stations, fitted parameters, and quality metrics.

3. Diagnostic figures — PNG images for visual quality control.

All file names begin with the prefix RRINGG_. Figures additionally embed the GNSS source code (e.g. EPOS, NGL, CSV).

---

Correction mode

Triggered by -po correction (the default).

Primary output

File: RRINGG_{input_filename}

The input raster is copied to the output directory and corrected in-place. The file name is preserved; only RRINGG_ is prepended.

Format	GeoTIFF, same band count and data type as the input
Units	Same as input (mm/yr if Value_unit: mm in the .meta; rad/yr otherwise — see Input Data)
Geometry	Unchanged affine transform and CRS; NoData pixels are preserved
Content	Bias-corrected mean LOS velocity field. Every valid pixel has been reduced by \(a \cdot \text{lon} + b \cdot \text{lat} + c\) where \(a\), \(b\), \(c\) are the fitted plane parameters (see JSON metadata below).

Processing metadata

File: RRINGG_{input_basename}.json

Machine-readable record of the full processing session, formatted as a structured JSON document.

Top-level sections:

Key	Content
schema	Schema name and version (rringg-metadata v3)
product	Processing operation, geometry type, generation timestamp
software	RRINGG version, source repository URL, licence
reproducibility	Full command line used, working directory, paths of input/output files, random seed (RANSAC)
units	Unit declarations for every numeric field (coordinates in degrees, velocities in mm/yr, etc.)
processingConfiguration	GNSS source, reference frame, plate code, minimum observation days, minimum InSAR/GNSS overlap fraction
processingParameters	All fitting results and per-station data (see below)
inputDataDescription	InSAR product metadata parsed from the .meta sidecar (sensor, mode, dates, bounding polygon, etc.)

processingParameters sub-sections:

Sub-key	Content
fitting	Fitting method, weighted flag, plane equation, convergence tolerance, iteration limit, cross-validation folds, fitted parameters \(a/b/c\) with uncertainties \(\sigma_a/\sigma_b/\sigma_c\), and quality metrics
gnssInfo	Raw metadata returned by the GNSS adapter (API version, etc.)
gnssStationSummary	Source code and total number of stations used
paramGnssStation	Per-station record for every station that entered the fit

Per-station fields in paramGnssStation.stations:

Field	Unit	Description
processingCentre	—	GNSS analysis centre (e.g. UGA-CNRS)
latitude / longitude / height	deg / deg / m	Station coordinates (WGS-84)
ve / vn / vu	mm/yr	East / North / Up velocity components
se / sn / su	mm/yr	1σ uncertainty on each component
gnssLosVelocity	mm/yr	GNSS velocity projected onto the InSAR LOS
gnssLosStd	mm/yr	LOS-projected 1σ uncertainty
gnssWeight	—	Normalised a priori weight used in the fit (\(w \propto N / \sigma_{\text{LOS}}^2\))
insarLosVelocity	mm/yr	Raw InSAR velocity sampled at the station location (before correction)
insarLosVelocityCorrected	mm/yr	InSAR velocity after the fitted plane has been subtracted
residualBefore	mm/yr	insarLosVelocity − gnssLosVelocity before correction
residualAfter	mm/yr	insarLosVelocityCorrected − gnssLosVelocity after correction
numberOfDays	days	Number of GNSS observation days in the time series
insarOverlapDays	days	Days of overlap between the GNSS series and the InSAR window
startDate / endDate	ISO-8601 UTC	Temporal span of the GNSS time series

Fitted-plane parameters in processingParameters.fitting:

Field	Unit	Description
params.a	mm/yr/°	East–west gradient of the bias plane. A value of 0.3 means the ramp increases by 0.3 mm/yr per degree of longitude across the scene.
params.b	mm/yr/°	North–south gradient.
params.c	mm/yr	Constant orbital offset (value of the plane at lon = 0, lat = 0). In practice this is the dominant term for scenes far from the equator/prime meridian.
uncertainties.sigmaA / sigmaB / sigmaC	same as a / b / c	1σ formal uncertainties from the weighted covariance matrix \(\hat\sigma^2 (\mathbf{A}^\top \mathbf{W} \mathbf{A})^{-1}\)
metrics.mse	(mm/yr)²	Weighted mean squared fitting residual
metrics.mae	mm/yr	Mean absolute fitting residual (inliers only)
metrics.r2	—	Weighted R² of the plane fit on (InSAR − GNSS) differences
metrics.wrss	(mm/yr)²	Weighted residual sum of squares
metrics.cvMse	(mm/yr)²	K-fold cross-validation MSE (default K = 5)

Diagnostic figures

{SRC} is the GNSS source code (EPOS, NGL, or CSV).

RRINGG_{SRC}_STATIONS_MAP_BEFORE.png

Geographic map of all GNSS stations entering the fit, plotted on top of the InSAR footprint. Each station is colour-coded by number of observation days (numberOfDays); longer series appear brighter. Voronoi cells show the spatial influence area of each station — irregular, oversized cells flag poor spatial coverage and may trigger the kriging fallback. Produced before plane fitting, so it reflects the distribution assessment made to decide whether kriging is needed.

RRINGG_{SRC}_SCATTER_BEFORE.png

Scatter plot of GNSS LOS velocity (x-axis) against raw InSAR LOS velocity (y-axis) at each station position, before correction. A dashed 1:1 reference line is drawn.

• Deviation from the 1:1 line indicates the magnitude of the bias.

• A systematic tilt (slope ≠ 1) suggests a gradient component (non-zero \(a\) or \(b\)).

• A vertical offset (intercept ≠ 0 at identical velocities) points to a dominant constant term \(c\).

• Scattered outliers that deviate strongly are the stations that IRLS will downweight or RANSAC will exclude.

RRINGG_{SRC}_SCATTER_AFTER.png

Same axes as BEFORE, but insarLosVelocityCorrected replaces the raw InSAR velocity. After a successful correction, points should cluster tightly around the 1:1 line. Residual scatter reflects short-wavelength InSAR noise and GNSS measurement uncertainty, which the plane model cannot remove.

RRINGG_{SRC}_STATIONS_MAP_AFTER.png

Station map coloured by the absolute post-correction residual \(|\text{insarLosVelocityCorrected} - \text{gnssLosVelocity}|\). Values near zero (cool colours) confirm that the plane has successfully absorbed the bias at that location. Persistently large residuals (warm colours) point to stations with local deformation or poor LOS projection — check them against the bar chart below.

RRINGG_{SRC}_RESIDUALS.png

Horizontal bar chart with one bar per station, ordered by station name. Each bar shows residualBefore (before correction). Bars are coloured by inlier status derived from fit.inlier_mask:

• Inlier (green) — station contributed normally to the fit.

• Outlier (red) — station was down-weighted (IRLS final robust weight < 1 %) or excluded (RANSAC). Its value is still plotted for reference but did not influence the final plane parameters.

Use this chart to identify stations that systematically diverge from the others and may require investigation (e.g. unknown local subsidence, wrong LOS projection, or data quality issue).

RRINGG_{SRC}_RESIDUAL_HISTOGRAM.png

Overlaid histograms of residualBefore (grey) and residualAfter (blue), with a fitted normal distribution curve for each. A well-corrected dataset shows:

• Before: broad, possibly asymmetric distribution with mean ≠ 0.

• After: narrow, symmetric distribution centred close to 0.

A heavy tail remaining in the after histogram indicates either unconverged outlier stations or a bias that is not well described by a linear plane.

RRINGG_{SRC}_FITTED_PLANE.png

Filled-contour map of the fitted plane \(a \cdot \text{lon} + b \cdot \text{lat} + c\) evaluated over the full InSAR footprint, overlaid with station locations coloured by residualBefore. The dynamic range of the contours shows the total amplitude of the corrected bias. Typical values range from a few mm/yr to ~15 mm/yr for uncorrected C-band scenes.

RRINGG_{SRC}_METRICS_SUMMARY.png

Summary table rendered as an image for quick inspection in file browsers. It reproduces the six metrics from processingParameters.fitting.metrics (see table above) together with the plane parameters and inlier count.

---

Referencing mode

Triggered by -po referencing.

Primary output

File: RRINGG_{input_filename}

Format	GeoTIFF, multi-band float32
Band count	One band per acquisition date in the input time series
Band order	Chronological; matches listOfDates in the JSON metadata
Units	mm (absolute LOS displacement referenced to the GNSS frame)
Content	Each band has the per-epoch bias plane subtracted, converting relative phase displacements to absolute LOS displacements in the GNSS reference frame.

Processing metadata

File: RRINGG_{input_basename}.json

Same structure as correction mode. The processingParameters.fitting section is replaced by referencing-specific fields:

Field	Content
method	differential or mean_velocity
Number of stations	Stations retained after trajectory modelling and quality filtering

Diagnostic figures

RRINGG_{SRC}_REFERENCING_STATION_MAP.png

Geographic map of GNSS stations retained after trajectory modelling (tsanalysis) and spatial distribution assessment. Only stations that pass all quality filters — time-series continuity, minimum observation days, and Voronoi distribution criterion — appear here. Stations coloured by number of observation days.

---

Interpreting the quality metrics

Metric	Interpretation
R²	Fraction of the spatial variance in (InSAR − GNSS) explained by the fitted plane. R² ≈ 0.8–1.0 → strong, well-structured ramp; the plane model is appropriate. R² ≈ 0.3–0.7 → moderate gradient; correction is useful but some non-planar component may remain. R² < 0.3 → differences are dominated by noise rather than a coherent gradient. The correction still removes the mean offset (\(c\) term) but the spatial pattern is weak. Inspect the FITTED_PLANE figure to confirm. Warning A low R² does not mean the correction is wrong. If the dominant bias is a uniform offset (large \(c\), small \(a\) and \(b\)) the plane explains most of the error in absolute terms but R² stays low because the spatial variance is small. Use RMSE and the SCATTER_AFTER figure to assess overall quality.
RMSE	Root-mean-square fitting residual in mm/yr. Values below 1 mm/yr indicate excellent fit; 1–3 mm/yr is typical for real datasets; above 5 mm/yr suggests unmodelled local deformation or poor station quality.
MAE	Mean absolute fitting residual (inliers only), in mm/yr. Less sensitive to outliers than RMSE. Compare MAE vs RMSE: a large gap (RMSE >> MAE) reveals a few stations with very large residuals worth investigating.
σ²	Weighted residual variance \(\text{WRSS}/(N-3)\) where N is the total number of stations. Used internally to compute parameter uncertainties \(\sigma_a\), \(\sigma_b\), \(\sigma_c\).
CV-MSE	K-fold cross-validation MSE. Compared to MSE: CV-MSE ≈ MSE → good generalisation; the three parameters are well constrained. CV-MSE >> MSE → overfitting; typically occurs when N < 8 stations, making the 3-parameter plane poorly constrained.
Inlier count	Number of stations contributing with full weight to the final fit. Stations flagged as outliers (IRLS robust weight < 1 % or RANSAC rejection) still appear in all figures for traceability. An inlier fraction below 70 % warrants inspection of the RESIDUALS figure.

---

Guidance by situation

Observation in the outputs	Recommended action
SCATTER_AFTER points tightly on the 1:1 line, low RMSE	Correction successful — use the corrected raster.
SCATTER_BEFORE shows tilt; SCATTER_AFTER removes it	Gradient (non-zero \(a\) or \(b\)) successfully corrected.
Large residuals on a few stations in RESIDUALS.png	Inspect those stations individually (local deformation? bad LOS projection?). Consider adding them to --remove_station.
Heavy tail remains in RESIDUAL_HISTOGRAM after correction	Possibly non-planar bias. Try a wider GNSS coverage (increase --scale) to better constrain the plane.
R² < 0.2, RMSE < 1 mm/yr, FITTED_PLANE shows near-zero amplitude	The InSAR scene was already well referenced. The correction is numerically small and safe to apply.
CV-MSE >> MSE (e.g. ratio > 3)	Too few stations for 3 parameters. Add stations via --local_timeseries or --velocity_file.
Most stations flagged as outliers in RESIDUALS.png	RANSAC threshold may be too tight, or genuine data quality issue. Re-run with -fi irls (IRLS is more tolerant).