Input Data¶

Overview¶

RRINGG integrates two complementary sources of geodetic data to produce corrected surface velocity fields. InSAR satellite measurements provide dense spatial coverage, while GNSS ground observations supply an absolute reference frame and long-wavelength constraints.

Two input categories are defined:

InSAR data products (required)

Dense, spatially continuous Line-of-Sight (LOS) measurements, including surface velocity fields and other products derived from InSAR processing. Three sources are supported:

FLATSIM Products — GeoTIFF products from the CNES/FormaTerre platform
EPOS TCS DTSLOS — CSV time series from the EPOS Thematic Core Service
Other InSAR Sources — any third-party dataset converted to the required format

GNSS station velocities (required)

Ground-based geodetic velocities used to correct InSAR velocity fields. Two usage modes are available, depending on whether a user-supplied text file is provided:

Primary sources — queried automatically when no user text file is provided (one defined in the parameter file):

EPOS GNSS Products — JSON velocities served via REST API
NGL MIDAS Velocities — weekly MIDAS velocity files from the Nevada Geodetic Laboratory

Standalone sources — when provided, replace the primary source entirely; no external data retrieval is performed:

User-Supplied Text File — pre-computed velocities in the RRINGG standard plain text format
Local GNSS Time-Series Directory — raw .pos files; velocities computed automatically via MIDAS

The table below summarises all supported sources and their roles:

Supported Input Sources¶
Category	Source	Format	Status	Description
InSAR	FLATSIM	GeoTIFF + `.meta`	Required	Mean LOS velocity raster and ancillary products from the CNES/FormaTerre platform
InSAR	EPOS TCS DTSLOS	CSV + metadata	Required	LOS displacement time series from the EPOS Thematic Core Service
InSAR	Other sources	GeoTIFF + `.meta`	Required (if used)	Any third-party InSAR product complying with the conventions described below
GNSS	EPOS GNSS	JSON (REST API)	Primary	Station velocities served via the EPOS GNSS Products web service
GNSS	NGL MIDAS	Plain text (fixed-width)	Primary	MIDAS velocity fields distributed weekly by the Nevada Geodetic Laboratory
GNSS	User text file	Plain text (ASCII)	Standalone	Pre-computed velocities; replaces the primary source entirely when provided
GNSS	Local time-series directory	PBO `.pos` files	Standalone	Raw GNSS position time series; velocities computed via MIDAS; replaces the primary source entirely when provided

Note

For a hands-on introduction using sample datasets, refer to the Quick Start.

Part I — InSAR Input Data¶

RRINGG ingests InSAR products that describe surface displacement in the satellite Line-of-Sight (LOS) direction. At minimum, each dataset must provide:

A mean LOS velocity raster (mm/yr or cm/yr, explicitly declared).
LOS unit-vector components (cosines in ENU or NEU convention).
Acquisition date list matching the band order of any time-series raster.

Two official providers are natively supported (FLATSIM and EPOS TCS). Third-party data must be converted to the same format before use (see Other Sources).

I — FLATSIM Products¶

1. Data Description¶

The FLATSIM platform, operated by CNES/FormaTerre, distributes multi-temporal InSAR products derived from Sentinel-1 acquisitions. For a complete product reference consult the official FLATSIM documentation.

Required products

Product name	Format	Description
`MVLOS_geo`	GeoTIFF (single-band)	Mean LOS velocity field. Data type: `float32` or `float64`. Units must be declared in metadata (e.g. `cm/yr`).
`CosNEU_geo` / `CosENU_geo`	GeoTIFF (3-band)	LOS unit-vector map. Bands correspond to (vN, vE, vU) or (vE, vN, vU) depending on convention declared in metadata.
Displacement time series	GeoTIFF (multi-band)	Per-pixel LOS displacement values. Band order must match `List_of_dates` in metadata.
`lut_radar` / `lut_ground`	GeoTIFF	Look-up tables for radar ↔ ground geometry conversion.
Station / velocity files	Plain text (ASCII)	Optional GNSS time series or velocity datasets for fitting/validation.

General raster requirements

Format: GeoTIFF
Recommended compression: LZW
Preferred data type: float32
Explicit NoData value (e.g. 999.0); do not mix NaN and sentinel values.

Mandatory metadata fields

Each product must include metadata either embedded in the GeoTIFF tags or as a side-car .meta file. Minimal schema:

