Configuration

---

How to change the defaults

All user-tunable parameters are centralised in a single file:

src/config.py

Open it with any text editor and modify the values directly:

nano src/config.py      # or: vim, code, gedit, …

Because RRINGG is installed in editable mode (pip install -e .), the change takes effect immediately on the next run — no reinstall required. See Installation method — editable clone (required) for an explanation of what editable mode means.

Note

Many parameters are also overridable per run via CLI flags without touching config.py:

# Change plate and fitting method for this run only
rringg -po correction -vr ... --plate EURA --fitting ransac

CLI flags take priority over the defaults in config.py. See Running RRINGG for the full list of CLI arguments.

---

Design rationale

src/config.py uses Python frozen dataclasses — once created at startup, the CFG singleton cannot be mutated by any module at runtime. This prevents accidental parameter overwrites in a multi-step pipeline where many modules share the same configuration object.

The single entry point for the rest of the codebase is:

from config import CFG           # read the defaults
print(CFG.fitting.weight_function)  # "huber"
print(CFG.gnss.source)              # "NGL"

To override defaults programmatically (e.g. in a script or notebook):

from config import ProcessingConfig, FittingConfig
cfg = ProcessingConfig(
    fitting=FittingConfig(max_iter=30),
)

The plane-fitting method (IRLS vs RANSAC) is controlled exclusively by the --fitting / -fi CLI flag at run time. It is not stored in FittingConfig.

Note

The former flat-variable tools/parameters.py module has been removed. Any code that previously imported from it should import from config instead.

---

Physical Constants

These are defined at module level in config.py and are not part of any dataclass (they are sensor-specific constants, not tunable parameters).

Constant	Value	Description
SENTINEL1_WAVELENGTH_MM	55.466	Sentinel-1 C-band carrier wavelength [mm].
RADIANS_TO_MM	λ / 4π	Converts interferometric phase [rad] → LOS displacement [mm].
MM_TO_RADIANS	4π / λ	Inverse of RADIANS_TO_MM.

---

IOConfig — I/O directories

Attribute access: CFG.io.<name>

Attribute	Default	Description
work_directory	repository root	Working directory for temporary intermediate files.
output_directory	<root>/output	Destination for corrected products, figures, and .meta files.
cache_directory	<root>/cache	On-disk cache for downloaded GNSS data.
cache_size_bytes	500 000 000	Maximum cache size in bytes (500 MB). LRU eviction is applied when this limit would be exceeded.

All four can be overridden from the command line with --work_directory, --output_directory, and --cache_directory.

---

FittingConfig — plane-fitting parameters

Attribute access: CFG.fitting.<name>

Attribute	Default	Description
weight_function	huber	Robust weight function used in the IRLS iterations. huber downweights linearly beyond the threshold (efficient under near-Gaussian noise); tukey hard-zeros large residuals (more aggressive outlier rejection).
huber_c	1.345	Huber threshold in units of normalised residuals. The value 1.345 gives 95 % asymptotic efficiency relative to OLS under normality.
tukey_c	4.685	Tukey bisquare constant. Residuals beyond this value receive weight 0.
max_iter	50	Maximum number of IRLS reweighting iterations.
tolerance	1 × 10⁻⁵	Convergence threshold on ‖Δβ‖ (Euclidean norm of parameter change).
weighted	True	Whether to apply a priori observation weights derived from GNSS precision and temporal coverage. Weights follow the Fisher-information formulation \(w_i \propto N_i / \sigma_i^2\), where \(N_i\) is the number of GNSS observation days and \(\sigma_i\) is the projected LOS velocity uncertainty. Normalised to unit mean.
cv_folds	5	Number of folds for the cross-validation performed once on the converged model (not inside the iteration loop).
ransac_min_samples	None	Minimum samples per RANSAC iteration. None → scikit-learn default (max(1, 0.1 × n_samples)).
ransac_residual_threshold	None	Inlier residual threshold [mm/yr]. None → MAD-based automatic selection.
ransac_max_outlier_fraction	0.30	If the detected outlier fraction exceeds this value, the fit is flagged as unreliable (FitResult.success = False).
inlier_weight_threshold	0.01	Minimum robust weight (relative to the a priori weight) for an observation to be classified as an inlier after IRLS convergence. Observations whose final \(w_\text{robust} / w_\text{prior}\) falls below this threshold are flagged as outliers in FitResult.inlier_mask.

Note

The plane-fitting algorithm (IRLS or RANSAC) is not stored in FittingConfig. It is controlled exclusively by the --fitting / -fi CLI flag (default least_squares).

