PathML is a Python library for performing deep learning image analysis on whole-slide images (WSIs), including deep tissue, artefact, and background filtering, tile extraction, model inference, model evaluation and more. This repository serves to teach users how to apply PathML on both a classification and a segmentation example problem from start to finish using best practices.
Install PathML by cloning its repository:
git clone https://github.com/markowetzlab/pathml
PathML is best run inside an Anaconda environment. Once you have installed Anaconda, you can create pathml-env, a conda environment containing all of PathML's dependencies, then activate that environment. Make sure to adjust the path to your local path to the pathml repository:
conda env create -f /path/to/pathml/pathml-environment.yml
conda activate pathml-env
Note that pathml-environment.yml installs Python version 3.7, PyTorch version 1.4, Torchvision version 0.5, and CUDA version 10.0. Stable versions above these should also work as long as the versions are cross-compatible. Be sure that the CUDA version matches the version installed on your GPU; if not, either update your GPU's CUDA or change the cudatoolkit line of pathml-environment.yml to match your GPU's version before creating pathml-env.
Some users have run into an error message saying that something from libvips is missing when PathML tries to import pyvips. This is because on some operating systems, the pip install of pyvips performed in the conda env create command leads to a flawed pyvips build. To solve this issue, also install pyvips using conda in pathml-env:
conda install -c conda-forge pyvips
For users who don't wish to use conda, PathML can also be installed via pip. To do so, navigate to to the pathml directory containing setup.py, and run the following command:
pip install -e .
First clone this repository:
git clone https://github.com/markowetzlab/pathml-tutorial
The tutorial uses an example subset lymph node WSIs from the CAMELYON16 challenge. Some of these WSIs contain breast cancer metastases and the goal of the tutorial is to use PathML to train deep learning models to identify metastasis-containing slides and slide regions, and then to evaluate the performance of those models.
Create a directory called wsi_data where there is at least 38 GB of disk space. Download the following 18 WSIs from the CAMELYON16 dataset into wsi_data:
normal/normal_001.tifnormal/normal_010.tifnormal/normal_028.tifnormal/normal_037.tifnormal/normal_055.tifnormal/normal_074.tifnormal/normal_111.tifnormal/normal_141.tifnormal/normal_160.tiftumor/tumor_009.tiftumor/tumor_011.tiftumor/tumor_036.tiftumor/tumor_039.tiftumor/tumor_044.tiftumor/tumor_046.tiftumor/tumor_058.tiftumor/tumor_076.tiftumor/tumor_085.tif
Install Jupyter notebook into pathml-env:
conda install -c conda-forge notebook
Now that the requisite software and data have been downloaded, you are ready to begin the tutorial, which is contained in the Jupyter notebook pathml-tutorial.ipynb in this repository. Start notebook and then navigate to that document in the interface:
jupyter notebook
Once up and running, pathml-tutorial.ipynb contains instructions for running the tutorial. For instructions on running Jupyter notebooks, see the Jupyter documentation.
The results of a completed tutorial run can be found here.
The complete documentation for PathML including its API reference can be found here.
Note that this is prerelease software. Please use accordingly.