DDSS_ID: string               # e.g. LOS_DISPLACEMENT_TIMESERIES, MEAN_LOS_VELOCITY
Title: string                 # e.g. Time_Serie, velocity
User_ID: string               # e.g. flatsim, CNRIREA
List_of_dates: [YYYY-MM-DDTHH:MM:SSZ]   # required for time series; must match band order
Value_unit: string            # e.g. cm/yr, rad/year
Software_version: string      # e.g. NSBAS:v2.2.10
Applied_filter: string        # e.g. Goldstein_0.50
Applied_corrections: string   # e.g. ERAW:ERA5, No_Corrections
Service_used_for_generation: string
Geographic_CS_type_code: string  # e.g. EPSG4326, RADAR_GEOMETRY
License: string or URI        # usage restrictions
Used_DEM: string              # e.g. SRTM_1arcsec
Band_description: string      # band-by-band description
Product_url: string           # download URL
Preview_url: string           # preview image URL

2. Data Access¶

Go to the FLATSIM portal.
Scroll down to the zone map and click on your region of interest (e.g. Balkans).
Log in or create an account (ORCID authentication recommended).
In the left panel, use Parameters to filter products (e.g. orbitDirection=DESCENDING, relativeOrbitNumber=007).
Download products of types AUXILIARYDATA and TIMESERIE (total size ~ 20 GB).

Illustration of the download process from the FLATSIM portal

Note

If the download button is greyed out, the dataset may be under embargo. A “Restricted Access” banner will appear. Acknowledge the terms of use and, if necessary, contact the data provider to request access.

Full product descriptions are available in the FLATSIM documentation.

II — EPOS TCS DTSLOS¶

1. Data Description¶

The EPOS Thematic Core Service for Satellite Data distributes InSAR time series in CSV format (product type DTSLOS — Displacement Time Series LOS). These files require preprocessing before being ingested by RRINGG. For the authoritative product specification see the EPOS product documentation.

Products

Product name	Format	Description
InSAR DTSLOS	CSV	Displacement time series, mean velocity, topography, LOS unit vectors, spatial coherence. Data type: `float32` or `float64`.
Metadata file	Plain text	Similar in structure to FLATSIM metadata. Must include acquisition dates in chronological order.

CSV field specification

Field	Type	Unit	Description
`ID`	string	—	Unique point identifier
`Lat`	float	decimal degrees	Latitude of measurement point
`Lon`	float	decimal degrees	Longitude of measurement point
`Topo`	float	m	Topographic elevation
`Vel`	float	cm/yr	Mean LOS velocity
`Coer`	float	unitless	Spatial coherence
`cosN`, `cosE`, `cosU`	float	unitless	LOS unit-vector components (NEU convention)
`TS`	float array	cm	Displacement time series (one value per acquisition date)

Each row of the CSV represents a single measurement point. The structure is illustrated below:

Mandatory metadata example

DDSS_ID: MEAN_LOS_VELOCITY
Title: Time_Serie
User_ID: CNRIREA
List_of_dates: [2015-05-07T12:25:18Z, 2015-05-31T12:25:20Z, ...]
Value_unit: rad/year
Software_version: NSBAS:v2.2.10
Applied_filter: sliding window average
Applied_corrections: ERAW:ERA5
Service_used_for_generation: WP12-DDSS-024 GDM-SAR Sentinel-1
Geographic_CS_type_code: EPSG4326
License: https://creativecommons.org/licenses/by-nc/4.0/
Used_DEM: SRTM V3, 1 arcsec
Band_description: LOS velocity [rad/yr], Radar illumination on DEM
Product_url: <download URL>
Preview_url: <preview URL>

2. Data Access¶

Visit the EPOS ICS portal.
Navigate to Data → Satellite Data → LOS Displacement Time Series.
On the map, select a region of interest.
In the popup, scroll down and click Product download (e.g. DTSLOS_CNRIREA_20160714_20231030_ZII6).
Extract the downloaded archive to access the CSV and metadata files.

Illustration of the download process from the EPOS ICS portal

III — Other InSAR Sources¶

Data from any other provider may be used only if the datasets are converted to the formats and conventions described in this section. This chapter provides a step-by-step methodology for preparing third-party InSAR data for use in RRINGG.

1. Required Products and Minimum Content¶

Regardless of origin, the following products must be present:

Product	RRINGG code	Minimum content
Mean LOS velocity	`MVLOS`	Single-band GeoTIFF; units in cm/yr or mm/yr declared in metadata
LOS unit vectors	`Cos[COORD]`	3-band GeoTIFF (ENU or NEU); explicit convention in metadata
Displacement time series	`DTS`	Multi-band GeoTIFF; band order = chronological acquisition dates
Look-up tables (if radar geometry)	`LUT`	GeoTIFF arrays for radar ↔ ground coordinate mapping
Metadata	`.meta`	Side-car YAML/text file; see mandatory fields in I — FLATSIM Products

2. File Naming Conventions¶

Adopt the following naming patterns to ensure consistent processing:

