How vmath20/isopath works
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).