From a937f29c9d39c13b45f439db9252e05b04f7e437 Mon Sep 17 00:00:00 2001 From: Jakub Kaczmarzyk Date: Fri, 24 Feb 2023 11:15:22 -0500 Subject: [PATCH] add more intro content to index.rst (#104) * add more intro content to index.rst - Add info on how to get help, request features - Add example CLI to the homepage - Add links to installation and user guide. * enh apptainer docs Improve the apptainer docs. Unset TORCH_HOME in the command line example and add a note of why that is necessary. Also add a note to the geojson converter that one can drag and drop the json to load it into qupath. * sleep in test_issue_97 so timestamp is different --- docs/index.rst | 31 +++++++++++++++++++++++++---- docs/installing.rst | 2 ++ docs/user_guide.rst | 48 ++++++++++++++++++++++++++++++++++++--------- tests/test_all.py | 3 +++ 4 files changed, 71 insertions(+), 13 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 02035d2..d14699d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,8 +3,6 @@ WSInfer: blazingly fast inference on whole slide images ======================================================= -🔥 🚀 **WSInfer** is a blazingly fast pipeline to run patch-based classification models -on whole slide images. .. image:: https://github.com/kaczmarj/wsinfer/actions/workflows/ci.yml/badge.svg :alt: GitHub workflow status @@ -21,6 +19,29 @@ on whole slide images. | +🔥 🚀 **WSInfer** is a blazingly fast pipeline to run patch-based classification models +on whole slide images. It includes several built-in models for tumor and lymphocyte +detection, and it can be used with any PyTorch model as well. The built-in models +:ref:`are listed below `. + +Running inference on whole slide images is done with a single command line. For example, +this is the command used to generate the heatmap on this page. + +:: + + CUDA_VISIBLE_DEVICES=0 wsinfer run \ + --wsi-dir slides/ \ + --results-dir results/ \ + --model resnet34 \ + --weights TCGA-BRCA-v1 \ + --num-workers 8 + +To get started, please :ref:`install WSInfer` and check out the :ref:`User Guide`. +To get help, report issues or request features, please +`submit a new issue `_ on our GitHub +repository. If you would like to make your patch classification model available in WSInfer, please +get in touch with us! You can `submit a new GitHub issue `_. + .. toctree:: :maxdepth: 1 :caption: Contents: @@ -41,6 +62,8 @@ on whole slide images. | |img-tissue| | |img-heatmap| | +----------------+------------------------------+ +.. _available-models: + Available models ---------------- @@ -55,7 +78,7 @@ Available models - Reference * - Breast adenocarcinoma detection - no-tumor, tumor - - inceptionv4 + - inception_v4 - TCGA-BRCA-v1 - 350 @ 0.25 - `Ref `_ @@ -91,7 +114,7 @@ Available models - `Ref `_ * - Tumor-infiltrating lymphocyte detection - til-negative, til-positive - - inceptionv4nobn + - inception_v4nobn - TCGA-TILs-v1 - 100 @ 0.5 - `Ref `_ diff --git a/docs/installing.rst b/docs/installing.rst index 81944b4..0cb0637 100644 --- a/docs/installing.rst +++ b/docs/installing.rst @@ -1,3 +1,5 @@ +.. _installing: + Installing and getting started ============================== diff --git a/docs/user_guide.rst b/docs/user_guide.rst index 00eca68..5f229f1 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -1,3 +1,5 @@ +.. _User Guide: + User Guide ========== @@ -37,8 +39,8 @@ The option :code:`--num-workers` controls how many processes to use for data loa Using more workers will typically speed up processing at the expense of more RAM and processor use. -The results directory includes a file named :code:`run_metadata.json` with provenance -information. +The results directory includes a file named :code:`run_metadata_TIMESTAMP.json` with +provenance information. Run model inference in containers --------------------------------- @@ -57,7 +59,7 @@ addition of downloaded weights. The base image :code:`kaczmarj/wsinfer` does not include downloaded models. The models will be downloaded automatically but will be lost when the container is stopped. Use versioned, application-specific containers like - :code:`kaczmarj/wsinfer:0.3.2-tumor-brca` as they already include weights. + :code:`kaczmarj/wsinfer:0.3.5-tumor-brca` as they already include weights. Apptainer/Singularity ^^^^^^^^^^^^^^^^^^^^^ @@ -65,11 +67,36 @@ Apptainer/Singularity We use :code:`apptainer` in this example. You can replace that name with :code:`singularity` if you do not have :code:`apptainer`. -:: +Pull the container: :: - apptainer pull docker://kaczmarj/wsinfer:0.3.2-tumor-paad - CUDA_VISIBLE_DEVICES=0 apptainer run --nv --bind $(pwd) wsinfer_0.3.2-tumor-paad.sif \ - run --wsi-dir slides/ --results-dir results/ + apptainer pull docker://kaczmarj/wsinfer:latest + +Run inference: :: + + apptainer run \ + --nv \ + --bind $(pwd) \ + --env TORCH_HOME="" \ + --env CUDA_VISIBLE_DEVICES=0 \ + wsinfer_latest.sif run \ + --wsi-dir slides/ \ + --results-dir results/ \ + --model resnet34 \ + --weights TCGA-BRCA-v1 \ + --num-workers 8 + +.. note:: + + If you get an error like :code:`Read-only file system: '/var/lib/wsinfer/hub/checkpoints/tmp4rs7aaz9'`, + then unset the environment variable :code:`TORCH_HOME`. + + :: + + apptainer run --nv --bind $(pwd) --env TORCH_HOME="" wsinfer_latest.sif + + This happens when model weights are downloaded. Apptainer/Singularity containers are + not writable, so writing the weights file to the container fails. Unsetting + :code:`TORCH_HOME` will cause the models to be downloaded to the current directory. Docker ^^^^^^ @@ -93,7 +120,7 @@ When mounting data, keep in mind that the workdir in the Docker container is :co Pull the Docker image: :: - docker pull kaczmarj/wsinfer:0.3.2-tumor-paad + docker pull kaczmarj/wsinfer:latest Run inference: :: @@ -103,7 +130,7 @@ Run inference: :: --env CUDA_VISIBLE_DEVICES=0 \ --user $(id -u):$(id -g) \ --mount type=bind,source=$(pwd),target=/work/ \ - kaczmarj/wsinfer:0.3.2-tumor-paad run \ + kaczmarj/wsinfer:latest run \ --wsi-dir slides/ \ --results-dir results/ \ --model resnet34 \ @@ -167,6 +194,9 @@ GeoJSON is a JSON format compatible with whole slide image viewers like QuPath. wsirun togeojson results/ geojson-results/ +If you open one of your slides in QuPath, you can drag and drop the corresponding +JSON file into the QuPath window to load the model outputs. + Convert model outputs to Stony Brook format (QuIP) -------------------------------------------------- diff --git a/tests/test_all.py b/tests/test_all.py index c9dff55..c94af0b 100644 --- a/tests/test_all.py +++ b/tests/test_all.py @@ -5,6 +5,7 @@ import platform import subprocess import sys +import time from typing import List from click.testing import CliRunner @@ -1047,6 +1048,8 @@ def test_issue_97(tmp_path: Path, tiff_image: Path): metas = list(results_dir.glob("run_metadata_*.json")) assert len(metas) == 1 + time.sleep(2) # make sure some time has passed so the timestamp is different + # Run again... result = runner.invoke( cli,