[AGENCY]_DTS_[GEOMETRY]_[LOOKS]rlks.tiff
[AGENCY]_DTS_[GEOMETRY]_[LOOKS]rlks.meta
[AGENCY]_MVLOS_[GEOMETRY]_[LOOKS]rlks.tiff
[AGENCY]_MVLOS_[GEOMETRY]_[LOOKS]rlks.meta
[AGENCY]_Cos[COORD]_[GEOMETRY]_[LOOKS]rlks.tiff
[AGENCY]_LUT_[GEOMETRY]_[LOOKS]rlks.tiff

Component glossary

Token	Meaning
`AGENCY`	Data provider code (e.g. `CNES`, `CNRIREA`, `DLR`)
`DTS`	LOS displacement time series
`MVLOS`	Mean LOS velocity raster
`Cos[COORD]`	LOS vector raster; `COORD` is either `ENU` or `NEU`
`LUT`	Look-up table for geometry conversion
`GEOMETRY`	`geo` (ground/geographic, lat–lon) or `radar` (radar geometry)
`LOOKS`	Multi-looking factor in azimuth (e.g. `10rlks` = averaged over 10 range looks)

Naming examples

File name	Product type	Description
`CNES_DTS_geo_10rlks.tiff`	Time series	LOS displacement raster, ground geometry, 10-look average
`CNES_MVLOS_geo_10rlks.meta`	Metadata	Side-car for mean velocity raster, ground geometry
`CNRIREA_CosENU_radar_5rlks.tiff`	LOS vectors	ENU LOS vector raster in radar geometry, 5-look average
`CNRIREA_LUT_radar_20rlks.tiff`	LUT	Geometry conversion look-up table, radar geometry, 20-look average

3. Conventions and Technical Requirements¶

LOS vectors

Must be unit vectors (‖v‖ = 1).
Allowed conventions:
- NEU — (North, East, Up)
- ENU — (East, North, Up)
The chosen convention must be explicitly declared in the .meta file under the field Band_description.

Time-series band ordering

Bands must be in strictly increasing chronological order.
The List_of_dates field in metadata must contain exactly one ISO-8601 timestamp per band (format YYYY-MM-DDTHH:MM:SSZ).

Coordinate reference system

Ground-geometry products must be projected in EPSG:4326 (WGS84 geographic).
Radar-geometry products must declare RADAR_GEOMETRY in the Geographic_CS_type_code metadata field.

NoData handling

Declare a single, explicit NoData sentinel (e.g. 999.0 or -9999.0).
Do not mix IEEE NaN and sentinel values within the same file.

4. Preparation Checklist¶

Before integrating third-party data into RRINGG, verify the following:

[ ] Mean velocity raster (MVLOS) exists and units are declared.
[ ] LOS vector raster (Cos[COORD]) is a unit vector with explicit ENU/NEU convention.
[ ] Time-series bands are in chronological order and List_of_dates matches band count.
[ ] All .meta files are present and contain the mandatory fields listed in I — FLATSIM Products.
[ ] Naming conventions follow the [AGENCY]_[PRODUCT]_[GEOMETRY]_[LOOKS]rlks pattern.
[ ] NoData value is consistent and explicitly declared.
[ ] Ground-geometry products use EPSG:4326.

Part II — GNSS Input Data¶

GNSS velocity data are used to correct InSAR products for orbital ramp, long-wavelength biases, or reference-frame offsets. Two usage modes are available depending on whether a user-supplied text file is provided:

Primary mode — a source is defined in the parameter file (EPOS or NGL) and queried automatically to retrieve station velocities.
Standalone mode — a user-supplied plain text file is provided; it replaces the primary source entirely and no external data retrieval is performed.

GNSS Source Comparison¶
Source	Format	Access	Reference frame	Update frequency	Usage mode
EPOS GNSS	JSON (REST API)	Web service	geodetic (IGb14, IGS20 …)	Annual release	Primary
NGL MIDAS	Plain text (fixed-width)	Bulk download	geodetic + plate frames	Weekly	Primary
User text file	Plain text (ASCII)	User-supplied	User-defined	User-defined	Standalone

I — EPOS GNSS Products¶

1. Data Description¶

The EPOS GNSS Products web service distributes station velocities computed with the MIDAS algorithm by multiple analysis centres. Data are served via a REST API in JSON format.

REST API endpoint

https://gnssproducts.epos.ubi.pt/GlassFramework/webresources/products/velocities/{STATION}/{CENTRE}/enu/json

where {STATION} is the 9-character station identifier (e.g. CASC00PRT) and {CENTRE} is the analysis-centre code (e.g. UGA-CNRS).

JSON structure

