| --- |
| 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. |
|
|
