A protocol for Solid Tumor Associative Modeling in Pathology. This repository contains the accompanying code for the steps described in the Nature Protocols paper:

From whole-slide image to biomarker prediction: end-to-end weakly supervised deep learning in computational pathology

The code can be executed either in a local environment, or in a containerized environment (preferred in clusters).

For setting up a local environment, note that the following steps are for Ubuntu Linux systems. For other operating systems such as Windows, MacOS or other Linux distributions, it is recommend to use the containerized environment as described below.

First, install OpenSlide using either the command below or the official installation instructions:

apt update && apt install -y openslide-tools libgl1-mesa-glx # libgl1-mesa-glx is needed for OpenCV

Second, install conda on your local computer, create an environment with Python 3.10, and activate it:

conda create -n stamp python=3.10
conda activate stamp
conda install -c conda-forge libstdcxx-ng=12

Then, install the STAMP package via pip:

pip install git https://github.com/KatherLab/STAMP

Once installed, you will be able to run the command line interface directly using the stamp command.

Next, initialize STAMP and obtain the required configuration file, config.yaml, in your current working directory, by running the following command:

stamp init

To download required resources such as the weights of the feature extractor, run the following command:

stamp setup

First, install Go and Singularity on your local machine using the official installation instructions. Note that the High-Performance Cluster (HPC) has Go and Singularity pre-installed, and do not require installation.

Second, build the container first on your local machine with (fake) root access:

sudo singularity build STAMP_container.sif setup/container.def

Note that the container is approximately 6 GB in size.

Alternatively, lab members with access to the ZIH server can download the pre-built container into the base STAMP directory from:

/glw/ekfz_proj/STAMP_container.sif

Finally, to download required resources such as the weights of the CTransPath feature extractor, run the following command in the base directory of the protocol:

singularity run --nv -B /mnt:/mnt STAMP_container.sif "stamp --config /path/to/config.yaml setup"

Note that the binding of filesystems (-B) should be adapted to your own system. GPU acceleration (--nv) should be enabled if GPUs are available in the system, but is optional.

Available commands are:

stamp init       # create a new configuration file in the current directory
stamp setup      # download required resources
stamp config     # print resolved configuration
stamp preprocess # normalization and feature extraction with CTransPath
stamp crossval   # train n_splits models using cross-validation
stamp train      # train single model
stamp deploy     # deploy a model on another test set
stamp statistics # compute stats including ROC curves
stamp heatmaps   # generate heatmaps

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