How mahmoodlab/porpoise works
Project type and purpose
• This is a command-line driven, Python-based research pipeline for pan-cancer prognosis using multimodal deep learning.
• It integrates whole-slide image (WSI) patch features and molecular profile data to train and evaluate survival models across 14 cancer types.
Main components of the system
a. External Data Sources
• GDC Data Portal (WSI: .svs files)
• cBioPortal (molecular CSVs)
b. Preprocessing (CLAM toolbox)
• Tissue segmentation → 256×256 patches → ResNet50 encoding → .pt feature files
c. Data Storage
• DATA_ROOT_DIR/ (per-cancer subfolders of .pt files)
• datasets_csv/ & datasets_csv_mutsig/ (molecular feature CSVs)
• splits/5foldcv/ (train/val split CSVs)
d. Dataset Loader Layer
• datasets/dataset_generic.py & dataset_survival.py implement PyTorch Dataset classes that:
– ingest .pt features + molecular CSVs + splits
– yield (image_features, molecular_features, label) batches
e. Model Definitions
• models/model_set_mil.py (SNN / set-based MIL)
• models/model_coattn.py (co-attention MIL)
• models/model_genomic.py (genomic-only network)
• models/model_porpoise.py (multimodal fusion network)
• models/model_utils.py (shared layers)
f. Training & Evaluation Utilities
• utils/*.py (train loops, loss functions, regularization, file I/O, evaluation metrics)
• core_utils.py orchestrates experiment setup
g. Control Scripts
• main.py – parses CLI args (--mode, --model_type, --which_splits, etc.), launches training
• eval_surv.py – loads checkpoints, computes survival metrics and visualizations
h. Documentation
• docs/INSTALLATION.md, docs/Commands.md, docs/README.md
Relationships and data flow
1) Raw WSIs (.svs) & molecular CSVs → CLAM toolbox (external) → .pt feature files + cleaned CSVs stored locally
2) splits/5foldcv defines train/val Case IDs for each cancer type
3) Dataset classes load features + CSVs + split files → PyTorch DataLoader
4) main.py passes DataLoader → selected Model → utils functions drive training loop → produces:
– model checkpoints (.pt)
– tensorboard logs, evaluation CSVs
5) eval_surv.py consumes checkpoints + splits → generates final performance metrics
Architectural patterns and design principles
• Pipeline pattern: Preprocessing → Storage → Loading → Training → Evaluation
• Modular package structure (datasets, models, utils) for separation of concerns
• CLI-driven orchestration to swap models, modalities, splits without code changes
• Use of standard ML frameworks (PyTorch, TensorFlow, Captum, SHAP) abstracted behind utility modules