# cedavidyang/network-risk architecture

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

- Interactive diagram: https://gitdiagram.com/cedavidyang/network-risk
- Repository: https://github.com/cedavidyang/network-risk

## Overview

##### Project type and purpose
- This is an open-source data-analysis and modeling toolkit for “Performance-Based Risk Assessment for Large-Scale Transportation Networks” using Transitional Markov Chain Monte Carlo (TMCMC).
- It consists of data assets (GIS network files), a core Python library (`netrisk_TMCMC`), and a set of top-level scripts that drive network preparation, case studies, risk computations, and results processing.

##### Main components of the system
a. Data Assets
- Directory: `assets/`
- Contains GIS shapefiles, GraphML, GeoPackage, etc., for the Oregon highway network.
b. Network Preparation
- Script: `prepare_OR_network.py`
- Reads raw GIS data, builds graph representations, serializes them for later use.
c. Core TMCMC Library
- Package: `netrisk_TMCMC/`
- `highway_network.py` — network data structures & I/O
- `net_util.py` — graph algorithms (path‐finding, vulnerability metrics)
- `sampler.py` — TMCMC sampler implementation
- `type_verifier.py` — input-type & parameter checks
- `benchmark.py` — performance measurement & logging
d. Use-Case Scripts
- `case_I.py` & `case_II.py` — parameterized examples of TMCMC runs (different seeds, asset sets)
- `OR_risk.py` — applies TMCMC method to compute risk on Oregon network
- `OR_MCS_risk.py` — Monte Carlo Simulation (crude MCS) baseline risk estimation
e. Output & Post-Processing
- Directory: `results/` (CSV, Excel)
- Script: `results_processing.py` for aggregating, plotting, and summarizing results
f. Configuration & Environment
- `.gitignore` for excluding intermediate files (e.g., `.DS_Store`, large GPkg files)

##### Relationships & Data Flow
- Assets → prepare_OR_network.py → serialized network graphs
- prepare_OR_network.py → (uses netrisk_TMCMC.highway_network + net_util)
- case_I/II.py & OR_risk.py & OR_MCS_risk.py → import and call `netrisk_TMCMC.sampler` + other modules → generate raw risk results
- Scripts write to `results/`
- `results_processing.py` → reads `results/` → produces final tables/plots

##### Key architectural patterns & principles
- Pipeline / workflow pattern: clear stages from data ingestion → model setup → sampling → results output
- Modular design: core algorithm code isolated in `netrisk_TMCMC` for reusability and testing
- Single-responsibility scripts: each top-level `.py` file has one main job (network prep, case runs, risk computing, post-processing)
- Separation of data (assets), code (library vs. scripts), and outputs (results)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    DS["assets/"]:::dataStore
    click DS "https://github.com/cedavidyang/network-risk/tree/main/assets/"

    %% Orchestration Layer
    Prepare["prepare_OR_network.py"]:::script
    click Prepare "https://github.com/cedavidyang/network-risk/blob/main/prepare_OR_network.py"

    %% Core Library Layer
    subgraph "Core TMCMC Library"
        direction TB
        NetPkg(("netrisk_TMCMC/")):::core
        Highway["highway_network.py<br/>(network data I/O)"]:::core
        Util["net_util.py<br/>(graph algorithms)"]:::core
        Sampler["sampler.py<br/>(TMCMC algorithm)"]:::core
        Verifier["type_verifier.py<br/>(input checks)"]:::core
        Benchmark["benchmark.py<br/>(performance & logging)"]:::core
    end
    click NetPkg "https://github.com/cedavidyang/network-risk/tree/main/netrisk_TMCMC/"
    click Highway "https://github.com/cedavidyang/network-risk/blob/main/netrisk_TMCMC/highway_network.py"
    click Util "https://github.com/cedavidyang/network-risk/blob/main/netrisk_TMCMC/net_util.py"
    click Sampler "https://github.com/cedavidyang/network-risk/blob/main/netrisk_TMCMC/sampler.py"
    click Verifier "https://github.com/cedavidyang/network-risk/blob/main/netrisk_TMCMC/type_verifier.py"
    click Benchmark "https://github.com/cedavidyang/network-risk/blob/main/netrisk_TMCMC/benchmark.py"

    %% Use-Case Scripts
    subgraph "Use-Case Scripts"
        direction TB
        CaseI["case_I.py"]:::script
        CaseII["case_II.py"]:::script
        ORRisk["OR_risk.py"]:::script
        ORMCS["OR_MCS_risk.py"]:::script
    end
    click CaseI "https://github.com/cedavidyang/network-risk/blob/main/case_I.py"
    click CaseII "https://github.com/cedavidyang/network-risk/blob/main/case_II.py"
    click ORRisk "https://github.com/cedavidyang/network-risk/blob/main/OR_risk.py"
    click ORMCS "https://github.com/cedavidyang/network-risk/blob/main/OR_MCS_risk.py"

    %% Output & Post-Processing
    Results["results/"]:::dataStore
    Proc["results_processing.py"]:::script
    click Results "https://github.com/cedavidyang/network-risk/tree/main/results/"
    click Proc "https://github.com/cedavidyang/network-risk/blob/main/results_processing.py"

    %% Configuration
    GitIgnore[".gitignore"]:::external
    click GitIgnore "https://github.com/cedavidyang/network-risk/blob/main/.gitignore"

    %% Connections
    DS -->|"GIS files (Shapefile, GPKG, GraphML)"| Prepare
    Prepare -->|"uses highway_network & net_util"| Highway
    Prepare --> Util
    Prepare -->|"serializes graph objects"| CaseI
    Prepare --> CaseII
    Prepare --> ORRisk
    Prepare --> ORMCS

    CaseI -->|"imports sampler & utils"| Sampler
    CaseII --> Sampler
    ORRisk --> Sampler
    ORMCS -->|"Monte Carlo baseline calls utility"| Util

    CaseI -->|"writes risk samples CSV"| Results
    CaseII --> Results
    ORRisk --> Results
    ORMCS --> Results

    Results -->|"reads sample CSVs"| Proc
    Proc -->|"produces plots & tables"| Results

    %% Styles
    classDef dataStore fill:#cde5ff,stroke:#036;
    classDef core fill:#d4f8c4,stroke:#0a0;
    classDef script fill:#ffe0b2,stroke:#e65;
    classDef external fill:#e0e0e0,stroke:#888;
```
