Blame for README.md

---
library_name: pytorch
pipeline_tag: feature-extraction
tags:
  - computational-pathology
  - spatial-proteomics
  - histopathology
  - colorectal-cancer
  - multimodal
---

# CIPHER model weights

This repository contains the released weights for CIPHER
(Cross-Panel Integration of Proteomics for Histopathology-based Ecosystem
Representation). CIPHER learns protein-defined tissue representations from
spatial proteomics and transfers them to routine H&E images.

The implementation and tutorials are maintained at
https://github.com/MedCAI/CIPHER-public.

> CIPHER is research software and has not been validated as a clinical
> decision-support system.

## Files

| File | Purpose | Size |
|---|---|---:|
| `cipher_sp/cipher_sp_weights.pt` | CIPHER-SP spatial-proteomics checkpoint | 1,474,240,075 bytes |
| `cipher_he/cipher_he_lora.pt` | CIPHER-HE LoRA adapter | 9,992,877 bytes |
| `metadata/share_schema.json` | Shared CODEX/ORION channel schema for CIPHER-SP | 1,761 bytes |

## Download

Install `huggingface_hub`, then download both weights into the layout expected by the GitHub repository:

```bash
python -m pip install --upgrade huggingface_hub
hf download Ceilinghans/CIPHER cipher_sp/cipher_sp_weights.pt cipher_he/cipher_he_lora.pt --local-dir artifacts/models
```

Or download individual files from Python:

```python
from huggingface_hub import hf_hub_download

sp_checkpoint = hf_hub_download(
    repo_id="Ceilinghans/CIPHER",
    filename="cipher_sp/cipher_sp_weights.pt",
)
he_adapter = hf_hub_download(
    repo_id="Ceilinghans/CIPHER",
    filename="cipher_he/cipher_he_lora.pt",
)
```

## CIPHER-SP inference

Install the CIPHER-SP package from the code repository, prepare a manifest as
described in `CIPHER-SP/README.md`, and run:

```bash
python CIPHER-SP/extract_features.py \
  --checkpoint artifacts/models/cipher_sp/cipher_sp_weights.pt \
  --manifest CIPHER-SP/metadata/manifest.csv \
  --schema CIPHER-SP/metadata/share_schema.json \
  --out_pt outputs/patch_features.pt \
  --feature_type mean_patch \
  --device cuda
```

The input TIFF patches must have shape `channels x 224 x 224`, with channels
ordered according to the schemas in the code repository.

## CIPHER-HE inference

CIPHER-HE is a LoRA adapter and does not include the UNI2-h backbone. Obtain
UNI2-h base weights separately under their original access and license terms,
then run:

```bash
cipher-he /path/to/he_patches --recursive \
  --output outputs/features.pt \
  --feature-type projected \
  --checkpoint artifacts/models/cipher_he/cipher_he_lora.pt \
  --base-weights /path/to/UNI2-h/pytorch_model.bin
```

Use `--feature-type projected` for normalized 512-dimensional cross-modal
features or `--feature-type backbone` for 1,536-dimensional adapted UNI2-h
features.

## Provenance and limitations

- The CIPHER-HE file is the epoch-10 LoRA training checkpoint. Optimizer state,
  environment-specific filesystem paths and cohort-split identifiers were removed
  without changing the trainable tensor values.
- Exact manuscript-training provenance of the CIPHER-SP checkpoint is not
  verified. Its embedded metadata reports epoch 9 and a 30-epoch,
  batch-size-128 recipe, whereas the manuscript describes 50 epochs and batch
  size 256. The audited implementation also uses one shared marker-decoder
  parameter set for both platforms. Do not present this checkpoint as an exact
  reproduction of manuscript training.
- Neither checkpoint contains patient, slide, patch or image data.
- These are PyTorch `.pt` files. PyTorch checkpoints may use pickle-based
  deserialization; download them only from the official repository.

## Citation

If you use these weights, please cite the accompanying manuscript:

> *Spatial proteomics-informed histopathology identifies prognostic tissue
> ecosystems in colorectal cancer.*

Formal citation details will be added after publication.