---

GNSSConfig — data source and station selection

Attribute access: CFG.gnss.<name>

General

Attribute	Default	Description
source	NGL	Default online GNSS provider: NGL (Nevada Geodetic Laboratory) or EPOS (European Plate Observing System).
reference_frame	IGS20	Geodetic reference frame for velocity products. Supported: IGS20, IGS14.
plate	POSI	ITRF tectonic plate code for plate-motion correction. Common values: EURA, NOAM, NUBI, POSI, ABSO. Can be overridden at runtime with the --plate / -pl CLI flag.
priority_centre	UGA-CNRS	Preferred GNSS analysis centre (EPOS source only).
min_observation_days	365	Stations with fewer than this many days in their time series are discarded.
window_size	5	Half-width of the pixel window used when sampling the InSAR raster at a GNSS station location. The returned value is the mean over a (2 × window_size + 1)² pixel neighbourhood.
sar_wavelength_mm	55.466	SAR carrier wavelength [mm]. Used to convert raster units (radians) to LOS displacement [mm/yr]. Default is Sentinel-1; change this for other sensors.

Time-series format (EPOS)

Attribute	Default	Description
time_series_coord_sys	enu	Coordinate system for GNSS time series: enu (East-North-Up) or xyz (ECEF Cartesian).
time_series_format	json	Time-series download format: json, xml, or pbo.
time_series_sampling	daily	Temporal sampling: daily or weekly.
velocity_format	json	Velocity product format: json, midas, xml, hector, or pbo.

Seismicity (offset detection)

Attribute	Default	Description
min_seismic_magnitude	5.5	Minimum earthquake magnitude searched in the seismicity catalogue when detecting offsets in GNSS time series.
seismicity_catalogue_source	emsc	Catalogue source: emsc (European Mediterranean) or usgs.

Network endpoints

These URLs point to the online APIs used to retrieve GNSS metadata, time series, and velocity products. They should only need changing if a provider migrates their service.

Attribute	Default value
url_metadata_epos	https://gnssproducts.epos.ubi.pt/glass/stations/v2/station/bbox
url_time_series_epos	https://gnssproducts.epos.ubi.pt/glass/products/timeseries
url_velocities_epos	https://gnssproducts.epos.ubi.pt/GlassFramework/webresources/products
url_metadata_ngl	https://geodesy.unr.edu/velocities
url_time_series_ngl	https://geodesy.unr.edu/gps_timeseries/IGS20/tenv3 (tenv3 sub-path changes with reference_frame)
url_offsets_epos	https://gnssproducts.epos.ubi.pt/download-offsets
url_logfiles	https://gnss-metadata.eu/v1/sitelog/metadata-list?…

---

SpatialConfig — bounding box and distribution analysis

Attribute access: CFG.spatial.<name>

Attribute	Default	Description
scale_bbox	1.2	Multiplicative scale factor applied to the InSAR bounding box before querying GNSS stations. 1.0 = no expansion. The CLI flag is -sc.
bbox_type	bb	Bounding box convention: bb = axis-aligned rectangle, fbb = footprint-aligned (oriented with the scene).
grid_step_m	120 000	Grid spacing [m] used by the Ordinary Kriging fallback when the station spatial distribution is too poor for direct interpolation.
grid_x_offset_m	0.0	Eastward offset [m] applied to the Kriging grid origin.
grid_y_offset_m	0.0	Northward offset [m] applied to the Kriging grid origin.
distribution_cv_threshold	0.6	Voronoi-area coefficient of variation above which the station distribution is flagged as inhomogeneous.
distribution_pct_station	30.0	Maximum percentage of stations allowed to dominate the coverage (used with distribution_ratio_threshold).
distribution_ratio_threshold	4.0	Maximum ratio of Voronoi area to station-percentage share.
sea_mask_path	data/World_Water_Bodies.shp	Path to the water-bodies shapefile used to exclude sea areas from the InSAR footprint polygon.

---

ProcessingConfig — top-level container

ProcessingConfig aggregates the four sub-configs above. It is the single object passed through the pipeline so that every module can access its parameters without relying on hidden globals.

@dataclass(frozen=True)
class ProcessingConfig:
    io:      IOConfig
    fitting: FittingConfig
    gnss:    GNSSConfig
    spatial: SpatialConfig
    doi:     str           # DOI of the software release (used in .meta files)

The default singleton is:

CFG = ProcessingConfig()

and is importable from anywhere in the codebase:

from config import CFG