{
  "Title": "EPOS-GNSS Velocities",
  "AnalysisCentre": "UGA-CNRS",
  "DOI": "10.17178/GNSS.products.EPOS.2019",
  "ReferenceFrame": "IGb14",
  "Software": "MIDAS",
  "ReleaseVersion": "2024.1",
  "Method_URL": "https://gnssproducts.epos.ubi.pt/methods/UGA_TS.pdf",
  "JSON_Version": "1.0",
  "Unit": "meters",
  "Station_metadata": {
    "StationID": "CASC00PRT",
    "isEPOS": true,
    "MOID": "https://gnss-metadata.eu/MOID/CASC00PRT",
    "DGW": "https://gnssdata-epos.oca.eu/#/metadata/marker=CASC00PRT"
  },
  "results": [
    {
      "ref_epoch": "2000-01-01 00:00:00",
      "ref_nlat": "38.69341",
      "ref_elong": "-9.41852",
      "ref_up": "76.01",
      "dn/dt": "0.01691",
      "de/dt": "0.01808",
      "du/dt": "-0.00025",
      "snd": "0.00013",
      "sed": "0.00012",
      "sud": "0.00039",
      "rne": "-0.03123",
      "rnu": "-0.01356",
      "reu": "0.01375",
      "first_epoch": "2000-01-01 00:00:00",
      "last_epoch":  "2024-03-21 00:00:00"
    }
  ]
}

Field reference

Field	Unit	Description
`ref_nlat`	decimal degrees	Station latitude
`ref_elong`	decimal degrees	Station longitude
`ref_up`	m	Ellipsoidal height at reference epoch
`dn/dt`	m/yr	North velocity component
`de/dt`	m/yr	East velocity component
`du/dt`	m/yr	Vertical velocity component
`snd`	m/yr	North velocity uncertainty (1σ)
`sed`	m/yr	East velocity uncertainty (1σ)
`sud`	m/yr	Vertical velocity uncertainty (1σ)
`rne`, `rnu`, `reu`	unitless	Correlation coefficients between velocity components
`first_epoch` / `last_epoch`	YYYY-MM-DD	Time span of the contributing time series

Warning

All velocities in the EPOS JSON response are expressed in metres per year (m/yr). RRINGG converts them to mm/yr internally, but users working with raw JSON must be aware of this difference.

2. Data Access¶

EPOS GNSS velocities can be accessed:

Interactively via the EPOS GNSS portal, where stations can be browsed on a map and results downloaded per station.
Programmatically by querying the REST API endpoint directly, substituting the desired station code and analysis centre.

Note

Time-series referencing mode — In addition to station velocities, RRINGG automatically downloads the daily position time series (tenv3 format) for each EPOS station when running in referencing mode. These files are cached locally in cache/ and reused on subsequent runs. The tenv3 format encodes daily ENU positions (East, North, Up in metres) from which RRINGG fits a trajectory model (linear trend + annual + semi-annual terms) to predict absolute displacements at each InSAR acquisition date. No additional configuration is required — the download is triggered automatically when -po referencing is specified.

II — NGL MIDAS Velocities¶

1. Data Description¶

The Nevada Geodetic Laboratory (NGL) distributes global GNSS station velocities computed with the MIDAS algorithm (Blewitt et al., 2016). Files are updated weekly from the NGL GPS time series.

Note

Citation requirement — when using NGL MIDAS velocities in publications, cite: Blewitt, G., C. Kreemer, W.C. Hammond, and J. Gazeaux (2016). MIDAS robust trend estimator for accurate GPS station velocities without step detection, Journal of Geophysical Research, 121, doi:10.1002/2015JB012552.

File format: fixed-width plain text

The format description is available at https://geodesy.unr.edu/velocities/midas.readme.txt. Each row corresponds to one station; columns are space-separated.

Column(s)	Field	Unit	Description
1	Station ID	—	4-character station code
2	MIDAS version	—	Algorithm version label
3	First epoch	decimal year	Start of contributing time series
4	Last epoch	decimal year	End of contributing time series
5	Duration	yr	Length of time series
6	Total epochs	—	Total number of data epochs (used or not)
7	Good epochs	—	Epochs used in at least one velocity sample
8	Velocity pairs	—	Number of sample pairs used to estimate the MIDAS velocity
9–11	ve, vn, vu	m/yr	East, North, Up mode velocities
12–14	se, sn, su	m/yr	East, North, Up velocity uncertainties
15–17	Offset E, N, U	m	East, North, Up offset at first epoch
18–20	Outlier fraction E, N, U	—	Fraction of outlier values per component
21–23	Std dev E, N, U	m/yr	Standard deviation of velocity sample pairs
24	Number of steps	—	Steps assumed (from NGL steps database)
25	Latitude	decimal degrees	Station latitude
26	Longitude	decimal degrees	Station longitude
27	Height	m	Ellipsoidal height

Warning

