From 3fb9342752c5f8b6625dba139003d1860d6a25ae Mon Sep 17 00:00:00 2001 From: Jakub Kaczmarzyk Date: Sat, 31 Dec 2022 20:31:31 -0500 Subject: [PATCH] DOCS: add usage examples and dedicated installation page (#54) * add dedicated installation page * add examples to user guide * add docs badge + add links to badges --- README.md | 9 ++-- docs/index.rst | 9 ++-- docs/installing.rst | 67 +++++++++++++++++++++++++ docs/user_guide.rst | 116 ++++++++++++++++++++++++++++++++++++++------ 4 files changed, 177 insertions(+), 24 deletions(-) create mode 100644 docs/installing.rst diff --git a/README.md b/README.md index c64f862..15e2dce 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Patch classification pipelines for computational pathology +# WSINfer: deep learning inference on whole slide images Original H&E | Heatmap of Tumor Probability :----------------------------------:|:-----------------------------------: @@ -6,9 +6,10 @@ Original H&E | Heatmap of Tumor Probability 🔥 🚀 Blazingly fast pipeline to run patch-based classification models on whole slide images. -![Continuous Integration](https://github.com/kaczmarj/patch-classification-pipeline/actions/workflows/ci.yml/badge.svg) -![Supported Python versions](https://img.shields.io/pypi/pyversions/wsinfer) -![Version on PyPI](https://img.shields.io/pypi/v/wsinfer.svg) +[![Continuous Integration](https://github.com/kaczmarj/patch-classification-pipeline/actions/workflows/ci.yml/badge.svg)](https://github.com/kaczmarj/wsinfer/actions/workflows/ci.yml) +[![Documentation Status](https://readthedocs.org/projects/wsinfer/badge/?version=latest)](https://wsinfer.readthedocs.io/en/latest/?badge=latest) +[![Version on PyPI](https://img.shields.io/pypi/v/wsinfer.svg)](https://pypi.org/project/wsinfer/) +[![Supported Python versions](https://img.shields.io/pypi/pyversions/wsinfer)](https://pypi.org/project/wsinfer/) # Table of contents diff --git a/docs/index.rst b/docs/index.rst index 1a7e19c..eed1ffb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,5 @@ -Welcome to WSInfer! -=================== +WSInfer: deep learning inference on whole slide images +====================================================== **WSInfer** is a program to run patch-based classification inference on whole slide images. @@ -8,10 +8,11 @@ Check out the :doc:`user_guide` for further information, including how to instal project. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: - user_guide + Installing + User Guide Indices and tables diff --git a/docs/installing.rst b/docs/installing.rst new file mode 100644 index 0000000..3a322c2 --- /dev/null +++ b/docs/installing.rst @@ -0,0 +1,67 @@ +Installing and getting started +============================== + +Prerequisites +------------- + +WSInfer supports Python 3.7+. + +Install PyTorch before installing WSInfer. Please see +`PyTorch's installation instructions `_. +WSInfer does not install PyTorch automatically because the installation depends on +the type of hardware a user has. + +Manual installation +------------------- + +After having installed PyTorch, install releases of WSInfer from `PyPI `_. +Be sure to include the line :code:`--find-links https://girder.github.io/large_image_wheels` to ensure +dependencies are installed properly. :: + + pip install wsinfer --find-links https://girder.github.io/large_image_wheels + +This installs the :code:`wsinfer` Python package and the :code:`wsinfer` command line program. :: + + wsinfer --help + +Containers +---------- + +See https://hub.docker.com/u/kaczmarj/wsinfer/ for available Docker images. :: + + docker pull kaczmarj/wsinfer + +The main wsinfer container includes all dependencies and can run all models. There are also model-specific +Docker images that are more suitable for inference because those include pre-downloaded model weights. If using +the "base" WSInfer Docker image, model weights need to be downloaded every time the container +is used for inference, and the downloaded weights do not persist after the container is stopped. + +Development installation +------------------------ + +Clone the repository from https://github.com/kaczmarj/wsinfer and install it in editable mode. :: + + git clone https://github.com/kaczmarj/wsinfer.git + cd wsinfer + pip install --editable .[dev] + wsinfer --help + +Getting started +--------------- + +The :code:`wsinfer` command line program is the main interface to WSInfer. Use the :code:`--help` +flag to show more information. :: + + wsinfer --help + +To list the available trained models: :: + + wsinfer list + +To run inference on whole slide images: :: + + wsinfer run --wsi-dir slides/ --results-dir results/ --model resnet34 --weights TCGA-BRCA-v1 + +To convert model outputs to GeoJSON, for example to view in QuPath: :: + + wsinfer togeojson results/ model-outputs-geojson/ diff --git a/docs/user_guide.rst b/docs/user_guide.rst index e74d638..b1242b3 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -1,31 +1,42 @@ User Guide ========== -.. _installation: - -Installation ------------- +List available models +--------------------- -To use WSInfer, first install it using pip: +:: -.. code-block:: console + wsinfer list - pip install wsinfer --find-links https://girder.github.io/large_image_wheels +As of January 1, 2022, the output is :: -Examples -------- + +------------------------------------------+ + | MODEL WEIGHTS | + | ======================================== | + | inceptionv4 TCGA-BRCA-v1 | + | ---------------------------------------- | + | inceptionv4nobn TCGA-TILs-v1 | + | ---------------------------------------- | + | preactresnet34 TCGA-PAAD-v1 | + | ---------------------------------------- | + | resnet34 TCGA-BRCA-v1 | + | resnet34 TCGA-LUAD-v1 | + | resnet34 TCGA-PRAD-v1 | + | ---------------------------------------- | + | vgg16mod TCGA-BRCA-v1 | + +------------------------------------------+ -List available models -^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: console +Run model inference +------------------- - wsinfer list +The model inference workflow will separate each slide into patches and run model +inference on all patches. The results directory will include the model outputs, +patch coordinates, and metadata about the run. -Run model inference -^^^^^^^^^^^^^^^^^^^ +For available :code:`--model` and :code:`--weights` options, see :code:`wsinfer list`. -.. code-block:: console +:: mkdir -p example-wsi-inference/sample-images cd example-wsi-inference/sample-images @@ -39,3 +50,76 @@ Run model inference --model resnet34 \ --weights TCGA-BRCA-v1 \ --num-workers 8 + + +Use your own model +------------------ + +WSInfer uses YAML configuration files for models and weights. Please see the commented +example below. + +.. code-block:: yaml + + # The version of the spec. At this time, only "1.0" is valid. (str) + version: "1.0" + # Models are referenced by the pair of (architecture, weights), so this pair must be unique. + # The name of the architecture. We use timm to supply hundreds or network architectures, + # so the name can be one of those models. If the architecture is not provided in timm, + # then one can add an architecture themselves, but the code will have to be modified. (str) + architecture: resnet34 + # A unique name for the weights for this architecture. (str) + name: TCGA-BRCA-v1 + # Where to get the model weights. Either a URL or path to a file. + # If using a URL, set the url_file_name (the name of the file when it is downloaded). + # url: https://stonybrookmedicine.box.com/shared/static/dv5bxk6d15uhmcegs9lz6q70yrmwx96p.pt + # url_file_name: resnet34-brca-20190613-01eaf604.pt + # If not using a url, then 'file' must be supplied. Use an absolute or relative path. If + # using a relative path, the path is relative to the location of the yaml file. + file: path-to-weights.pt + # Size of patches from the slides. (int) + patch_size_pixels: 350 + # The microns per pixel of the patches. (float) + spacing_um_px: 0.25 + # Number of output classes from the model. (int) + num_classes: 2 + # Names of the model outputs. The order matters. class_names[0] is the name of the first + # class of the model output. + class_names: # (list of strings) + - notumor + - tumor + transform: + # Size of images immediately prior to inputting to the model. (int) + resize_size: 224 + # Mean and standard deviation for RGB values. (list of three floats) + mean: [0.7238, 0.5716, 0.6779] + std: [0.1120, 0.1459, 0.1089] + +Once you create a configuration file, use the config with `wsinfer run`: :: + + wsinfer run --wsi-dir slides/ --results-dir results/ --config config.yaml + + +Convert model outputs to GeoJSON (QuPath) +----------------------------------------- + +GeoJSON is a JSON format compatible with whole slide image viewers like QuPath. + +:: + + wsirun togeojson results/ geojson-results/ + +Convert model outputs to Stony Brook format (QuIP) +-------------------------------------------------- + +The QuIP whole slide image viewer uses a particular format consisting of JSON and table files. + +:: + + wsirun tosbu \ + --wsi-dir slides/ \ + --execution-id UNIQUE_ID_HERE \ + --study-id STUDY_ID_HERE \ + --make-color-text \ + --num-processes 16 \ + results/ \ + results/model-outputs-sbubmi/