Real-World Examples of STAMP in Action

• Squamous Tumors & Survival: In a multi-cohort study spanning four squamous carcinoma types (head & neck, esophageal, lung, cervical), STAMP was used to extract slide-level features for a deep learning model that predicted patient survival directly from H&E whole-slide images.

• Inflammatory Bowel Disease Atlas: In a 1,002-patient multi-center IBD study, all histology slides were processed with the STAMP workflow, enabling a weakly-supervised MIL model to accurately predict histologic disease activity scores from H&E tissue sections.

• Foundation Model Benchmarking: A large-scale evaluation of 19 pathology foundation models built its pipeline on STAMP (v1.1.0) for standardized WSI tiling and feature extraction, demonstrating STAMP’s utility as an open-source framework for reproducible model training across diverse cancer biomarkers.

• Breast Cancer Risk Stratification: In an international early breast cancer study, STAMP performed slide tessellation and color normalization (e.g. 1.14 µm/px resolution, Macenko norm) as part of a multimodal transformer pipeline to predict recurrence risk (Oncotype DX scores) from pathology images.

• Endometrial Cancer Subtyping: A recent endometrial cancer project employed a modified STAMP pipeline with a pre-trained vision transformer (Virchow2) to predict molecular tumor subtypes directly from H&E slides, achieving strong diagnostic performance in cross-validation.

Installation

To setup STAMP you need uv.

[!IMPORTANT] We use the experimental match runtime feature of uv which was introduced in version 0.8.5. Please empty your triton cache before installing STAMP: rm -r ~/.triton.

Install or Update uv:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Update uv
uv self update

Install STAMP from the Repository:

git clone https://github.com/KatherLab/STAMP.git
cd STAMP

# GPU (CUDA) Installation (excluding conchv1_5, gigapath and musk)

uv sync --extra gpu
source .venv/bin/activate

# CPU-only Installation (excluding conchv1_5, gigapath and musk)

uv sync --extra cpu
source .venv/bin/activate

[!CAUTION] In the next step we will build flash-attn, this might take an extended amount of time and consume a lot of RAM and CPU time!

Please make sure you have Nvidia CUDA Toolkit 13.0 installed! You must use Nvidia Driver version 580 or newer!

The nvcc --version command must indicate that 13.0 is installed and is currently in PATH: Cuda compilation tools, release 13.0, V13.0.88.

If you get another version or Command 'nvcc' not found, add it to the PATH:

export CUDA_HOME=/usr/local/cuda-13.0
export PATH="${CUDA_HOME}/bin:$PATH"

Run nvcc --version to ensure flash-attn will be built for CUDA 13.0

# GPU (CUDA) Installation - building flash-attn for supporting conchv1_5, gigapath and musk

MAX_JOBS=2 uv sync --extra gpu_all # to speed up the build time increase max_jobs! This might use more RAM!
source .venv/bin/activate

If you encounter errors during installation please read Installation Troubleshooting below.

Additional Dependencies

[!IMPORTANT] STAMP additionally requires OpenCV dependencies to be installed.

For Ubuntu < 23.10:

apt update && apt install -y libgl1-mesa-glx

For Ubuntu >= 23.10:

apt update && apt install -y libgl1 libglx-mesa0 libglib2.0-0

Basic Usage

If the installation was successful, running stamp in your terminal should yield the following output:

$ stamp
usage: stamp [-h] [--config CONFIG_FILE_PATH] {init,preprocess,encode_slides,encode_patients,train,crossval,deploy,statistics,config,heatmaps} ...

STAMP: Solid Tumor Associative Modeling in Pathology

positional arguments:
  {init,preprocess,encode_slides,encode_patients,train,crossval,deploy,statistics,config,heatmaps}
    init                Create a new STAMP configuration file at the path specified by --config
    preprocess          Preprocess whole-slide images into feature vectors
    encode_slides       Encode patch-level features into slide-level embeddings
    encode_patients     Encode features into patient-level embeddings
    train               Train a Vision Transformer model
    crossval            Train a Vision Transformer model with cross validation for modeling.n_splits folds
    deploy              Deploy a trained Vision Transformer model
    statistics          Generate AUROCs and AUPRCs with 95%CI for a trained Vision Transformer model
    config              Print the loaded configuration
    heatmaps            Generate heatmaps for a trained model

options:
  -h, --help            show this help message and exit
  --config CONFIG_FILE_PATH, -c CONFIG_FILE_PATH
                        Path to config file. Default: config.yaml

Getting Started Guide

For a quick introduction how to run stamp, check out our getting started guide.

Reference

If you find our work useful in your research or if you use parts of this code please consider citing our Nature Protocols publication:

@Article{ElNahhas2024,
  author={El Nahhas, Omar S. M. and van Treeck, Marko and W{\"o}lflein, Georg and Unger, Michaela and Ligero, Marta and Lenz, Tim and Wagner, Sophia J. and Hewitt, Katherine J. and Khader, Firas and Foersch, Sebastian and Truhn, Daniel and Kather, Jakob Nikolas},
  title={From whole-slide image to biomarker prediction: end-to-end weakly supervised deep learning in computational pathology},
  journal={Nature Protocols},
  year={2024},
  month={Sep},
  day={16},
  issn={1750-2799},
  doi={10.1038/s41596-024-01047-2},
  url={https://doi.org/10.1038/s41596-024-01047-2}
}

[!NOTE] This repo contains an updated version of the codebase. For a version compatible with the instructions in the paper, please check out version 1 of STAMP.

Installation Troubleshooting

[!NOTE] Installing the GPU version of STAMP might force the compilation of the flash-attn package (as well as mamba-ssm and causal_conv1d). This can take a long time and requires a lot of memory. You can limit the number of parallel compilation jobs by setting the MAX_JOBS environment variable before running the installation command, e.g. `MAX_JOBS=4 uv s