PathSculpt

PathSculpt is a prompt-guided patch selection framework for whole-slide image classification. It uses pathology text concepts to score patches, samples informative and diverse patch tokens with differentiable Gumbel Top-K selection, and feeds the selected tokens into a frozen slide-level foundation model such as TITAN or PRISM.

This repository is a cleaned open-source release derived from the research code. It keeps the training path focused on:

• PathSculpt-TITAN
• PathSculpt-PRISM
• classification with external-cohort evaluation
• H5 patch-feature inputs with coordinates

Installation

Python 3.10 or 3.11 is recommended.

conda create -n pathsculpt python=3.10 -y
conda activate pathsculpt

cd /path/to/PathSculpt-open-source
pip install -r requirements.txt

PathSculpt also imports CONCH for text encoding. Install CONCH following the upstream instructions and provide a checkpoint when needed:

export CONCH_CHECKPOINT=/path/to/conch.bin

The slide encoders are loaded through Hugging Face transformers by default:

• TITAN: MahmoodLab/TITAN
• PRISM: paige-ai/Prism

Some models may require Hugging Face access approval or authentication:

huggingface-cli login

You can also pass a local compatible encoder directory:

export ENCODER_NAME=/path/to/local/TITAN_or_PRISM

Data Preparation

Raw WSIs and extracted features are not included. Prepare:

1. WSI-derived patch-feature H5 files for the primary slide encoder input.
2. Patch-feature H5 files in the CONCH text-embedding space for prompt-guided scoring.
3. Label CSV files.
4. Split CSV files.
5. Concept prompt JSON files.

We recommend using TRIDENT for WSI preprocessing and feature extraction:

https://github.com/mahmoodlab/TRIDENT

Expected Feature Layout

Configure feature roots in scripts/tasks.json. The provided placeholder layout is:

data/TCGA-BRCA/features/20x_512px_0px_overlap/
|-- features_conch_v15/
|   |-- <slide_id>.h5
|   `-- ...
`-- features_conch_v1/
    |-- <slide_id>.h5
    `-- ...

Each H5 file must contain:

features: float array, shape [num_patches, feature_dim]
coords:   int array,   shape [num_patches, 2]

Optional but recommended:

coords.attrs["patch_size_level0"]

For pathsculpt_titan, the primary feature directory should match the TITAN slide encoder input. For pathsculpt_prism, the primary feature directory should match the PRISM slide encoder input. The secondary feature directory is used for concept-guided patch scoring and must live in the same embedding space as the CONCH text anchors.

Labels, Splits, and Tasks

Each label CSV should contain:

slide_id,case_id,label

Each split CSV should contain:

train,val,test

Training and validation rows are read from the training cohort label CSV. The test column is read from the external cohort label CSV. Edit scripts/tasks.json to point to your local labels, feature directories, and split directory.

Concept Prompts

PathSculpt uses concept prompts with three groups:

{
  "cls_prompts": [["class 0 names"], ["class 1 names"]],
  "desc_cell": [["class 0 cellular descriptions"], ["class 1 cellular descriptions"]],
  "desc_tissue": [["class 0 tissue descriptions"], ["class 1 tissue descriptions"]]
}

The default BRCA ER status prompt file is provided at text_prompts/brca_er_2l_gpt54_v2.json.

Training

PathSculpt-TITAN

CONCH_CHECKPOINT=/path/to/conch.bin \
bash scripts/pathsculpt_titan.sh BRCA_ER conch_v15 conch_v1 gpt54

PathSculpt-PRISM

CONCH_CHECKPOINT=/path/to/conch.bin \
bash scripts/pathsculpt_prism.sh BRCA_ER virchow conch_v1 gpt54

Useful environment overrides:

CUSTOM_LR=2e-4
CUSTOM_EPOCHS=10
DS_NUM=256
IS_TEMP=1.0
TEXT_CTX=2
W_PROMPT=1.0
TOME=0
OVERWRITE=1

For a one-fold smoke test, provide splits_0.csv and run:

K_FOLDS=1 OVERWRITE=1 \
CONCH_CHECKPOINT=/path/to/conch.bin \
bash scripts/pathsculpt_titan.sh BRCA_ER conch_v15 conch_v1 gpt54

Outputs

Results are written to:

results/<exp_code>/s<seed>_<test_name>/

Expected files:

training_log.log
experiment_<exp_code>.txt
split_<fold>_results_test.pkl
summary.csv

summary.csv contains:

test_auroc,test_f1,test_kappa,test_bacc

Repository Notes

This release intentionally excludes:

• raw WSIs and extracted features
• model checkpoints and local foundation-model weights
• experiment logs and result folders
• private agent/autotune/Notion workflows

Large files are ignored by .gitignore.

License

This project is released under the MIT License. See LICENSE.

Acknowledgments

This project builds on tools and model interfaces from:

• CLAM: https://github.com/mahmoodlab/CLAM
• CONCH: https://github.com/mahmoodlab/CONCH
• TRIDENT: https://github.com/mahmoodlab/TRIDENT
• TITAN: https://huggingface.co/MahmoodLab/TITAN
• PRISM: https://huggingface.co/paige-ai/Prism