# mgovorcin/venti architecture

> Architecture diagram of the GitHub repository mgovorcin/venti, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mgovorcin/venti
- Repository: https://github.com/mgovorcin/venti

## Overview

##### Project Type and Purpose
- Venti is an open-source Python toolbox (not a web app) for scientific analysis of vertical land motion (VLM) using InSAR and GNSS data.
- It provides data-ingestion readers, processing pipelines (calibration, interpolation, LOS decomposition), statistical modeling (variogram), and inversion solvers (hector, midas).

##### File-Structure Analysis
- Top-level directories:
- data/ – sample plate boundary and metadata files
- notebooks/ – Jupyter workflows demonstrating GNSS & InSAR workflows
- src/venti/ – core library organized by functional subpackages: calibration, gnss, insar, losdecomp, solvers, utils
- Configuration and packaging: setup.py, MANIFEST.in, tox.ini, environment.yml (implied).
- Obsolete/ contains legacy code; ignore for the main architecture.

##### Key Components
a. Data Inputs
- Raw GNSS observations (src/venti/gnss/readers via gps.py)
- InSAR stacks (via mintpy wrapper in src/venti/insar/mintpy)
- Plate-boundary metadata (data/plates)
b. Data-Ingestion Layer
- Reader modules: src/venti/gnss, src/venti/insar/mintpy, plus calibration/utils for metadata
c. Processing Pipelines
- GNSS interpolation (hvlsc_py3 collocation, empirical covariance, grid)
- Insar referencing & correction (std_reference_correction, ts_spatial_referencing)
- LOS decomposition (src/venti/losdecomp)
- Calibration routines (src/venti/calibration)
- Variogram modeling (src/venti/insar/variogram)
d. Solvers & Inversion
- hector and midas implementations in src/venti/solvers
e. Utilities & Execution
- Dask-based clustering for scaling (src/venti/utils/dask_cluster)
- CLI entry points (setup.py) or notebook orchestration
f. Outputs
- VLM rate grids, error estimates, diagnostic plots

##### Relationships and Data Flow
- Merge paths into Calibration & Referencing module → LOS Decomposition → Variogram Model
- Output of variogram enters Solvers → Final VLM estimates → Results (files/plots)
- Utilities (dask_cluster, utils) underpin all heavy computations