NGL MIDAS velocities are expressed in metres per year (m/yr). RRINGG converts them to mm/yr internally.

Available reference frames

Velocities are distributed in multiple reference frames identified by a two-letter code appended to the file name:

Code	Reference frame / tectonic plate
`IGS14` / `IGS20`	IGS global reference frame (2014 or 2020 realisation)
`EU`	Eurasian plate
`NA`	North American plate
`AF`	African plate
`AU`	Australian plate
`SA`	South American plate
(others)	AN, AR, BU, CA, CO, IN, MA, NB, NZ, OK, ON, PA, PM, PS, SB, SC, SL, SO, SU, WL

2. Data Access¶

Velocity files are available for bulk download at https://geodesy.unr.edu/velocities/. Select the reference frame corresponding to your study region and download the relevant .vel file.

III — User-Supplied Text File¶

1. Purpose and Scope¶

This format is intended for users who:

Hold pre-processed GNSS velocities from any source not covered above.
Wish to use velocities from a custom processing or campaign-mode survey.
Need full control over the station dataset used for InSAR correction.

When a user-supplied plain text file is provided, it acts as a standalone source: it entirely replaces the primary source defined in the parameter file, and RRINGG performs no external data retrieval. Only the stations listed in the text file are used for the correction.

Important

--velocity_file is only compatible with correction mode (-po correction). It provides pre-computed velocities but no raw time series, which referencing mode requires to build trajectory models. For referencing, use --local_timeseries instead (see IV — Local GNSS Time-Series Directory).

The plain text format described here is also the canonical interchange format within RRINGG: EPOS and NGL data are automatically converted to this format during ingestion.

2. File Format Specification¶

The file is a plain ASCII text file with space-separated columns, one station per row. Comment lines starting with # are ignored.

General format

marker centre frame latitude longitude height ve vn vu se sn su [start] [end] [gnss_days]

Fields in square brackets are optional.

Field reference

#	Field	Type	Unit	Description
1	`marker`	string	—	Station code. 4-character (e.g. `BRST`) or 9-character IERS format (e.g. `BRST00FRA`). Must start with 4 uppercase letters; characters 5–9 are alphanumeric (0–9, A–Z).
2	`centre`	string	—	Processing centre code (e.g. `SGO-EPND`, `UGA-CNRS`). Use `unknown` if not known.
3	`frame`	string	—	Reference frame identifier. Common values: `ITRF2014`, `ITRF2020`, `IGS14`, `IGS20`, `ETRF2000`, `NAD83`. Use `unknown` if not applicable.
4	`latitude`	float	decimal degrees	Station latitude. Range: −90 to +90. Recommended precision: 6 decimal places.
5	`longitude`	float	decimal degrees	Station longitude. Range: −180 to +180. Recommended precision: 6 decimal places.
6	`height`	float	m	Ellipsoidal height. Valid range: −500 to +9000 m.
7	`ve`	float	mm/yr	East velocity component. Valid range: ±1000 mm/yr.
8	`vn`	float	mm/yr	North velocity component. Valid range: ±1000 mm/yr.
9	`vu`	float	mm/yr	Vertical velocity component. Valid range: ±1000 mm/yr.
10	`se`	float	mm/yr	East velocity uncertainty (1σ). Valid range: 0–100 mm.
11	`sn`	float	mm/yr	North velocity uncertainty (1σ). Valid range: 0–100 mm.
12	`su`	float	mm/yr	Vertical velocity uncertainty (1σ). Valid range: 0–100 mm.
13	`start`	date	YYYY-MM-DD	(Optional) Start date of the time series used to compute the velocity. Required: `start` < `end`.
14	`end`	date	YYYY-MM-DD	(Optional) End date of the time series used to compute the velocity.
15	`gnss_days`	integer	—	(Optional) Number of GNSS observation days contributing to the velocity estimate.

Important

The gnss_days field directly controls the Fisher-information prior weight assigned to each station:

\[w_i \propto \frac{N_i}{\sigma_i^2}\]

where \(N_i\) is gnss_days and \(\sigma_i\) is the projected LOS uncertainty. Omitting gnss_days (or setting it to unknown) causes RRINGG to assign equal coverage weight to all stations, regardless of time-series length — potentially over-weighting short or unreliable velocity estimates. Always provide this field when known.

Units summary

Quantity	Unit
Velocities (ve, vn, vu)	mm/yr
Uncertainties (se, sn, su)	mm/yr
Height	m
Geographic coordinates	decimal degrees

Special values

unknown — use when the value exists but is not known.
default — use system default.
Empty field — the field is ignored by RRINGG.

3. Format Example¶

