Project Structure

The project follows a modular, package-oriented layout designed to maximise readability, testability, and maintainability. Each top-level directory has a single well-defined responsibility.

rringg/
├── cache/                    # On-disk GNSS data cache (managed by utils/cache.py)
│   ├── .cache_config.json    # Cache configuration (size limit, LRU metadata)
│   ├── time_series/          # Downloaded GNSS time series (EPOS / NGL)
│   └── metadata/             # Station metadata (coordinates, site info)
├── data/                     # Sample and reference datasets
│   ├── input/                # Raw inputs for test cases
│   └── output/               # Reference outputs for validation
├── doc/                      # Sphinx documentation (reStructuredText)
├── images/                   # Logos, diagrams, figures
├── output/                   # Generated processing products
├── src/                      # Python source code (all importable packages)
│   ├── rringg.py             # CLI entry point — thin argument-parsing wrapper
│   ├── config.py             # Frozen-dataclass configuration (replaces parameters.py)
│   ├── schema.py             # Data contracts: STATION_COLUMNS, FitResult, …
│   ├── fitting/              # Plane-fitting algorithms
│   │   ├── __init__.py       # Public API: fit_plane()
│   │   ├── irls.py           # IRLS with Huber / Tukey robust reweighting
│   │   ├── ransac.py         # RANSAC with weighted OLS re-fit
│   │   └── weighting.py      # Weight functions and prior-weight helpers
│   ├── geo/                  # Geodetic and raster geometry
│   │   ├── __init__.py
│   │   ├── geodetic.py       # LLH ↔ ECEF, projections, outlier removal
│   │   ├── raster.py         # Raster sampling, LOS projection, band interleave
│   │   └── spatial.py        # Convex/concave hull, Voronoi analysis, Kriging
│   ├── gnss/                 # GNSS data acquisition and preprocessing
│   │   ├── __init__.py
│   │   ├── base.py           # Abstract base class GNSSSource
│   │   ├── epos.py           # EPOS REST-API adapter
│   │   ├── ngl.py            # NGL tenv3 adapter
│   │   ├── csv.py            # User-supplied CSV velocity file reader
│   │   ├── factory.py        # Source selection + LOS projection of NEU velocities
│   │   └── stations.py       # Station filtering, weighting, distribution assessment
│   ├── insar/                # InSAR product ingestion
│   │   ├── __init__.py
│   │   ├── reader.py         # InsarReader: bounds, LOS vectors, raster sampling
│   │   └── corrector.py      # Apply plane correction / referencing to rasters
│   ├── ioutil/               # Output I/O helpers (named ioutil to avoid shadowing stdlib io)
│   │   ├── __init__.py
│   │   └── metadata.py       # Generate .meta sidecar files
│   ├── pipeline/             # Top-level processing orchestration
│   │   ├── __init__.py
│   │   ├── runner.py         # run() dispatcher, input validation, session model
│   │   ├── correction.py     # Velocity-field correction workflow
│   │   └── referencing.py    # Time-series referencing workflow
│   ├── utils/                # Cross-cutting utilities
│   │   ├── __init__.py
│   │   ├── cache.py          # LRU on-disk file cache (CacheHandling)
│   │   ├── logging_setup.py  # Structured logging initialisation
│   │   └── validation.py     # CLI-argument validators (scale, dates, codes)
│   ├── viz/                  # Visualisation
│   │   ├── __init__.py
│   │   └── plots.py          # Scatter plots, station maps, spatial coverage
│   └── tools/                # Active connectors and data utilities
│       ├── EPOSjson.py       # EPOS REST API connector
│       ├── NGLtenv3.py       # NGL tenv3 file parser
│       ├── reference.py      # InSAR time-series referencing engine
│       ├── csv2raster.py     # EPOS TCS CSV → GeoTIFF converter (user-facing)
│       ├── caching.py        # Legacy cache wrapper
│       ├── download.py       # Generic HTTP download helper
│       ├── geodetic.py       # Geodetic utilities (legacy)
│       ├── geoprocessing.py  # Raster/geometry helpers (legacy)
│       └── timeseries.py     # GNSS time-series parsing helper
└── tests/                    # pytest test suite
    ├── conftest.py           # Path setup (adds src/ to sys.path)
    ├── test_schema.py        # STATION_COLUMNS, FitResult, validate_station_df, …
    ├── test_fitting.py       # Weighting functions, IRLS, RANSAC, fit_plane
    ├── test_geo_geodetic.py  # LLH ↔ ECEF round-trip, projections, outliers
    ├── test_utils.py         # CacheHandling, validate_*, setup_logging
    ├── test_caching.py       # Legacy cache tests (kept for CI compatibility)
    └── test_installation.py  # Environment and dependency checks

