README.md

---
license: cc-by-nc-nd-4.0
library_name: pytorch
tags:
  - computational-pathology
  - whole-slide-image
  - molecular-prediction
  - survival-analysis
  - conch
  - pathlupi
---

# PathLUPI Checkpoints

Official model checkpoints for **PathLUPI**, introduced in [Genome-Anchored Foundation Model Embeddings Improve Molecular Prediction from Histology Images](https://arxiv.org/abs/2506.19681).

PathLUPI uses transcriptomic profiles as privileged information during training to learn genome-anchored representations from histology. At inference time, the model requires only WSI features extracted with [CONCH](https://github.com/mahmoodlab/CONCH); transcriptomic data are not required.

For model code, data preparation, and inference instructions, see the [PathLUPI GitHub repository](https://github.com/ChengJin-git/PathLUPI).

## Available Checkpoints

This repository provides the five cross-validation folds for 37 TCGA-trained tasks reported in the paper:

- **24 biomarker and molecular prediction tasks**
- **13 survival prognosis tasks**
- **185 checkpoint files in total**

External cohorts in the paper were evaluated with the checkpoint for the corresponding TCGA-trained task and therefore do not require separate checkpoint files.

### Biomarker Prediction

| Cancer type | Task |
|---|---|
| BLCA | FGFR3 mutation |
| BRCA | ER, HER2, PIK3CA, PR, TNBC, TP53 |
| CRC | BRAF, KRAS, TP53 |
| GBMLGG | IDH1 mutation |
| LIHC | TP53 mutation |
| LUAD | EGFR, KRAS, TP53 |
| NSCLC | Tumor mutation burden (TMB) |
| SKCM | BRAF mutation |

### Molecular Subtyping

| Directory | Cohort |
|---|---|
| `BLCA_MolSub` | Bladder cancer |
| `BRCA_MolSub` | Breast cancer |
| `CRC_MolSub` | Colorectal cancer |
| `GBMLGG_MolSub` | Glioma |
| `HNSC_MolSub` | Head and neck cancer |
| `PanGI_MolSub` | Pan-gastrointestinal cancers |
| `UCEC_MolSub` | Endometrial cancer |

### Survival Prognosis

`BLCA`, `BRCA`, `CRC`, `GBM`, `HNSC`, `KIRC`, `LGG`, `LIHC`, `LUAD`, `LUSC`, `SKCM`, `STAD`, and `UCEC`.

GBM and LGG are provided as separate survival models, consistent with the final analysis in the paper.

## Repository Structure

```text
PathLUPI/
├── subtyping/
│   ├── BRCA_ERSub/
│   │   ├── fold0.pth.tar
│   │   ├── fold1.pth.tar
│   │   ├── fold2.pth.tar
│   │   ├── fold3.pth.tar
│   │   └── fold4.pth.tar
│   └── ...
└── survival/
    ├── GBM/
    │   ├── fold0.pth.tar
    │   └── ...
    ├── LGG/
    │   ├── fold0.pth.tar
    │   └── ...
    └── ...
```

## Download

Install the Hugging Face CLI:

```bash
pip install -U huggingface_hub
```

Download all checkpoints:

```bash
hf download peterjin0703/PathLUPI \
  --local-dir ./checkpoints/PathLUPI
```

Download one task only, for example BRCA ER prediction:

```bash
hf download peterjin0703/PathLUPI \
  --include "subtyping/BRCA_ERSub/*" \
  --local-dir ./checkpoints/PathLUPI
```

Download one survival model only:

```bash
hf download peterjin0703/PathLUPI \
  --include "survival/GBM/*" \
  --local-dir ./checkpoints/PathLUPI
```

## Checkpoint Format

Each file is a PyTorch `state_dict` containing model weights only. Validation metrics, training epochs, optimizer states, and other training metadata are not stored in the checkpoint.

```python
import torch

state_dict = torch.load(
    "checkpoints/PathLUPI/subtyping/BRCA_ERSub/fold0.pth.tar",
    map_location="cpu",
    weights_only=True,
)
model.load_state_dict(state_dict)
model.eval()
```

The model architecture and task-specific construction code are provided in the [GitHub repository](https://github.com/ChengJin-git/PathLUPI).

## CONCH Dependency

These checkpoints operate on WSI features extracted using CONCH. The original CONCH weights are not redistributed here. Please obtain them directly from the [MahmoodLab CONCH model page](https://huggingface.co/MahmoodLab/CONCH) and follow its license and access requirements.

## Citation

```bibtex
@article{jin2025pathlupi,
  title={Genome-Anchored Foundation Model Embeddings Improve Molecular Prediction from Histology Images},
  author={Jin, Cheng and Zhou, Fengtao and Yu, Yunfang and Ma, Jiabo and Wang, Yihui and Xu, Yingxue and others},
  journal={arXiv preprint arXiv:2506.19681},
  year={2025}
}
```

## License

The PathLUPI checkpoints are released under the [CC BY-NC-ND 4.0](https://creativecommons.org/licenses/by-nc-nd/4.0/) license. CONCH is distributed separately under its own terms.