# cns-iu/hra-ftu-vccf-supporting-information architecture

> Architecture diagram of the GitHub repository cns-iu/hra-ftu-vccf-supporting-information, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cns-iu/hra-ftu-vccf-supporting-information
- Repository: https://github.com/cns-iu/hra-ftu-vccf-supporting-information

## Overview

##### Project type and purpose
- This is an open-source data-visualization tool (not a full-stack web app) that generates “butterfly” radial tree visualizations of Functional Tissue Units (FTUs) and their blood-vasculature connections for the Human Reference Atlas.
- It ingests ASCT+B JSON data (either via live API or static files), builds a network graph, and outputs SVGs that can be post-processed into a printable poster.

##### File structure
- Top-level folders:
- data: static CSV/Excel files (Table_S1, asct-22-FTUs)
- code: Python notebooks and scripts, plus versioned data and Vega configs
- visualization: final assets (PDF halves, AI poster)
- Inside code:
- build-network.py: reads CSV/JSON, constructs NetworkX graph
- hra_butterfly.py & HRA_Butterfly_viz.ipynb (and v2, v3): orchestration of data → radial layout → rendering
- data/v1.4 & v2.2: historical JSON/CSV data dumps, versioned for reproducibility
- viz_v2.0, viz_v2.2: Vega-Lite/SceneGraph JSON configs for front-end rendering
- requirements.txt & setup.sh: environment setup, dependency management

##### Insights from README
- Dependencies: pandas, numpy, networkx, datashader, vl_convert, svgutils
- Workflow:
a) Run build-network.py to convert raw ASCT+B data into a graph
b) Run the notebook (or hra_butterfly.py) to layout nodes in a radial “butterfly” tree, overlay vasculature edges
c) Export SVG, combine halves in Illustrator, add legends/titles

##### Components
1. Data Sources
- Local static data (data/)
- ASCT+B Reporter API (external HTTP)
2. Data Ingestion & Processing
- build-network.py (graph construction)
- hra_butterfly.py & Jupyter Notebooks (layout & rendering)
3. Configuration Layer
- Vega/SceneGraph JSON configs (viz_v2.0, viz_v2.2)
4. Rendering Engine
- NetworkX + Datashader → intermediate SVG
- VL_Convert + svgutils for final SVG tweaks
5. Post-Processing
- Manual assembly in Adobe Illustrator
6. Output Artifacts
- SVG files (code/viz_v*)
- PDFs, AI files (visualization/)

- Data Sources → Data Ingestion
- Data Ingestion → Configuration Layer (feeds processed graph & metadata)
- Configuration Layer + Rendering Engine → SVG Output
- SVG Output → Post-Processing → Final Poster

c. Architectural patterns / design principles:
- Pipeline/multiple-stage ETL (Extract → Transform → Load → Render → Post-process)
- Versioned data/config directories allow reproducible builds
- Separation of concerns: graph construction, layout & rendering, configuration, and manual finishing

