Troubleshooting¶

Installation issues¶

GDAL version conflict¶

Symptom

ImportError: cannot import name 'gdal' from 'osgeo'
# or
ImportError: libgdal.so.30: cannot open shared object file

Cause

The GDAL Python bindings version does not match the compiled GDAL library. This typically happens when GDAL is installed via pip without a matching system library, or when the conda environment is partially broken.

Fix

Always use the provided environment.yml:

conda env create -f environment.yml
conda activate rringg-env
pip install -e .

If the environment already exists but is broken, recreate it:

conda env remove -n rringg-env
conda env create -f environment.yml
conda activate rringg-env
pip install -e .

Verify with:

python -c "from osgeo import gdal; print(gdal.__version__)"
# Expected: 3.5.3

`rringg: command not found`¶

Cause

The editable install was not completed, or the conda environment is not active.

Fix

conda activate rringg-env
pip install -e .
rringg --help

GNSS data issues¶

No stations found in the InSAR footprint¶

Symptom

WARNING  No stations overlap the InSAR raster coverage.
# or
WARNING  0 valid station(s) found.

Causes and fixes

Likely cause	Fix
Bounding box too small	Increase `--scale` (default 1.2). Try `-sc 1.5` or `-sc 2.0` to widen the search area.
Wrong GNSS source for the region	The EPOS network covers Europe; NGL covers the globe. Switch source in `src/config.py`: `source = "NGL"`.
Minimum observation days too strict	Lower `CFG.gnss.min_observation_days` in `config.py` (default 365). Some regions have shorter records.
Plate code causes all stations to be removed	Try `-pl ABSO` (absolute frame, no plate-motion correction).

Network timeout or empty API response¶

Symptom

WARNING  EPOS API returned empty results for station …
# or
ConnectionError: HTTPSConnectionPool … Read timed out.

Causes and fixes

The EPOS or NGL server may be temporarily unavailable. Wait a few minutes and retry.
The EPOS server uses a self-signed certificate; SSL warnings are suppressed by design. If you see SSL errors, check your network proxy.
For repeated failures with EPOS, switch to NGL: source = "NGL" in config.py.
Once downloaded, data are cached in cache/. Subsequent runs do not require a network connection.

Processing issues¶

R² is very low — is the correction wrong?¶

Short answer: not necessarily.

R² measures the fraction of spatial variance in the InSAR–GNSS differences explained by the fitted bilinear plane. When the dominant bias is a uniform offset (constant term c dominates, with little lat/lon gradient), R² can be close to zero even after a successful correction.

How to assess correction quality instead:

Check the post-correction RMSE in the metrics summary (-METRICS_SUMMARY.png or the .meta JSON file). A low RMSE (< 1 mm/yr) indicates a good fit.
Inspect the scatter plot after correction (-SCATTER_AFTER.png): points should cluster tightly around the 1:1 line.
Inspect the residual histogram (-RESIDUAL_HISTOGRAM.png): the after-correction distribution should be narrow and centred near zero.

RANSAC fails with few stations¶

Symptom

WARNING  RANSAC outlier fraction 33.3% exceeds threshold 30.0%.
WARNING  FitResult.success = False

Cause

With a small station set (< 10), even two outlier stations exceed the default 30 % outlier fraction limit.

Fix

Switch to IRLS:

rringg … -fi least_squares

IRLS handles outliers via continuous downweighting (Huber/Tukey) without a hard outlier-fraction limit, making it more robust with sparse networks.

Poor correction despite good RMSE¶

Symptom

The metrics look acceptable but the corrected raster still shows a visible ramp or gradient.

Likely causes

A contaminated station dominates the fit (e.g., a station on a subsiding building, near a fault, or with a short record that misses the deformation). Use --remove_stations to exclude it.
The spatial distribution of stations is too uneven (most stations clustered in one corner of the scene). The Kriging fallback should activate automatically; check the log for "Poor spatial distribution … Kriging grid fallback may be needed". If kriging still fails (too few stations to fit a variogram), supply a directory of local time-series files using --local_timeseries /path/to/dir (see Running RRINGG for the accepted file format). This replaces EPOS/NGL entirely for that run.
The bias is not planar (e.g., strong topographic phase residuals or ionospheric gradients that follow a non-linear pattern). RRINGG corrects for affine planes only.

Correction produces NaN or extreme values in the output raster¶

Cause

The plane parameters a, b, c were estimated from stations far outside the raster footprint, producing extrapolation artefacts at raster edges.

Fix

Reduce the bounding-box scale factor:

rringg … -sc 1.0   # no expansion

