How cns-iu/hra-ftu-vccf-supporting-information works
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