# vmath20/isopath architecture

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

- Interactive diagram: https://gitdiagram.com/vmath20/isopath
- Repository: https://github.com/vmath20/isopath

## Overview

##### Project type and purpose
- This is a data‑analysis pipeline (full-stack in the sense of ETL + compute + visualization) for computational pathology.
- Purpose: extract histopathology image patches from TCGA WSIs, generate feature embeddings using seven pre‑trained vision models, compute Representational Dissimilarity Matrices (RDMs), and perform second‑order analyses (RSA, clustering, specificity, spectral analysis).

##### File structure
- Top‑level:
- preprocessing.py        → data ingestion & patch extraction
- FinalRDMGenerations.ipynb → analysis & visualization notebook
- generate_embeddings/   → seven parallel scripts/notebooks (one per model)
- README.md, LICENSE    → documentation
- There are no “frontend” or “backend” directories. Instead, this is a linear modular pipeline:
- Data Acquisition & Preprocessing
- Embedding Generation (multi‑model)
- Analysis & Visualization
- Hard‑coded paths indicate reliance on cluster file systems (`/tcga/`, `/lotterlab/`).
- Each script generates `.npy` files and writes to data directories.

##### Key insights from README
- Steps: Preprocessing→Embedding→Batching→RDM calculation→Second‑order RSA→Clustering→Specificity→Spectral analysis.
- External dependencies: TCGA WSI data, Hugging Face Hub models, `openslide`, `timm`, `rsatoolbox`.
- Outputs: `.npy` (patches, embeddings, RDMs), heatmaps, dendrograms, CSVs.

a. Main components
- Data Sources
– TCGA WSI files (.svs)
– Metadata (gdc_sample_sheet.tsv)
- Preprocessing Module (`preprocessing.py`)
- Patch Storage (e.g., NFS/S3 folders for .npy patches)
- Embedding Generation Modules (seven parallel workers)
– ConchEmbeddings.ipynb
– plip.py, prov.py, quiltnet.py, resnet.py, uni.py, virchow.py
- Embeddings Storage (per model & cancer type .npy files)
- Analysis Module (`FinalRDMGenerations.ipynb`)
– Batching
– RDM Calculation
– Second‑order RSA
– Clustering
– Specificity Analysis
– Spectral Analysis
- Visualization & Results Storage (heatmaps, CSVs)
- External Services
– Hugging Face Model Hub
– GPU Compute Cluster

b. Relationships & data flow
1. Data Sources → Preprocessing
(openslide thumbnail → Otsu → 224×224 patches → save .npy)
2. Preprocessing → Patch Storage
3. Patch Storage → Embedding Generation Modules
(each model loads patches, applies transforms, forwards through model → .npy embeddings)
4. Embedding Generation → Embeddings Storage
5. Embeddings Storage → Analysis Module
(batch splitting → RDMs → second‑order RSA → clustering etc.)
6. Analysis Module → Results Storage (figures, CSVs)
7. External calls: Embedding scripts authenticate to HF Hub; all compute runs on GPU cluster.

c. Architectural patterns & principles
- Modular ETL pipeline: clear separation of data ingestion, transformation, compute, and analysis.
- Parallel workers for embedding generation (one per model) for scalability.
- Batch processing within analysis for statistical robustness.
- Durable artifacts at each stage (.npy, .csv, .png) to decouple steps.
- Hard‑coded config signals potential refactoring into config files or environment variables.

d. Key technologies & libraries
- Python scripts & Jupyter notebooks
- openslide (WSI reading)
- numpy (.npy IO)
- timm, Hugging Face Transformers/CLIP (model inference)
- rsatoolbox (RDM calculations)
- scipy, sklearn (clustering, SVD)
- matplotlib/seaborn (visualizations)

