| --- |
| license: cc-by-nc-4.0 |
| tags: |
| - computational-pathology |
| - survival-analysis |
| - whole-slide-imaging |
| - gene-expression |
| - oncology |
| - histopathology |
| extra_gated_prompt: | |
| These weights are released under CC BY-NC 4.0 — strictly non-commercial, |
| research and educational use only. By requesting access you agree to: |
| 1. Use the weights only for non-commercial research. |
| 2. Cite the SPARC paper in any derived publication. |
| 3. Not redistribute the weights to third parties. |
| extra_gated_fields: |
| Name: text |
| Affiliation: text |
| Email: text |
| Intended use: text |
| I agree to the non-commercial license: checkbox |
| --- |
| |
| # SPARC |
|
|
| **Gene-program-aware survival modelling from H&E whole-slide images.** |
|
|
| This repository hosts the trained model weights for the SPARC paper (Ayed, |
| Cohn, et al.). Code, configs, training scripts, and figure-regeneration |
| notebooks live at **[github.com/aziz-ayed/SPARC](https://github.com/aziz-ayed/SPARC)**. |
|
|
| SPARC is a two-stage pipeline: |
|
|
| 1. **SPARC-Map** predicts 40 hallmark gene-expression-program (GEP) scores |
| per H&E patch, recovering a *spatial* molecular map of each slide. |
| 2. **SPARC-Risk** fuses those per-patch GEP scores with the same H&E |
| features through a signature-query attention head and a cancer-aware |
| gate, producing a single per-patient risk score. |
|
|
| These weights cover the SPARC-Risk model, the image-only baseline used for |
| ablations, and the SPARC-Map GEP-prediction model. |
|
|
| <p align="center"> |
| <img src="https://raw.githubusercontent.com/aziz-ayed/SPARC/main/docs/figs/figure1.png" alt="SPARC pipeline" width="720"> |
| </p> |
|
|
| ## What you get |
|
|
| ### SPARC-Risk |
|
|
| | Folder | Model | Description | |
| |---|---|---| |
| | `sparc_risk/` | **SPARC-Risk (canonical)** | Signature-query fusion + H&E. The model reported throughout the paper. | |
| | `image_only/` | **Image-only baseline** | Same backbone, GEP pathway disabled. Use for direct ablation against SPARC-Risk. | |
|
|
| Each folder contains 5 checkpoints — `fold_0_best.pt` through |
| `fold_4_best.pt` — corresponding to the 5-fold cross-validation splits |
| described in the paper and in |
| [`data/mmp_hybrid_splits_v2_20cancer.csv`](https://github.com/aziz-ayed/SPARC/blob/main/data/mmp_hybrid_splits_v2_20cancer.csv). |
|
|
| Every `.pt` carries both `model_state_dict` and the original training |
| `config`, so the model can be rebuilt with one line: |
|
|
| ```python |
| import torch |
| from sparc.models.factory import build_model |
| |
| ckpt = torch.load("sparc_risk/fold_0_best.pt", map_location="cpu", weights_only=False) |
| model = build_model(ckpt["config"]) |
| model.load_state_dict(ckpt["model_state_dict"]) |
| model.eval() |
| ``` |
|
|
| ### SPARC-Map |
|
|
| | Folder | Model | Description | |
| |---|---|---| |
| | `sparc_map/` | **SPARC-Map** | kNN-transformer that predicts 40 hallmark GEP scores per H&E patch from the same H-optimus-1 features used by SPARC-Risk. | |
|
|
| Unlike SPARC-Risk, this ships as a single checkpoint — |
| `knn_transformer_robust_normalized_mse_pearson.pth` — rather than a 5-fold |
| ensemble. |
|
|
| The checkpoint carries the training `args` (hyperparameters), the |
| `model_state_dict`, per-program normalisation stats (`norm_stats`), and the |
| ordered list of 40 GEP program names (`program_names`) the model was |
| trained to predict: |
|
|
| ```python |
| import torch |
| |
| ckpt = torch.load( |
| "sparc_map/knn_transformer_robust_normalized_mse_pearson.pth", |
| map_location="cpu", weights_only=False, |
| ) |
| args = ckpt["args"] # hyperparameters used to build the model |
| program_names = ckpt["program_names"] # the 40 GEP programs, in output order |
| |
| # Build the kNN-transformer (see the training script in the SPARC repo) with |
| # args["hidden_dim"], args["num_layers"], args["num_heads"], args["k_neighbors"], |
| # then: model.load_state_dict(ckpt["model_state_dict"]) |
| ``` |
|
|
| ## Quick start |
|
|
| ```bash |
| # 1. Install the SPARC package |
| git clone https://github.com/aziz-ayed/SPARC.git && cd SPARC |
| conda env create -f environment.yml |
| conda activate sparc |
| |
| # 2. Accept the license on https://huggingface.co/azizayed/SPARC, then: |
| pip install -U "huggingface_hub[cli]" |
| hf auth login |
| hf download azizayed/SPARC --local-dir checkpoints |
| |
| # 3. Inference on an external cohort (e.g. NLST lung) |
| python -m inference.run \ |
| --cohort nlst \ |
| --checkpoint_dir checkpoints/sparc_risk \ |
| --gpus 0,1,2,3 |
| ``` |
|
|
| The download produces: |
|
|
| ``` |
| checkpoints/ |
| ├── sparc_risk/ fold_{0..4}_best.pt |
| ├── image_only/ fold_{0..4}_best.pt |
| └── sparc_map/ knn_transformer_robust_normalized_mse_pearson.pth |
| ``` |
|
|
| ## Architecture (SPARC-Risk) |
|
|
| | Component | Setting | |
| |---|---| |
| | Image backbone | H-optimus-1 (1536-dim) | |
| | Patch size / magnification | 224 px @ 20× | |
| | Max patches per slide | 4096 | |
| | Fusion | Signature-query cross-attention (64-NN, 4 heads) | |
| | Aggregator | Gated attention MIL | |
| | Head | Discrete-time NLL survival, 4 bins | |
| | Cancer conditioning | Per-cancer learned gate | |
| | Hidden dim | 256 | |
| | Trainable params | ≈ 2.6 M | |
| | Optimiser / schedule | Adam, lr 1 × 10⁻⁴, cosine T_max 20 | |
| | Random seed | 1337 | |
| |
| Full config + reproduction recipe: [`configs/sparc_risk.yaml`](https://github.com/aziz-ayed/SPARC/blob/main/configs/sparc_risk.yaml). |
| |
| ## Architecture (SPARC-Map) |
| |
| | Component | Setting | |
| |---|---| |
| | Image backbone | H-optimus-1 (1536-dim), same per-patch features as SPARC-Risk | |
| | Patch size / magnification | 224 px @ 20× | |
| | Spatial context | k-NN patch graph, k = 128 neighbours; coordinate MLP encoder (2 → 64 → 256) | |
| | Encoder | 3-layer pre-norm Transformer, 8 heads, hidden dim 256, MLP ratio 4× | |
| | Output head | 256 → 128 → 40 (per-patch GEP program scores) | |
| | Programs predicted | 40 hallmark / curated gene-expression programs | |
| | Label normalisation | Per-program | |
| | Loss | MSE + Pearson correlation (`mse+pearson`) | |
| | Trainable params | ≈ 2.8 M | |
| | Optimiser | Adam, lr 1 × 10⁻⁴, weight decay 1 × 10⁻² | |
| | Batch size / epochs | 32 / up to 50 (this checkpoint: epoch 38, val R² ≈ 0.66) | |
| |
| ## Training data |
| |
| ### SPARC-Risk |
| |
| 5-fold patient-level cross-validation over **20 TCGA cancer types** |
| (BLCA, BRCA, CESC, COAD, ESCA, GBM, HNSC, KIRC, KIRP, LGG, LIHC, LUAD, |
| LUSC, PAAD, READ, SARC, SKCM, STAD, UCEC, plus a held-out evaluation |
| split). Splits derive from the MMP hybrid scheme of Mahmood et al. and |
| are released alongside the code at |
| [`data/mmp_hybrid_splits_v2_20cancer.csv`](https://github.com/aziz-ayed/SPARC/blob/main/data/mmp_hybrid_splits_v2_20cancer.csv). |
| |
| External validation cohorts (not used for training) — NLST lung, SurGen |
| CRC, Yale breast, ovarian — are described in the paper. |
| |
| ### SPARC-Map |
| |
| Trained on **[HEST-1k](https://arxiv.org/abs/2406.16192)** (Jaume et al.), |
| a public dataset of paired H&E whole-slide images and spatial transcriptomics |
| spots spanning multiple organs and cancer types. Per-spot gene expression is |
| summarised into the 40 hallmark/curated GEP scores used as regression |
| targets, so SPARC-Map learns to predict spatially resolved GEP activity from |
| H&E alone. |
| |
| ## Intended use |
| |
| These weights are intended for **non-commercial biomedical research and |
| education only**. Acceptable uses include: |
| |
| - Reproducing the SPARC paper's results. |
| - Benchmarking against SPARC-Risk in computational-pathology research. |
| - Methodological extensions (new fusion designs, additional cohorts, |
| ablation studies). |
| |
| ## Citation |
| |
| The SPARC paper is currently under review. Once a preprint or accepted |
| version is available, a BibTeX entry will be added here. In the meantime, |
| if you use these weights, please link back to |
| [github.com/aziz-ayed/SPARC](https://github.com/aziz-ayed/SPARC) and |
| contact the corresponding author at <azizayed@mit.edu>. |
| |
| ## License |
| |
| These weights are released under the |
| [Creative Commons Attribution-NonCommercial 4.0 International License |
| (CC BY-NC 4.0)](https://creativecommons.org/licenses/by-nc/4.0/). For |
| commercial licensing, please contact the authors via the corresponding |
| GitHub issues page. |
| |