# marker     centre    frame    latitude   longitude   height   ve     vn     vu    se    sn    su    start       end         gnss_days
ALGO00CAN    SGO-EPND  IGS14    50.960300  -98.513400   220.5  -15.2   -8.7   2.1   1.2   1.1   1.3  2010-01-01  2024-12-31  5475
BRST00FRA    UGA-CNRS  IGS14    48.380600   -4.496500    65.3    1.4   12.3   0.8   0.9   0.8   1.5  2008-03-15  2023-09-30  4012
KOUR00GUF    unknown   unknown   5.252100  -52.805300   -23.1   11.9   -2.4  -0.5   1.0   1.0   1.8  unknown     unknown     unknown

4. Station Code Conventions¶

4-character format

Four uppercase letters: BRST, ALGO, KOUR.
Used for legacy datasets and files that do not require sub-daily disambiguation.

9-character IERS format

Characters 1–4: station letters (uppercase).
Characters 5–6: monument/domes number (00 to 99).
Characters 7–9: ISO 3166-1 alpha-3 country code (e.g. FRA, CAN, PRT).
Examples: BRST00FRA, ALGO00CAN, CASC00PRT.

5. Reference Frame and Processing-Centre Identifiers¶

Common reference frames

Identifier	Description
`ITRF2014`	International Terrestrial Reference Frame 2014
`ITRF2020`	International Terrestrial Reference Frame 2020
`IGS14`	IGS realisation of ITRF2014
`IGS20`	IGS realisation of ITRF2020
`ETRF2000`	European Terrestrial Reference Frame 2000
`NAD83`	North American Datum 1983
`unknown`	Frame is not known or not applicable

Common processing centres

Code	Full name
`SGO-EPND`	Service Géodésique de l’Observatoire de Paris — EPND
`UGA-CNRS`	Université Grenoble Alpes / CNRS
`NASA-JPL`	NASA Jet Propulsion Laboratory
`MIT`	Massachusetts Institute of Technology
`UCSD`	University of California San Diego
`CODE`	Center for Orbit Determination in Europe
`GFZ`	German Research Centre for Geosciences
`unknown`	Processing centre not known

6. Validation Rules¶

Before supplying the file to RRINGG, verify that:

[ ] Latitude ∈ [−90, +90] and longitude ∈ [−180, +180].
[ ] Height ∈ [−500, +9000] m.
[ ] Velocities ∈ [−1000, +1000] mm/yr.
[ ] Uncertainties ∈ [0, 100] mm and strictly positive.
[ ] Dates follow YYYY-MM-DD and start < end when both are provided.
[ ] Marker codes start with 4 uppercase letters; 9-character codes are valid.
[ ] No mixing of units (all velocities must be in mm/yr).

IV — Local GNSS Time-Series Directory¶

1. Purpose and Scope¶

This source mode is intended for users who:

Hold raw GNSS position time series from a regional network (RGP, EUREF, campaign surveys) not covered by EPOS or NGL.
Need to process in a fully offline environment.
Want RRINGG to compute velocities automatically rather than providing pre-computed values.
Are running in referencing mode (-po referencing) and need an offline GNSS source.

When --local_timeseries is provided, the directory is used as the exclusive GNSS source — no data is downloaded from EPOS or NGL. Velocities are derived via the MIDAS algorithm (Median Interannual Difference Adjusted for Skewness), which is robust to offsets and seasonal signals.

This is the only offline GNSS source compatible with referencing mode. The raw .pos files are used directly by InsarReferencer to build GNSS trajectory models — which requires the full time series, not just pre-computed velocities. --velocity_file cannot fulfil this role.

Antenna jumps and sitelogs¶

GNSS position time series contain discontinuities caused by antenna or receiver changes that must be handled before computing velocities or building trajectory models. RRINGG’s behaviour depends on whether the station is registered in the IGS/M3G sitelog registry:

Station type	Correction mode (MIDAS)	Referencing mode (tsanalysis)
Standard station registered in M3G	Seismic steps only (USGS M≥5)	Sitelog auto-downloaded from M3G → `staDB` ✓
Local / campaign station not in M3G	Seismic steps only	No sitelog → no offset correction ✗
Any station with `.steps` companion file	Seismic + equipment steps ✓	`.steps` → `staDB` via itsa ✓

For referencing mode, RRINGG applies the following priority chain to obtain equipment-change offset information before running tsanalysis:

Pre-placed .sta_db file  ← highest priority
Local IGS sitelog (.log)
Download from M3G (internet required, known stations only)
NGL steps.txt (NGL source only, internet required)
.steps companion file    ← fallback for unknown stations

If none of the above is available, tsanalysis runs without offset correction. Antenna jumps remain in the trajectory model and may produce residuals.

Four strategies are available depending on the situation:

Strategy 1 — Companion ``.steps`` file (recommended for unknown stations)