##### Details
- Specific script/notebook as its own component under Embedding Generation.
- Bidirectional if an analysis step can trigger re‑generation (e.g., tweak paths and re-run).

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Data Sources"
    direction TB
    WSI["TCGA WSI (.svs)"]:::storage
    MD["Metadata (gdc_sample_sheet.tsv)"]:::storage
  end

  Preproc["Preprocessing Module\npreprocessing.py"]:::compute
  WSI -->|"slides & thumbnails"| Preproc
  MD -->|"metadata"| Preproc

  PatchStore[(Patch Storage\n.npy patches)]:::storage
  Preproc -->|".npy patches"| PatchStore

  subgraph "Embedding Generation Modules"
    direction TB
    CE["ConchEmbeddings.ipynb"]:::compute
    plip["plip.py"]:::compute
    prov["prov.py"]:::compute
    quiltnet["quiltnet.py"]:::compute
    resnet["resnet.py"]:::compute
    uni["uni.py"]:::compute
    virchow["virchow.py"]:::compute
  end

  PatchStore --> CE
  PatchStore --> plip
  PatchStore --> prov
  PatchStore --> quiltnet
  PatchStore --> resnet
  PatchStore --> uni
  PatchStore --> virchow

  EmbStore[(Embedding Storage\n.npy embeddings)]:::storage
  CE -->|".npy embeddings"| EmbStore
  plip -->|".npy embeddings"| EmbStore
  prov -->|".npy embeddings"| EmbStore
  quiltnet -->|".npy embeddings"| EmbStore
  resnet -->|".npy embeddings"| EmbStore
  uni -->|".npy embeddings"| EmbStore
  virchow -->|".npy embeddings"| EmbStore

  AnalysisModule["Analysis Module\nFinalRDMGenerations.ipynb"]:::compute
  EmbStore --> AnalysisModule
  AnalysisModule --> Batching

  subgraph "Analysis Steps"
    direction TB
    Batching["Batching"]:::compute
    RDM["RDM Calculation"]:::compute
    RSA["Second-order RSA"]:::compute
    Cluster["Clustering"]:::compute
    Spec["Specificity Analysis"]:::compute
    Spectral["Spectral Analysis"]:::compute
  end

  Batching --> RDM
  RDM --> RSA
  RSA --> Cluster
  Cluster --> Spec
  Spec --> Spectral

  Results[(Results Storage\nheatmaps, CSVs)]:::results
  Spectral --> Results

  HF["Hugging Face Hub"]:::external
  GPU["GPU Compute Cluster"]:::external

  HF --> CE
  HF --> plip
  HF --> prov
  HF --> quiltnet
  HF --> resnet
  HF --> uni
  HF --> virchow

  GPU --> Preproc
  GPU --> CE
  GPU --> plip
  GPU --> prov
  GPU --> quiltnet
  GPU --> resnet
  GPU --> uni
  GPU --> virchow
  GPU --> Batching
  GPU --> RDM
  GPU --> RSA
  GPU --> Cluster
  GPU --> Spec
  GPU --> Spectral

  Documentation["Documentation\nREADME.md\nLICENSE"]:::external

  click Preproc "https://github.com/vmath20/isopath/blob/main/preprocessing.py"
  click CE "https://github.com/vmath20/isopath/blob/main/generate_embeddings/ConchEmbeddings.ipynb"
  click plip "https://github.com/vmath20/isopath/blob/main/generate_embeddings/plip.py"
  click prov "https://github.com/vmath20/isopath/blob/main/generate_embeddings/prov.py"
  click quiltnet "https://github.com/vmath20/isopath/blob/main/generate_embeddings/quiltnet.py"
  click resnet "https://github.com/vmath20/isopath/blob/main/generate_embeddings/resnet.py"
  click uni "https://github.com/vmath20/isopath/blob/main/generate_embeddings/uni.py"
  click virchow "https://github.com/vmath20/isopath/blob/main/generate_embeddings/virchow.py"
  click EmbStore "https://github.com/vmath20/isopath/tree/main/generate_embeddings/"
  click AnalysisModule "https://github.com/vmath20/isopath/blob/main/FinalRDMGenerations.ipynb"
  click Documentation "https://github.com/vmath20/isopath/blob/main/README.md"
  classDef storage fill:#ADD8E6,stroke:#000;
  classDef compute fill:#90EE90,stroke:#000;
  classDef external fill:#FFA500,stroke:#000;
  classDef results fill:#DDA0DD,stroke:#000;
```