##### Architectural Patterns & Principles
- Modular subpackages, each encapsulating one domain (single responsibility)
- Pipeline pattern: clear data-flow stages chained together
- Plugin-style interpolation backends (hvlsc_py3) and solver backends (hector, midas)
- Separation of I/O, processing, and analysis

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients"
        NB["Jupyter Notebooks"]:::client
        CLI["CLI (setup.py)"]:::client
    end

    %% Data Inputs & Readers
    subgraph "Data Inputs & Readers"
        PlateMeta["Plate Metadata"]:::data
        GNSSReader["GNSS Reader (gps.py)"]:::data
        InSARReader["InSAR Reader (MintPy)"]:::data
        CalibMetaUtils["Calibration Metadata Utils"]:::data
    end

    %% Processing Pipelines
    subgraph "Processing Pipelines"
        GNSSInterp["GNSS Interpolation"]:::proc
        StdRef["Std Reference Correction"]:::proc
        TSRef["TS Spatial Referencing"]:::proc
        Calibration["Calibration Routines"]:::proc
        LOS["LOS Decomposition"]:::proc
        Variogram["Variogram Modeling"]:::proc
    end

    %% Solvers & Inversion
    subgraph "Solvers & Inversion"
        Hector["Hector Solver"]:::solver
        MIDAS["MIDAS Solver"]:::solver
    end

    %% Outputs
    FinalOutputs["VLM Estimates & Results"]:::output

    %% Utilities
    subgraph "Utilities"
        DaskCluster["Dask Cluster"]:::util
        Utils["General Helpers"]:::util
    end

    %% External Dependencies
    MintPy((MintPy)):::external
    Dask((Dask)):::external

    %% Data Flow
    NB -->|drives| PlateMeta
    NB -->|drives| GNSSReader
    NB -->|drives| InSARReader
    CLI -->|drives| PlateMeta
    CLI -->|drives| GNSSReader
    CLI -->|drives| InSARReader

    PlateMeta -->|metadata| GNSSInterp
    PlateMeta -->|metadata| StdRef

    GNSSReader -->|GNSS time series| GNSSInterp
    InSARReader -->|InSAR stack| StdRef

    MintPy -.->|wrapper| InSARReader
    StdRef -->|referenced stack| TSRef
    TSRef -->|spatially-referenced TS| Calibration

    GNSSInterp -->|interpolated field| Calibration
    CalibMetaUtils -->|ancillary metadata| Calibration

    Calibration -->|calibrated data| LOS
    LOS -->|3D displacements| Variogram
    Variogram -->|variogram model| Hector
    Variogram -->|variogram model| MIDAS

    Hector -->|inversion results| FinalOutputs
    MIDAS -->|inversion results| FinalOutputs

    DaskCluster -.->|scaling| GNSSInterp
    DaskCluster -.->|scaling| StdRef
    DaskCluster -.->|scaling| Calibration
    DaskCluster -.->|scaling| Hector
    Utils -.-> GNSSInterp
    Utils -.-> StdRef
    Utils -.-> Calibration
    Dask -.->|dependency| DaskCluster

    %% Click Events
    click PlateMeta "https://github.com/mgovorcin/venti/blob/main/data/plates/PB2002_boundaries.json"
    click GNSSReader "https://github.com/mgovorcin/venti/blob/main/src/venti/gnss/gps.py"
    click InSARReader "https://github.com/mgovorcin/venti/tree/main/src/venti/insar/mintpy/"
    click CalibMetaUtils "https://github.com/mgovorcin/venti/blob/main/src/venti/calibration/utils.py"
    click GNSSInterp "https://github.com/mgovorcin/venti/blob/main/src/venti/gnss/interpolation/hvlsc_py3/src/collocation.py"
    click StdRef "https://github.com/mgovorcin/venti/blob/main/src/venti/insar/std_reference_correction.py"
    click TSRef "https://github.com/mgovorcin/venti/blob/main/src/venti/insar/ts_spatial_referencing.py"
    click Calibration "https://github.com/mgovorcin/venti/blob/main/src/venti/calibration/calibration.py"
    click LOS "https://github.com/mgovorcin/venti/blob/main/src/venti/losdecomp/los2disp3d.py"
    click Variogram "https://github.com/mgovorcin/venti/blob/main/src/venti/insar/variogram/variogram.py"
    click Hector "https://github.com/mgovorcin/venti/blob/main/src/venti/solvers/hector.py"
    click MIDAS "https://github.com/mgovorcin/venti/blob/main/src/venti/solvers/midas.py"
    click DaskCluster "https://github.com/mgovorcin/venti/blob/main/src/venti/utils/dask_cluster.py"
    click Utils "https://github.com/mgovorcin/venti/blob/main/src/venti/utils/utils.py"
    click NB "https://github.com/mgovorcin/venti/tree/main/notebooks/"
    click CLI "https://github.com/mgovorcin/venti/blob/main/setup.py"

    %% Styles
    classDef data fill:#e6ffed,stroke:#2ecc71,stroke-width:2px
    classDef proc fill:#e8f4ff,stroke:#3498db,stroke-width:2px
    classDef solver fill:#fff4e6,stroke:#e67e22,stroke-width:2px
    classDef util fill:#f2f2f2,stroke:#7f8c8d,stroke-width:2px
    classDef client fill:#fffbe6,stroke:#f1c40f,stroke-width:2px
    classDef output fill:#e6ffe6,stroke:#27ae60,stroke-width:2px
    classDef external fill:#ffffff,stroke-dasharray: 5 5,stroke:#95a5a6,stroke-width:2px
```