d. Key technologies / libraries:
- Python ecosystem: pandas, numpy, networkx
- Visualization: datashader, Vega-Lite/SceneGraph, vl_convert, svgutils
- Jupyter notebooks for exploratory code
- Adobe Illustrator for final poster assembly
- Bash setup.sh for environment provisioning

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources
    subgraph "Data Sources"
        style DataSources fill:#E8F1F2,stroke:#333,stroke-width:1px
        LocalStatic["Local Static Data\n(data/Table_S1.xlsx,\ndata/asct-22-FTUs.csv)"]:::data
        ASCT_API["ASCT+B Reporter API\n(External HTTP)"]:::external
        VersionedData["Versioned ASCT+B Data Dumps\n(code/data/v1.4/, code/data/v2.2/)"]:::data
    end

    %% Ingestion & Processing
    subgraph "Data Ingestion & Processing"
        style Ingestion fill:#FEF3C7,stroke:#333,stroke-width:1px
        BuildNet["build-network.py"]:::processing
        SetupSh["setup.sh"]:::utility
        ReqTxt["requirements.txt"]:::utility
        Orchestration["Layout & Rendering Orchestration\n(hra_butterfly.py,\nnotebooks)"]:::processing
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        style ConfigLayer fill:#FDECEF,stroke:#333,stroke-width:1px
        VizV2_0["Vega Configs v2.0\n(code/viz_v2.0/)"]:::config
        VizV2_2["Vega & SceneGraph Configs v2.2\n(code/viz_v2.2/)"]:::config
    end

    %% Rendering Engine
    subgraph "Rendering Engine"
        style Rendering fill:#E8F8F5,stroke:#333,stroke-width:1px
        RenderLibs["NetworkX + Datashader\n→ intermediate SVG"]:::engine
        FinalSVG["vl_convert + svgutils\n→ final SVG"]:::engine
    end

    %% Post-Processing
    subgraph "Post-Processing"
        style PostProc fill:#F4ECF7,stroke-dasharray: 5 5,stroke:#333,stroke-width:1px
        Illustrator["Adobe Illustrator\n(manual assembly)"]:::manual
    end

    %% Output Artifacts
    subgraph "Output Artifacts"
        style Output fill:#FFF5E5,stroke:#333,stroke-width:1px
        SVGOut["SVG Files\n(code/viz_v2.*)"]:::output
        PDFs["PDFs & AI Files\n(visualization/)"]:::output
    end

    %% Connections
    LocalStatic -->|ingest| BuildNet
    VersionedData -->|ingest| BuildNet
    ASCT_API -->|fetch| BuildNet
    BuildNet -->|graph| Orchestration
    SetupSh -->|env| BuildNet
    ReqTxt -->|deps| BuildNet
    Orchestration -->|uses| VizV2_0
    Orchestration -->|uses| VizV2_2
    VizV2_0 -->|config| RenderLibs
    VizV2_2 -->|config| RenderLibs
    RenderLibs -->|SVG| FinalSVG
    FinalSVG -->|SVG| SVGOut
    SVGOut -->|assemble| Illustrator
    Illustrator -->|export| PDFs

    %% Click Events
    click LocalStatic "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/blob/main/data/Table_S1.xlsx"
    click LocalStatic "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/blob/main/data/asct-22-FTUs.csv"
    click VersionedData "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/tree/main/code/data/v1.4/"
    click VersionedData "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/blob/main/code/data/v2.2/asct-nodes.csv"
    click VersionedData "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/blob/main/code/data/v2.2/asct-edges.csv"
    click VersionedData "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/blob/main/code/data/v2.2/asct-blood-vasculature-edges.csv"
    click BuildNet "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/blob/main/code/build-network.py"
    click SetupSh "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/blob/main/code/setup.sh"
    click ReqTxt "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/blob/main/code/requirements.txt"
    click Orchestration "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/blob/main/code/hra_butterfly.py"
    click Orchestration "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/blob/main/code/HRA_Butterfly_viz.ipynb"
    click Orchestration "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/blob/main/code/HRA_Butterfly_viz_v2.ipynb"
    click Orchestration "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/blob/main/code/HRA_Butterfly_viz_v3.ipynb"
    click VizV2_0 "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/tree/main/code/viz_v2.0/"
    click VizV2_2 "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/tree/main/code/viz_v2.2/"
    click PDFs "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/blob/main/visualization/Left_half.pdf"
    click PDFs "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/blob/main/visualization/Right_half.pdf"
    click PDFs "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/blob/main/visualization/Full_poster.pdf"
    click PDFs "https://github.com/cns-iu/hra-ftu-vccf-supporting-information/blob/main/visualization/butterfly_viz_v14.ai"

    %% Styles
    classDef data fill:#CCE5FF,stroke:#333,stroke-width:1px
    classDef external fill:#D6EAF8,stroke:#333,stroke-width:1px
    classDef processing fill:#FCF3CF,stroke:#333,stroke-width:1px
    classDef utility fill:#F8F9F9,stroke:#333,stroke-width:1px
    classDef config fill:#FADBD8,stroke:#333,stroke-width:1px
    classDef engine fill:#D1F2EB,stroke:#333,stroke-width:1px
    classDef manual fill:#E8DAEF,stroke:#333,stroke-width:1px
    classDef output fill:#FEF9E7,stroke:#333,stroke-width:1px
```