Or manually exclude edge stations with --remove_stations.

Local time-series issues (`--local_timeseries`)¶

Velocity appears biased or unrealistic¶

Symptom

The velocity estimated by MIDAS for a local station is visibly different from expected values, or residuals at that station are large after correction.

Likely cause: uncorrected antenna or receiver change

RRINGG only passes seismic steps (USGS catalogue, M≥5) to MIDAS. Antenna and receiver changes in the .pos file are not corrected automatically. A single large jump can bias the MIDAS estimate.

Fix — correction mode

Create a companion .steps file alongside the .pos file (same stem, same directory) with one equipment-change date per line:

# BRST00FRA.steps
2014-10-15
2019-03-28

RRINGG reads it automatically and passes the dates to MIDAS. Accepted formats: YYYY-MM-DD or YYYYMMDD.

Fix — referencing mode

Pre-place the IGS sitelog for the station in:

{output_directory}/INPUT_FILES/INPUT_STN_METADATA/logfiles/

RRINGG checks this directory before attempting to download from M3G.

See Antenna jumps and sitelogs for the full description of all available strategies.

Station silently skipped¶

Symptom

A .pos file exists in the directory but its station does not appear in the processing log or output figures.

Possible causes

Cause	Fix
File name has wrong length	Rename to exactly 4 or 9 characters (e.g. `BRST.pos`).
Fewer than ~730 epochs in the series	MIDAS requires ≥ 2 years of data. The file is renamed to `.bad` and skipped. Provide a longer series.
`NEU Reference` header line missing	Add the line — RRINGG cannot determine the station coordinates without it (see IV — Local GNSS Time-Series Directory).
Station outside InSAR bounding box	Check that the coordinates in `NEU Reference` are correct. Adjust `--scale` to widen the search area if needed.
MIDAS returns `None` (degenerate series)	The `.pos` file is renamed to `.bad`. Inspect the file for zero-variance epochs, duplicate dates, or extreme outliers.

Referencing mode issues¶

`reference_date` not found in the time series¶

Symptom

ValueError: reference_date 2020-01-01 is not in the acquisition list.

Fix

The reference date must exactly match one of the acquisition dates listed in the .meta sidecar of the time-series raster. Check the dates with:

python -c "
import json
m = json.load(open('your_file.meta'))
print(m['List_of_dates'])
"

Then pass an exact match to --reference_date.

Windows-specific issues¶

`source activate base` not recognised¶

In Git Bash on Windows, use:

conda activate base
# if the above also fails, run:
source ~/miniconda3/etc/profile.d/conda.sh
conda activate base

Path separators in file arguments¶

Git Bash accepts both / and \ in paths. If a path contains spaces, wrap it in double quotes:

rringg -vr "C:/My Data/velocity.tiff" …

Getting more diagnostic information¶

Enable DEBUG logging to see the full processing trace:

rringg … --log-level DEBUG --log-file debug.log

The log file contains all INFO and DEBUG messages regardless of the console verbosity setting. Share this file when reporting a bug.

Report a bug: GitLab issue tracker

Troubleshooting¶

Installation issues¶

GDAL version conflict¶

`rringg: command not found`¶

GNSS data issues¶

No stations found in the InSAR footprint¶

Network timeout or empty API response¶

Processing issues¶

R² is very low — is the correction wrong?¶

RANSAC fails with few stations¶

Poor correction despite good RMSE¶

Correction produces NaN or extreme values in the output raster¶

Local time-series issues (`--local_timeseries`)¶

Velocity appears biased or unrealistic¶

Station silently skipped¶

Referencing mode issues¶

`reference_date` not found in the time series¶

Windows-specific issues¶

`source activate base` not recognised¶

Path separators in file arguments¶

Getting more diagnostic information¶

rringg

Navigation

Related Topics

Troubleshooting¶

Installation issues¶

GDAL version conflict¶

rringg: command not found¶

GNSS data issues¶

No stations found in the InSAR footprint¶

Network timeout or empty API response¶

Processing issues¶

R² is very low — is the correction wrong?¶

RANSAC fails with few stations¶

Poor correction despite good RMSE¶

Correction produces NaN or extreme values in the output raster¶

Local time-series issues (--local_timeseries)¶

Velocity appears biased or unrealistic¶

Station silently skipped¶

Referencing mode issues¶

reference_date not found in the time series¶

Windows-specific issues¶

source activate base not recognised¶

Path separators in file arguments¶

Getting more diagnostic information¶

`rringg: command not found`¶

Local time-series issues (`--local_timeseries`)¶

`reference_date` not found in the time series¶

`source activate base` not recognised¶