Place a file with the same name as the .pos file but with a .steps extension in the same directory. RRINGG reads it automatically and merges the listed dates with the seismic steps before passing them to MIDAS:

my_stations/
├── BRST00FRA.pos      # time series
└── BRST00FRA.steps    # antenna/receiver change dates

Format of the .steps file: one date per line, YYYY-MM-DD or YYYYMMDD. Comments with # are ignored.

# BRST00FRA — equipment change log
2014-10-15   # receiver swap
2019-03-28   # antenna change
2021-11-02   # receiver swap

This covers both earthquake-driven steps (added automatically from the USGS catalogue) and equipment steps (from the .steps file).

Strategy 2a — Pre-placed IGS sitelog for referencing mode

For referencing mode, InsarReferencer looks for a local IGS sitelog (.log) before attempting to download from M3G. Pre-place the sitelog here before running RRINGG:

{output_directory}/
└── INPUT_FILES/
    └── INPUT_STN_METADATA/
        └── logfiles/
            └── brst00fra00.log   # 9-char lower-case + any suffix

The file must be in IGS sitelog format (standard .log exported from M3G or the station operator). When found, it is converted to a staDB file by itsa and all antenna offsets are corrected before trajectory modelling.

Strategy 2b — Pre-placed ``.sta_db`` for referencing mode

If you already have a staDB file (generated externally by itsa or from a previous run), place it directly in the staDB directory. RRINGG checks for it first — if present, all other mechanisms are skipped:

{output_directory}/
└── INPUT_FILES/
    └── INPUT_STN_METADATA/
        └── staDB/
            └── brst.sta_db   # 4-char lower-case, no country code

This is the highest-priority mechanism and the fastest option when the staDB is already available.

Strategy 3 — Pre-correct the time series

Apply antenna phase-centre corrections and remove equipment-change offsets using your GNSS processing software (GipsyX, Bernese, GINS, etc.) before writing the .pos file. The resulting series should be offset-free; no .steps file is then required.

Strategy 4 — Use ``–velocity_file`` (correction mode only)

If velocities from a corrected solution are already available (e.g., from a regional analysis centre), bypass MIDAS entirely: use III — User-Supplied Text File (--velocity_file).

Note

MIDAS is inherently robust to isolated unmodelled offsets because it uses the median of all yearly displacement pairs. A single antenna change in a 5-year series corrupts at most 20 % of pairs and is unlikely to bias the velocity significantly. For series shorter than 3 years or with multiple equipment changes, providing a .steps file or pre-correcting is strongly recommended.

If velocities are already known and you are running in correction mode only, use III — User-Supplied Text File instead (--velocity_file).

2. Directory Layout and File Naming¶

The directory must contain one file per station. Only files whose name (without extension) is exactly 4 or 9 alphanumeric characters are recognised; all others are silently ignored.

my_stations/
├── BRST.pos          # 4-character code → auto-extended to BRST00FRA
├── BRST00FRA.pos     # 9-character IGS code (preferred)
├── LROC.pos
└── AJAC00FRA.pos

Note

4-character codes are automatically extended to the 9-character IGS format using the ISO-3166-1 alpha-3 country code inferred from the station coordinates (e.g. BRST → BRST00FRA).

3. File Format: PBO Position Time Series¶

RRINGG reads the PBO (Plate Boundary Observatory) position time series format, which is the standard output of GipsyX and compatible software. .txt files in raw GipsyX format are automatically converted to .pos before reading.

Header block

The file begins with a free-form header. RRINGG extracts the following lines (all others are ignored):

AnalysisCentre  UGA-CNRS
Software        GipsyX-1.4
First Epoch     20100101 000000
Last Epoch      20231231 000000
PBO Station Position  IGS14
XYZ Reference    Pos     4201544.123  -332190.456  4779006.789
NEU Reference    Pos      45.188800   -4.496500    65.000

Header line	What RRINGG reads
`AnalysisCentre`	Processing centre label (stored in metadata)
`First Epoch`	Series start date as `YYYYMMDD`, 4th token
`Last Epoch`	Series end date as `YYYYMMDD`, 4th token
`PBO Station Position`	Reference frame (e.g. `IGS14`), last token
`XYZ Reference`	ECEF reference position X Y Z [m], tokens 4–6
`NEU Reference`	Latitude Longitude Height [deg / deg / m], tokens 4–6

Important

NEU Reference is mandatory — it provides the station latitude and longitude used for spatial filtering and LOS projection. Files missing this line are skipped.

Column header line

The data block starts immediately after the line beginning with *YYYYMMDD, which serves as the column header:

*YYYYMMDD HHmmss.s  MJD  X(m)  Y(m)  Z(m)  Sx(m)  Sy(m)  Sz(m)  Rxy  Rxz  Ryz  N(m)  E(m)  U(m)  dN(m)  dE(m)  dU(m)  Sn(m)  Se(m)  Su(m)  Rne  Reu  Rnu  tag

