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
SBU-BMI · Jan 1, 2023 · 3fb9342 · 3fb9342
1 parent 0e1d8b7
commit 3fb9342
Show file tree

Hide file tree

Showing 4 changed files with 177 additions and 24 deletions.
diff --git a/README.md b/README.md
@@ -1,14 +1,15 @@
-# Patch classification pipelines for computational pathology
+# WSINfer: deep learning inference on whole slide images
 
 Original H&E                        |  Heatmap of Tumor Probability
 :----------------------------------:|:-----------------------------------:
 ![](sample-images/brca-tissue.png)  | ![](sample-images/brca-heatmap.png)
 
 🔥 🚀 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
@@ -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 <installing>
+   User Guide <user_guide>
 
 
 Indices and tables

diff --git a/docs/installing.rst 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 <https://pytorch.org/get-started/locally/>`_.
+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 <https://pypi.org/project/wsinfer/>`_.
+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
@@ -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/