immuno-compass 2.0.4

COMPASS: Generalizable AI predicts immunotherapy outcomes across cancers and treatments.

COMPASS Reproducibility (Pretraining from Scratch & Downstream Fine-Tuning)

This branch provides a fully reproducible pipeline for the COMPASS model, including pretraining from scratch and fine-tuning on downstream immunotherapy response datasets.

---

🧩 Step 1: Download Pretraining Datasets

TCGA Dataset

This dataset contains preprocessed TCGA transcriptomic profiles used for COMPASS pretraining. To facilitate reproducibility and efficient execution, we provide an immune-focused subset of 2,475 genes, which is sufficient to run all pretraining scripts in this repository.

After downloading the dataset from Figshare, please organize the files under the data/ directory with the following structure:

data/
└── TCGA/
    ├── GENE.TABLE
    ├── TCGA.PATIENT.PROCESSED.TABLE
    ├── TCGA.PATIENT.TABLE
    └── TCGA.TPM.TABLE

---

ITRP Dataset (Alternative / Downstream Fine-Tuning)

The ITRP.zip archive contains two serialized pandas tables:

• ITRP.TPM.TABLE — gene-level RNA-seq TPM matrix
• ITRP.PATIENT.TABLE — patient metadata (cancer type, therapy, response labels)

This dataset integrates 1,133 patients from 16 immunotherapy cohorts, all standardized using the COMPASS preprocessing pipeline.

---

Reproducing Datasets from Raw Data (Optional)

If you prefer to regenerate the datasets from raw sources, please refer to:

• TCGA preprocessing pipeline https://github.com/mims-harvard/COMPASS-web/tree/main/TCGA_dataset_processing

• ITRP mRNA pipeline https://github.com/mims-harvard/COMPASS-web/tree/main/mRNA_pipeline

---

🧠 Step 2: Install COMPASS

# IMPORTANT:
# If you are pretraining COMPASS from scratch,
# you MUST use this specific version
pip install immuno-compass==2.0.4

---

⚙️ Step 3: Run Pretraining from Scratch

Go to the run_scripts folder, Open and execute the following notebook:

01_pretraining.ipynb

Note The example notebook uses the TCGA-2475 gene subset for faster execution and reduced GPU memory usage.

---

🔬 Step 4: Run Downstream Fine-Tuning

You can either run the notebooks interactively or execute them sequentially via scripts.

Below is an example using nbconvert (tested on V100 GPU):

jupyter nbconvert --to notebook --execute 01_loco_nft.ipynb --output 01_loco_nft.ipynb
jupyter nbconvert --to notebook --execute 02_loco_lft.ipynb --output 02_loco_lft.ipynb
jupyter nbconvert --to notebook --execute 03_loco_pft.ipynb --output 03_loco_pft.ipynb
jupyter nbconvert --to notebook --execute 04_loco_fft.ipynb --output 04_loco_fft.ipynb
jupyter nbconvert --to notebook --execute 05_loco_lgr.ipynb --output 05_loco_lgr.ipynb
jupyter nbconvert --to notebook --execute 06_analysis_loco.ipynb --output 06_analysis_loco.ipynb

---

📌 Notes

• This repository is intended for methodological reproducibility, not for matching a single reported checkpoint.
• For close reproducibility, use the same weight initialization and document the GPU and PyTorch versions.
• Minor numerical differences may occur due to hardware, CUDA versions, or random seeds.
• For best reproducibility, fix random seeds and document GPU / PyTorch versions.
• Minor numerical differences may occur due to variations in hardware setup, CUDA version and GPU configuration, or ML weight initialization.