Top-level Directories

• cache/

  Managed automatically by utils.cache. Do not edit manually. The file .cache_config.json stores the cache size limit and the LRU access timestamps for each cached file.

• data/

  Raw input datasets and reference outputs for the three bundled test cases. See Quick Start for a step-by-step guide.

• doc/

  Sphinx documentation sources. Build with:

  cd doc && make html
  

• output/

  Default destination for corrected rasters, diagnostic figures, and .meta sidecar files. Can be overridden with --output_directory.

Source Packages

All source code lives under src/. The sub-packages follow a strict one-responsibility principle:

config.py / schema.py

Shared data contracts. config.py contains all user-tunable parameters as frozen dataclasses (ProcessingConfig, FittingConfig, …). schema.py defines the column contract for GNSS station DataFrames (STATION_COLUMNS) and the FitResult dataclass returned by every fitting function.

fitting/

Pure numerical code — no I/O, no raster access. Three modules: weighting (Huber, Tukey, MAD scale), irls (IRLS plane fit), ransac (RANSAC plane fit). The public entry point is fitting.fit_plane(X, y, method=…).

geo/

Everything involving geometry or coordinates: geodetic conversions (WGS-84, ECEF), CRS selection, raster sampling (get_raster_value), LOS projection of NEU vectors, Voronoi-based station distribution assessment, and Ordinary Kriging fallback grid.

gnss/

Data-source adapters following the GNSSSource abstract base class. factory.py selects the correct adapter at runtime and projects downloaded NEU velocities into the InSAR LOS direction. stations.py filters, weights, and assesses the spatial distribution of the final station set.

insar/

Ingests InSAR raster products and applies corrections. reader.py extracts footprint, bounding box, and LOS vectors from a GeoTIFF. corrector.py subtracts the fitted plane from the raster.

ioutil/

Writes .meta sidecar files that document the processing parameters, GNSS source, fitting metrics, and station list for each output product. Named ioutil (not io) to avoid shadowing Python’s stdlib io module.

pipeline/

Top-level orchestration. runner.py validates inputs, selects the workflow, and routes to correction.py or referencing.py.

utils/

Cross-cutting infrastructure: LRU on-disk cache, structured logging, and CLI-argument validators.

viz/

Diagnostic figures: scatter plots (GNSS–InSAR differences before and after correction), station location maps, and spatial coverage maps.

tools/ (legacy connectors — active)

Original data connectors that remain in active use:

• EPOSjson.py — EPOS REST API connector (used by gnss/epos.py).

• NGLtenv3.py — NGL tenv3 file parser (used by gnss/ngl.py).

• reference.py — InSAR time-series referencing engine (used by pipeline/referencing.py).

• csv2raster.py — standalone script to convert EPOS TCS CSV products to GeoTIFF format; run directly by the user before processing.

These modules are not scheduled for removal — they encapsulate provider-specific logic that is stable and well-tested. New functionality should go into the thematic sub-packages (gnss/, insar/, etc.) rather than into tools/.

Configuration and Metadata Files

File	Description
environment.yml	Conda environment specification (recommended installation method).
pyproject.toml	Build system requirements, pytest settings, and package metadata.
requirements.txt	Flat pip dependency list (fallback only; prefer environment.yml).
.gitlab-ci.yml	GitLab CI pipeline (lint, test, docs build, deploy).
.zenodo.json	Zenodo archival metadata for DOI assignment.
CITATION.cff	Citation File Format metadata for academic reference.
codemeta.json	CodeMeta machine-readable software description.
LICENSE.txt	GNU General Public License.