Skip to content
Back to search

STAMP

Solid Tumor Associative Modeling in Pathology

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/katherlab--stamp/badge.svg)](/listings/katherlab--stamp)

HTML

<a href="/listings/katherlab--stamp"><img src="/api/listings/katherlab--stamp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

To setup STAMP you need [uv](https://docs.astral.sh/uv/) 0.12 or newer.

Supported platforms

| | Python | Platforms | |---|---|---| | CPU (`--extra cpu`) | 3.13, 3.14 | Linux x86_64/aarch64, Windows AMD64, Apple Silicon macOS | | CUDA (`--extra gpu`, `--extra gpu_all`) | 3.13, 3.14 | Linux x86_64, Linux aarch64 |

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](#why-uv-is-required)), 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](#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](https://wheels.astral.sh/simple/cu130/) 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](#installation-troubleshooting).

Additional Dependencies

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

> For Ubuntu < 23.10: > ```bash > apt update && apt install -y libgl1-mesa-glx > ``` > > For Ubuntu >= 23.10: > ```bash > 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 280 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # STAMP: A Protocol for Solid Tumor Associative Modeling in Pathology
  2. <img src="docs/STAMP_logo.svg" width="250px" align="right"></img>
  3. ![CI](https://github.com/KatherLab/STAMP/actions/workflows/ci.yml/badge.svg)
  4. [![STAMP • Nature Protocols](https://img.shields.io/badge/Nature%20Protocols%20Paper-gray.svg)](https://www.nature.com/articles/s41596-024-01047-2)
  5. *An efficient, ready‑to‑use workflow from whole‑slide image to biomarker prediction.*
  6. 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.
  7. **Want to start now?** [Jump to Installation](#installation) or [walk through our Getting Started guide](getting-started.md) for a hands-on tutorial.
  8. ## **Why choose STAMP?**
  9. * 🚀 **Scalable**: Run locally or on HPC (SLURM) with the same CLI; built to handle multi‑center cohorts and large WSI collections.
  10. * 🎓 **Beginner‑friendly & expert‑ready**: Zero‑code CLI and YAML config for routine use; optional code‑level customization for advanced research.
  11. * 🧩 **Model‑rich**: Out‑of‑the‑box support for **+20 foundation models** at [tile level](getting-started.md#feature-extraction) (e.g., *Virchow‑v2*, *UNI‑v2*) and [slide level](getting-started.md#slide-level-encoding) (e.g., *TITAN*, *COBRA*).
  12. * 🔬 **Weakly‑supervised**: End‑to‑end MIL with Transformer aggregation for training, cross‑validation and external deployment; no pixel‑level labels required.
  13. * 🧮 **Multi-task learning**: Unified framework for **classification**, **multi-target classification**, **regression**, and **cox-based survival analysis**.
  14. * 📊 **Stats & results**: Built‑in metrics and patient‑level predictions, ready for analysis and reporting.
  15. * 🖼️ **Explainable**: Generates heatmaps and top‑tile exports out‑of‑the‑box for transparent model auditing and publication‑ready figures.
  16. * 🤝 **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.
  17. * 📑 **Peer‑reviewed**: Protocol published in [*Nature Protocols*](https://www.nature.com/articles/s41596-024-01047-2) and validated across multiple tumor types and centers.
  18. * **🔗 MCP Support**: Compatible with Model Context Protocol (MCP) via the \`mcp/\` module, ready for integration into next-gen agentic AI workflows.
  19. ## **Real-World Examples of STAMP in Action**
  20. - **[Squamous Tumors & Survival](https://www.sciencedirect.com/science/article/pii/S0893395225001425):** 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.
  21. - **[Inflammatory Bowel Disease Atlas](https://www.researchsquare.com/article/rs-6443303/v1):** 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.
  22. - **[Foundation Model Benchmarking](https://arxiv.org/pdf/2408.15823):** 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.
  23. - **[Breast Cancer Risk Stratification](https://doi.org/10.1038/s41467-025-57283-x):** 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.
  24. - **[Endometrial Cancer Subtyping](https://www.actscience.org/Portals/0/Translational%20Science%202025/Top%2050%20Posters/TS25_VincentWagner_OralPosterSession.pdf):** 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.
  25. ## Installation
  26. To setup STAMP you need [uv](https://docs.astral.sh/uv/) 0.12 or newer.
  27. ### Supported platforms
  28. | | Python | Platforms |
  29. |---|---|---|
  30. | CPU (`--extra cpu`) | 3.13, 3.14 | Linux x86_64/aarch64, Windows AMD64, Apple Silicon macOS |
  31. | CUDA (`--extra gpu`, `--extra gpu_all`) | 3.13, 3.14 | Linux x86_64, Linux aarch64 |
  32. Python **3.14 is recommended** and is what `.python-version` selects; 3.13 remains
  33. supported. The CUDA builds are pinned to one ABI stack: **CUDA 13.0 with PyTorch
  34. 2.11.0 and TorchVision 0.26.0**.
  35. CI runs the test suite on Linux. macOS is checked for installation and imports
  36. only, so it stays usable for development but is not a tested target.
  37. There is no CUDA build for macOS or Windows. `flash-attn`, `mamba-ssm` and
  38. `causal-conv1d` are only published as pre-built wheels for Linux, and STAMP
  39. refuses to compile them (see [below](#why-uv-is-required)), so a GPU extra on
  40. those platforms fails with a clear resolution error rather than a compiler error.
  41. > [!IMPORTANT]
  42. > uv is required for the GPU workflow. The PyTorch and Astral wheel indexes are
  43. > configured through `[tool.uv.sources]` in `pyproject.toml`, which is
  44. > uv-specific and invisible to other installers. Installing with plain `pip`
  45. > would mean pointing it at
  46. > `https://download.pytorch.org/whl/cu130` and
  47. > `https://wheels.astral.sh/simple/cu130/` yourself, and re-deriving the exact
  48. > pins by hand. See [Why uv is required](#why-uv-is-required).
  49. ### Install or Update uv:
  50. ```bash
  51. # Install uv
  52. curl -LsSf https://astral.sh/uv/install.sh | sh
  53. # Update uv
  54. uv self update
  55. ```
  56. ### Install STAMP from the Repository:
  57. ```bash
  58. git clone https://github.com/KatherLab/STAMP.git
  59. cd STAMP
  60. ```
  61. ```bash
  62. # GPU (CUDA) Installation (excluding conchv1_5, gigapath and musk)
  63. uv sync --extra gpu
  64. source .venv/bin/activate
  65. ```
  66. ```bash
  67. # CPU-only Installation (excluding conchv1_5, gigapath and musk)
  68. uv sync --extra cpu
  69. source .venv/bin/activate
  70. ```
  71. For the full GPU stack, add `conchv1_5`, `gigapath` and `musk`:
  72. ```bash
  73. # GPU (CUDA) Installation - everything
  74. uv sync --extra gpu_all
  75. source .venv/bin/activate
  76. ```
  77. Both GPU extras install **pre-built wheels by default**. `flash-attn`,
  78. `mamba-ssm` and `causal-conv1d` come from the
  79. [Astral wheel index](https://wheels.astral.sh/simple/cu130/) already compiled
  80. against CUDA 13.0 and PyTorch 2.11, so nothing is compiled locally and no CUDA
  81. toolkit needs to be installed to *install* STAMP. You still need an NVIDIA
  82. driver to *run* on a GPU.
  83. > [!NOTE]
  84. > `--extra gpu_prebuilt` is deprecated and now just an alias for
  85. > `--extra gpu_all`, which is pre-built anyway. It will be removed in the next
  86. > breaking release.
  87. If you encounter errors during installation please read Installation Troubleshooting [below](#installation-troubleshooting).
  88. ### Additional Dependencies
  89. > [!IMPORTANT]
  90. > STAMP additionally requires OpenCV dependencies to be installed.
  91. >
  92. > For Ubuntu < 23.10:
  93. > ```bash
  94. > apt update && apt install -y libgl1-mesa-glx
  95. > ```
  96. >
  97. > For Ubuntu >= 23.10:
  98. > ```bash
  99. > apt update && apt install -y libgl1 libglx-mesa0 libglib2.0-0
  100. > ```
  101. ### Why uv is required
  102. The GPU workflow depends on configuration that only uv reads:
  103. * `[tool.uv.sources]` routes `torch` and `torchvision` to
  104. `https://download.pytorch.org/whl/cu130` (or `.../cpu` for the `cpu` extra)
  105. and the three compiled extensions to `https://wheels.astral.sh/simple/cu130/`.
  106. * `[tool.uv.exclude-dependencies]` drops the unconditional CUDA requirements
  107. that the UNI, GigaPath and COBRA forks declare, so a CPU install stays free of
  108. CUDA-only packages.
  109. * `[tool.uv.no-build-package]` forbids source builds of `flash-attn`,
  110. `mamba-ssm` and `causal-conv1d`.
  111. None of this is visible to `pip`, which reads only `[project]`. Installing with
  112. pip would resolve `flash-attn` from PyPI and try to compile it — which is
  113. exactly what this configuration exists to prevent. If you must use pip, you have
  114. to add both indexes yourself and pin the extensions to the same
  115. `+cu.13.0.torch.2.11` local versions listed in `pyproject.toml`.
  116. Source builds of the three extensions are refused on purpose: they are
  117. ABI-locked to one PyTorch build, take a long time, need a matching CUDA toolkit,
  118. and were the most common cause of broken installs. An unsupported platform now
  119. fails during resolution with a clear message instead of part-way through a
  120. compile.
  121. ## Basic Usage
  122. If the installation was successful, running `stamp` in your terminal should yield the following output:
  123. ```
  124. $ stamp
  125. usage: stamp [-h] [--config CONFIG_FILE_PATH] {init,preprocess,encode_slides,encode_patients,train,crossval,deploy,statistics,config,heatmaps} ...
  126. STAMP: Solid Tumor Associative Modeling in Pathology
  127. positional arguments:
  128. {init,preprocess,encode_slides,encode_patients,train,crossval,deploy,statistics,config,heatmaps}
  129. init Create a new STAMP configuration file at the path specified by --config
  130. preprocess Preprocess whole-slide images into feature vectors
  131. encode_slides Encode patch-level features into slide-level embeddings
  132. encode_patients Encode features into patient-level embeddings
  133. train Train a Vision Transformer model
  134. crossval Train a Vision Transformer model with cross validation for modeling.n_splits folds
  135. deploy Deploy a trained Vision Transformer model
  136. statistics Generate AUROCs and AUPRCs with 95%CI for a trained Vision Transformer model
  137. config Print the loaded configuration
  138. heatmaps Generate heatmaps for a trained model
  139. options:
  140. -h, --help show this help message and exit
  141. --config CONFIG_FILE_PATH, -c CONFIG_FILE_PATH
  142. Path to config file. Default: config.yaml
  143. ```
  144. ## Getting Started Guide
  145. For a quick introduction how to run stamp,
  146. check out our [getting started guide](getting-started.md).
  147. ## Reference
  148. If you find our work useful in your research
  149. or if you use parts of this code
  150. please consider citing our [Nature Protocols publication](https://www.nature.com/articles/s41596-024-01047-2):
  151. ```
  152. @Article{ElNahhas2024,
  153. 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},
  154. title={From whole-slide image to biomarker prediction: end-to-end weakly supervised deep learning in computational pathology},
  155. journal={Nature Protocols},
  156. year={2024},
  157. month={Sep},
  158. day={16},
  159. issn={1750-2799},
  160. doi={10.1038/s41596-024-01047-2},
  161. url={https://doi.org/10.1038/s41596-024-01047-2}
  162. }
  163. ```
  164. > [!NOTE]
  165. > This repo contains an updated version of the codebase.
  166. > For a version compatible with the instructions in the paper,
  167. > please check out [version 1 of STAMP][stamp v1].
  168. [stamp paper]: https://www.nature.com/articles/s41596-024-01047-2 "From whole-slide image to biomarker prediction: end-to-end weakly supervised deep learning in computational pathology"
  169. [stamp v1]: https://github.com/KatherLab/STAMP/tree/v1
  170. ## Installation Troubleshooting
  171. #### `flash-attn` / `mamba-ssm` / `causal-conv1d` cannot be installed
  172. These only exist as pre-built wheels for Linux x86_64 and Linux aarch64 on
  173. Python 3.13/3.14. On any other platform uv reports that no compatible version
  174. was found. This is deliberate — STAMP does not fall back to compiling them.
  175. Use `--extra cpu` on macOS and Windows.
  176. #### Triton Errors
  177. If you encounter errors related to the [Triton package like the following](https://github.com/pytorch/pytorch/issues/153737):
  178. ```bash
  179. SystemError: PY_SSIZE_T_CLEAN macro must be defined for '#' formats
  180. ```
  181. Try to delete the triton cache:
  182. ```bash
  183. rm -r ~/.triton
  184. ```
  185. A re-installation might be necessary afterwards.
  186. #### Undefined Symbol Error
  187. An error like the following when importing `flash_attn`, `mamba_ssm` or
  188. `causal_conv1d` means the installed torch does not match the torch the extension
  189. was compiled against:
  190. ```
  191. > import flash_attn_2_cuda as flash_attn_gpu
  192. E ImportError: [...]/.venv/lib/python3.14/site-packages/flash_attn_2_cuda.cpython-314-x86_64-linux-gnu.so: undefined symbol: _ZN3c105ErrorC2ENS_14SourceLocationENSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEE
  193. ```
  194. This should no longer happen, because the extension versions carry the PyTorch
  195. build in their version string (`+cu.13.0.torch.2.11`) and the lockfile pins them
  196. together with torch. If you do hit it, you are almost certainly in an
  197. environment left over from an older STAMP release. Check what is installed:
  198. ```bash
  199. uv run python scripts/verify_installed_stack.py --expect-cuda
  200. ```
  201. and rebuild the environment from the lockfile:
  202. ```bash
  203. rm -rf .venv
  204. uv sync --locked --extra gpu_all
  205. ```
  206. ## Reproducibility
  207. > [!NOTE]
  208. > We use a central `Seed` utility to set seeds for PyTorch, NumPy, and Python’s `random`. This makes data loading and model initialization reproducible. Always call `Seed.set(seed)` once at startup.
  209. > We do not enable [`torch.use_deterministic_algorithms()`](https://pytorch.org/docs/stable/notes/randomness.html#reproducibility) because it can cause large performance drops. Expect runs with the same seed to follow the same training trajectory, but not bit-for-bit identical low-level kernels.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.