Installing and getting started#
Prerequisites#
WSInfer supports Python 3.8+ and has been tested on Windows, macOS, and Linux.
WSInfer can be installed using pip or conda. WSInfer will install PyTorch automatically
if it is not installed, but this may not install GPU-enabled PyTorch even if a GPU is available.
For this reason, install PyTorch before installing WSInfer.
Install PyTorch first#
Please see PyTorch’s installation instructions
for help installing PyTorch. The installation instructions differ based on your operating system
and choice of pip or conda. Thankfully, the instructions provided
by PyTorch also install the appropriate version of CUDA. We refrain from including code
examples of installation commands because these commands can change over time. Please
refer to PyTorch’s installation instructions
for the most up-to-date instructions.
You will need a new-enough driver for your NVIDIA GPU. Please see this version compatibility table for the minimum versions required for different CUDA versions.
To test whether PyTorch can detect your GPU, check that this code snippet prints True
python -c 'import torch; print(torch.cuda.is_available())'
If your GPU is not available but you have a GPU, you can test if you installed a GPU-enabled PyTorch
python -c 'import torch; print(torch.version.cuda)'
If that command does not print a version string (e.g., 11.7, 12.1), then you probably installed a CPU-only PyTorch. Re-install PyTorch with CUDA support.
Another thing to test is that the environment variable CUDA_VISIBLE_DEVICES is set. I (Jakub) have mine set to “0”
because I have one GPU on my machine. If it is set to something other than “0”, then PyTorch will not be able to
detect the GPU.
Install WSInfer#
WSInfer can be installed with pip or conda (from conda-forge). In both cases, you get
the wsinfer command line tool and Python package.
Pip#
To install the latest stable version of WSInfer, use
python -m pip install wsinfer
To check the installation, type
wsinfer --help
To install the latest unstable version of WSInfer, use
python -m pip install git+https://github.com/SBU-BMI/wsinfer
Conda#
To install the latest stable version of WSInfer with conda, use
conda install -c conda-forge wsinfer
If you use mamba, replace conda install with mamba install.
To check the installation, type
wsinfer --help
Developers#
Clone the GitHub repository and install the package in editable mode with the dev extras
git clone https://github.com/SBU-BMI/wsinfer.git
cd wsinfer
python -m pip install --editable .[dev]
pre-commit install
We use pre-commit to automatically run various checks during git commit.
Supported slide backends#
WSInfer supports two backends for reading whole slide images: OpenSlide
and TiffSlide. When you install WSInfer, TiffSlide is also
installed. To install OpenSlide, install the compiled OpenSlide library and the Python package
openslide-python. To choose the backend on the command line, use
wsinfer --backend=tiffslide ... or wsinfer --backend=openslide .... In a Python script,
use wsinfer.wsi.set_backend.
Containers#
See https://hub.docker.com/u/kaczmarj/wsinfer/ for available Docker images. These Docker images can be used with Docker, Apptainer, or Singularity.
Docker:
docker pull kaczmarj/wsinfer
Apptainer:
apptainer pull docker://kaczmarj/wsinfer
Singularity:
singularity pull docker://kaczmarj/wsinfer
Developers#
Clone the repository from SBU-BMI/wsinfer and install it in editable mode.
git clone https://github.com/SBU-BMI/wsinfer.git
cd wsinfer
python -m pip install --editable .[dev,openslide]
wsinfer --help
Getting started#
The wsinfer command line program is the main interface to WSInfer. Use the --help
flag to show more information.
wsinfer --help
To list the available trained models:
wsinfer-zoo ls
To run inference on whole slide images:
wsinfer run --wsi-dir slides/ --results-dir results/ --model breast-tumor-resnet34.tcga-brca
To convert model outputs to GeoJSON, for example to view in QuPath:
wsinfer togeojson results/ model-outputs-geojson/