STAMP: A Protocol for Solid Tumor Associative Modeling in Pathology

An efficient, ready‑to‑use workflow from whole‑slide image to biomarker prediction.

STAMP is an end‑to‑end, weakly‑supervised deep‑learning pipeline that helps discover and evaluate candidate image‑based biomarkers from gigapixel histopathology slides, no pixel‑level annotations required. Backed by a peer‑reviewed protocol and used in multi‑center studies across several tumor types, STAMP lets clinical researchers and machine‑learning engineers collaborate on reproducible computational‑pathology projects with a clear, structured workflow.

Want to start now? Jump to Installation or walk through our Getting Started guide for a hands-on tutorial.

Why choose STAMP?

• 🚀 Scalable: Run locally or on HPC (SLURM) with the same CLI; built to handle multi‑center cohorts and large WSI collections.
• 🎓 Beginner‑friendly & expert‑ready: Zero‑code CLI and YAML config for routine use; optional code‑level customization for advanced research.
• 🧩 Model‑rich: Out‑of‑the‑box support for +20 foundation models at tile level (e.g., Virchow‑v2, UNI‑v2) and slide level (e.g., TITAN, COBRA).
• 🔬 Weakly‑supervised: End‑to‑end MIL with Transformer aggregation for training, cross‑validation and external deployment; no pixel‑level labels required.
• 🧮 Multi-task learning: Unified framework for classification, multi-target classification, regression, and cox-based survival analysis.
• 📊 Stats & results: Built‑in metrics and patient‑level predictions, ready for analysis and reporting.
• 🖼️ Explainable: Generates heatmaps and top‑tile exports out‑of‑the‑box for transparent model auditing and publication‑ready figures.
• 🤝 Collaborative by design: Clinicians drive hypothesis & interpretation while engineers handle compute; STAMP’s modular CLI mirrors real‑world workflows and tracks every step for full reproducibility.
• 📑 Peer‑reviewed: Protocol published in Nature Protocols and validated across multiple tumor types and centers.
• 🔗 MCP Support: Compatible with Model Context Protocol (MCP) via the `mcp/` module, ready for integration into next-gen agentic AI workflows.

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 0.12 or newer.

Supported platforms

Python 3.14 is recommended and is what .python-version selects; 3.13 remains supported. The CUDA builds are pinned to one ABI stack: CUDA 13.0 with PyTorch 2.11.0 and TorchVision 0.26.0.

CI runs the test suite on Linux. macOS is checked for installation and imports only, so it stays usable for development but is not a tested target.

There is no CUDA build for macOS or Windows. flash-attn, mamba-ssm and causal-conv1d are only published as pre-built wheels for Linux, and STAMP refuses to compile them (see below), so a GPU extra on those platforms fails with a clear resolution error rather than a compiler error.

[!IMPORTANT] uv is required for the GPU workflow. The PyTorch and Astral wheel indexes are configured through [tool.uv.sources] in pyproject.toml, which is uv-specific and invisible to other installers. Installing with plain pip would mean pointing it at https://download.pytorch.org/whl/cu130 and https://wheels.astral.sh/simple/cu130/ yourself, and re-deriving the exact pins by hand. See Why uv is required.

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

For the full GPU stack, add conchv1_5, gigapath and musk:

# GPU (CUDA) Installation - everything
uv sync --extra gpu_all
source .venv/bin/activate

Both GPU extras install pre-built wheels by default. flash-attn, mamba-ssm and causal-conv1d come from the Astral wheel index already compiled against CUDA 13.0 and PyTorch 2.11, so nothing is compiled locally and no CUDA toolkit needs to be installed to install STAMP. You still need an NVIDIA driver to run on a GPU.

[!NOTE] --extra gpu_prebuilt is deprecated and now just an alias for --extra gpu_all, which is pre-built anyway. It will be removed in the next breaking release.

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

Why uv is required

The GPU workflow depends on configuration that only uv reads:

• [tool.uv.sources] routes torch and torchvision to https://download.pytorch.org/whl/cu130 (or .../cpu for the cpu extra) and the three compiled extensions to https://wheels.astral.sh/simple/cu130/.
• [tool.uv.exclude-dependencies] drops the unconditional CUDA requirements that the UNI, GigaPath and COBRA forks declare, so a CPU install stays free of CUDA-only packages.
• [tool.uv.no-build-package] forbids source builds of flash-attn, mamba-ssm and causal-conv1d.

None of this is visible to pip, which reads only [project]. Installing with pip would resolve flash-attn from PyPI and try to compile it — which is exactly what this configuration exists to prevent. If you must use pip, you have to add both indexes yourself and pin the extensions to the same +cu.13.0.torch.2.11 local versions listed in pyproject.toml.

Source builds of the three extensions are refused on purpose: they are ABI-locked to one PyTorch build, take a long time, need a matching CUDA toolkit, and were the most common cause of broken installs. An unsupported platform now fails during resolution with a clear message instead of part-way through a compile.

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 AU