Data columns

Each data line has exactly 25 whitespace-separated fields:

Col	Name	Unit	Description
1	`*YYYYMMDD`	—	Date as an 8-digit integer (e.g. `20150601`)
2	`HHmmss.s`	—	Time of day; `000000.0` for daily solutions
3	`MJD`	days	Modified Julian Date (float)
4–6	`X` `Y` `Z`	m	ECEF Cartesian coordinates
7–9	`Sx` `Sy` `Sz`	m	1σ formal uncertainties on X, Y, Z
10–12	`Rxy` `Rxz` `Ryz`	—	Correlation coefficients between XYZ components
13–15	`N` `E` `U`	m	Absolute North / East / Up coordinates
16–18	`dN` `dE` `dU`	m	Displacements relative to the reference position; these are the columns fed to MIDAS
19–21	`Sn` `Se` `Su`	m	1σ uncertainties on dN, dE, dU (must be > 0)
22–24	`Rne` `Reu` `Rnu`	—	Correlation coefficients between NEU components; set to `0.0` if unknown
25	tag	—	Free-text label (e.g. `itsa`, `manual`); ignored

4. Minimal example¶

A syntactically valid file for a station at lat = 45.1888°, lon = −4.4965° with daily solutions:

AnalysisCentre  LOCAL
Software        manual
First Epoch     20100101 000000
Last Epoch      20231231 000000
PBO Station Position  IGS14
XYZ Reference    Pos     4201544.123  -332190.456  4779006.789
NEU Reference    Pos      45.188800   -4.496500    65.000
*YYYYMMDD HHmmss.s    MJD     X(m)          Y(m)          Z(m)      Sx(m)  Sy(m)  Sz(m)  Rxy  Rxz  Ryz     N(m)         E(m)        U(m)    dN(m)   dE(m)   dU(m)  Sn(m)  Se(m)  Su(m)  Rne  Reu  Rnu
20100101 000000.0 55197.0  4201544.1230  -332190.4560  4779006.7890  0.003  0.003  0.006  0.0  0.0  0.0  5765813.230  -332190.456  65.000  0.0000  0.0000  0.0000  0.003  0.003  0.006  0.0  0.0  0.0 manual
20100102 000000.0 55198.0  4201544.1235  -332190.4558  4779006.7895  0.003  0.003  0.006  0.0  0.0  0.0  5765813.231  -332190.455  65.001  0.0002  0.0002  0.0005  0.003  0.003  0.006  0.0  0.0  0.0 manual

5. Constraints and common mistakes¶

Constraint	Detail
Minimum series length	MIDAS requires at least ~2 years of data (≈ 730 epochs for daily solutions) to compute a reliable velocity. Files with fewer epochs are rejected and renamed to `.bad`.
Uncertainties in metres	`Sn`, `Se`, `Su` must be in metres, not millimetres. Typical daily solutions: 0.002–0.005 m (2–5 mm). Zero uncertainties cause division errors and will skip the station.
Correlation columns	`Rxy`, `Rxz`, `Ryz`, `Rne`, `Reu`, `Rnu` can all be `0.0` if not available.
`NEU Reference` missing	The station is silently skipped — RRINGG cannot determine its location without this line.
Epoch count per field	Exactly 25 fields per data line. Lines with a different count fail the format check and are ignored.
File outside bounding box	Stations whose coordinates (from `NEU Reference`) fall outside the InSAR scene bounding box are filtered out after loading.

Input Data¶

Overview¶

Part I — InSAR Input Data¶

I — FLATSIM Products¶

1. Data Description¶

2. Data Access¶

II — EPOS TCS DTSLOS¶

1. Data Description¶

2. Data Access¶

III — Other InSAR Sources¶

1. Required Products and Minimum Content¶

2. File Naming Conventions¶

3. Conventions and Technical Requirements¶

4. Preparation Checklist¶

Part II — GNSS Input Data¶

I — EPOS GNSS Products¶

1. Data Description¶

2. Data Access¶

II — NGL MIDAS Velocities¶

1. Data Description¶

2. Data Access¶

III — User-Supplied Text File¶

1. Purpose and Scope¶

2. File Format Specification¶

3. Format Example¶

4. Station Code Conventions¶

5. Reference Frame and Processing-Centre Identifiers¶

6. Validation Rules¶

IV — Local GNSS Time-Series Directory¶

1. Purpose and Scope¶

Antenna jumps and sitelogs¶

2. Directory Layout and File Naming¶

3. File Format: PBO Position Time Series¶

4. Minimal example¶

5. Constraints and common mistakes¶

rringg

Navigation

Related Topics