Merge pull request #4 from AdaptiveMotorControlLab/mwm/updateDocs

MMathisLab · web-flow · commit 4e3616dad4df · 2022-06-18T14:28:09.000+02:00
Mwm/update docs [WIP]
diff --git a/docs/res/guides/detailed_walkthrough.rst b/docs/res/guides/detailed_walkthrough.rst
@@ -3,20 +3,27 @@
 Detailed walkthrough
 ===================================
 
-The following guide will show in details how to use the plugin's workflow, starting from a large labeled volume.
+The following guide will show you how to use the plugin's workflow, starting from human-labeled annotation volume, to running inference on novel volumes.
 
 Preparing images and labels
 -------------------------------
 
-To get started with the entire workflow, you'll need at least one pair of image and corresponding labels;
+CellSeg3D was designed for cleared-brain tissue data (collected on mesoSPIM ligthsheet systems). Specifically, we provide a series
+of deep learning models that we have found to work well on cortical whole-neuron data. We also provide support for MONAI models, and
+we have ported TRAILMAP to PyTorch and trained the model on mesoSPIM collected data. We provide all the tooling for you to use these
+weights and also perform transfer learning by fine-tuning the model(s) on your data for even better performance!
+
+To get started with the entire workflow (i.e., fine-tuning on your data), you'll need at least one pair of image and corresponding labels;
 let's assume you have part of a cleared brain from mesoSPIM imaging as a large .tif file.
 
+If you want to test the models "as is", please see "Inference" sections in our docs.
+
 
 .. figure:: ../images/init_image_labels.png
    :scale: 40 %
    :align: center
 
-   Example of an anisotropic volume and its associated labels.
+   Example of an anisotropic volume (i.e., often times the z resolution is not the same as x and y) and its associated labels.
 
 
 .. note::
@@ -29,7 +36,7 @@ Cropping
 *****************
 
 To reduce memory requirements and build a dataset from a single, large volume,
-you can use the **cropping** tool to extract multiple smaller images from a large volume.
+you can use the **cropping** tool to extract multiple smaller images from a large volume for training.
 
 Simply load your image and labels (by checking the "Crop labels simultaneously" option),
 and select the volume size you desire to use.
@@ -75,24 +82,24 @@ Models for object detection
 Training
 *****************
 
-If you have a dataset of reasonably sized images with semantic labels, you're all set !
-First of all, load your data by inputting the paths to images and labels, as well as where you want the results to be saved.
-
-There are a few more options on this tab :
+If you have a dataset of reasonably sized images (see cropping above) with semantic labels, you're all set to proceed!
+First, load your data by inputting the paths to images and labels, as well as where you want the results to be saved.
 
-* Save as zip : simply copies the results in a zip archive for easier transfer
+There are a few more options on this tab:
 
 * Transfer weights : you can start the model with our pre-trained weights if your dataset comes from cleared brain tissue
-  image by mesoSPIM as well. If you have your own weights for the provided models, you can also choose to load them by
-  checking the related option; simply make sure they are compatible with the model.
+  imaged by a mesoSPIM (or other lightsheet). If you have your own weights for the provided models, you can also choose to load them by
+  checking the related option; simply make sure they are compatible with the model you selected.
 
   To import your own model, see : :ref:`custom_model_guide`, please note this is still a WIP.
 
 * Validation proportion : the percentage is listed is how many images will be used for training versus validation.
   Validation can work with as little as one image, however performance will greatly improve the more images there are.
-  Use 90% only if you have a very small dataset (less than 5 images)
+  Use 90% only if you have a very small dataset (less than 5 images).
 
-With this, we can switch to the next tab : data augmentation.
+* Save as zip : simply copies the results in a zip archive for easier transfer.
+
+Now, we can switch to the next tab : data augmentation.
 
 If you have cropped cubic images with a power of two as the edge length, you do not need to extract patches,
 your images are usable as is.
@@ -109,11 +116,14 @@ In most cases this should left enabled.
 
 Finally, the last tab lets you choose :
 
-* The model
+* The models
 
-    * SegResNet is a lightweight model (low memory requirements) with decent performance.
-    * TRAILMAP is a recent model trained for axonal detection in cleared tissue; use it if your dataset is similar
-    * VNet is a possibly more performant model than SegResnet but requires much more memory
+    * SegResNet is a lightweight model (low memory requirements) from MONAI originally designed for 3D fMRI data.
+    * VNet is a heavier (than SegResNet) CNN from MONAI designed for medical image segmentation.
+    * TRAILMAP is our PyTorch implementation of a 3D CNN model trained for axonal detection in cleared tissue.
+    * TRAILMAP-MS is our implementation in PyTorch additionally trained on mouse cortical neural nuclei from mesoSPIM data.
+    * Note, the code is very modular, so it is relatively straightforward to use (and contribute) your model as well.
+    
 
 * The loss : for object detection in 3D volumes you'll likely want to use the Dice or Dice-focal Loss.
 
@@ -161,7 +171,7 @@ To start, simply choose which folder of images you'd like to run inference on, t
 Then, select the model you trained (see note below for SegResNet), and load your weights from training.
 
 .. note::
-    If you trained a SegResNet, set the counter below the model choice to the size of the images you trained the model on.
+    If you already trained a SegResNet, set the counter below the model choice to the size of the images you trained the model on.
     (Either use the size of the image itself if you did not extract patches, or the size of the nearest superior power of two of the patches you extracted)
 
     Example :
@@ -171,7 +181,7 @@ Then, select the model you trained (see note below for SegResNet), and load your
 
 
 Next, you can choose to use window inference, use this if you have very large images.
-Please note that using too small a window might degrade performance, set the size appropriately.
+Please note that using too small of a window might degrade performance, set the size appropriately.
 
 You can also keep the dataset on the CPU to reduce memory usage, but this might slow down the inference process.
 
@@ -294,8 +304,3 @@ for the plots to work.
 .. _notebooks folder of the repository: https://github.com/AdaptiveMotorControlLab/CellSeg3d/tree/main/notebooks
 
 With this complete, you can repeat the workflow as needed.
-
-
-
-
-
diff --git a/docs/res/welcome.rst b/docs/res/welcome.rst
@@ -2,13 +2,13 @@ Introduction
 ===================
 
 
-Here you will find instructions on how to use the plug-in program.
+Here you will find instructions on how to use the plugin for direct-to-3D segmentation.
 If the installation was successful, you'll see the napari-cellseg3D plugin
 in the Plugins section of napari.
 
 This plugin was initially developed for the review of labeled cell volumes [#]_ from mice whole-brain samples
 imaged by mesoSPIM microscopy [#]_ , and for training and using segmentation models from the MONAI project [#]_,
-or any custom model written in Pytorch.
+or any custom model written in PyTorch.
 It should be adaptable to other tasks related to detection of 3D objects, as long as labels are available.
 
 
@@ -26,32 +26,34 @@ From this page you can access the guides on the several modules available for yo
     * Defining custom models directly in the plugin (WIP) : :ref:`custom_model_guide`
 
 
-Requirements
+Installation
 --------------------------------------------
 
-.. important::
-    A **CUDA-capable GPU** is not needed but **very strongly recommended**, especially for training.
-
-Requires installation of PyTorch and some optional dependencies of MONAI.
+You can install `napari-cellseg3d` via [pip]:
 
-* For PyTorch, please see `PyTorch's website`_ for installation instructions, with or without CUDA depending on your hardware.
+  ``pip install napari-cellseg3d``
 
-* If you get errors from MONAI regarding missing readers, please see `MONAI's optional dependencies`_ page for instructions on getting the readers required by your images.
+  For local installation, please run:
 
-.. _MONAI's optional dependencies: https://docs.monai.io/en/stable/installation.html#installing-the-recommended-dependencies
-.. _PyTorch's website: https://pytorch.org/get-started/locally/
+  ``pip install -e .``
 
-Installation
+Requirements
 --------------------------------------------
 
-You can install `napari-cellseg3d` via [pip]:
+.. important::
+    A **CUDA-capable GPU** is not needed but **very strongly recommended**, especially for training.
 
-    ``pip install napari-cellseg3d``
+This package requires you have napari installed first.
 
-For local installation, please run:
+It also depends on PyTorch and some optional dependencies of MONAI. These come in the pip package above, but if
+you need further assistance see below.
 
-    ``pip install -e .``
+* For help with PyTorch, please see `PyTorch's website`_ for installation instructions, with or without CUDA depending on your hardware.
 
+* If you get errors from MONAI regarding missing readers, please see `MONAI's optional dependencies`_ page for instructions on getting the readers required by your images.
+
+.. _MONAI's optional dependencies: https://docs.monai.io/en/stable/installation.html#installing-the-recommended-dependencies
+.. _PyTorch's website: https://pytorch.org/get-started/locally/
 
 
 Usage
@@ -61,7 +63,7 @@ To use the plugin, please run:
 
     ``napari``
 
-Then go into Plugins > napari-cellseg3d, and choose which tool to use.
+Then go into Plugins > napari-cellseg3d, and choose which tool to use:
 
 
 - **Train**:  This module allows you to train segmentation algorithms from labeled volumes.
@@ -73,11 +75,12 @@ See above for links to detailed guides regarding the usage of the modules.
 
 Acknowledgments & References
 ---------------------------------------------
-This plugin has been developed by Cyril Achard and Maxime Vidal for the `Mathis Laboratory of Adaptive Motor Control`_. 
+This plugin has been developed by Cyril Achard and Maxime Vidal, supervised by Mackenzie Mathis for the `Mathis Laboratory of Adaptive Motor Control`_.
 
 We also greatly thank Timokleia Kousi for her contributions to this project and the `Wyss Center`_ for project funding.
 
-The TRAILMAP models and original weights used here all originate from the `TRAILMAP project on GitHub`_ [1]_.
+The TRAILMAP models and original weights used here were ported to PyTorch but originate from the `TRAILMAP project on GitHub`_ [1]_.
+We also provide a model that was trained in-house on mesoSPIM nuclei data in collaboration with Dr. Stephane Pages and Timokleia Kousi.
 
 This plugin mainly uses the following libraries and software:
 
@@ -88,7 +91,7 @@ This plugin mainly uses the following libraries and software:
 * `MONAI project website`_ (various models used here are credited `on their website`_)
 
 
-.. _Mathis Laboratory of adaptive motor control: http://www.mackenziemathislab.org/
+.. _Mathis Laboratory of Adaptive Motor Control: http://www.mackenziemathislab.org/
 .. _Wyss Center: https://wysscenter.ch/
 .. _TRAILMAP project on GitHub: https://github.com/AlbertPun/TRAILMAP
 .. _napari website: https://napari.org/
@@ -102,4 +105,3 @@ This plugin mainly uses the following libraries and software:
 .. [#] Mapping mesoscale axonal projections in the mouse brain using a 3D convolutional network, Friedmann et al., 2020 ( https://pnas.org/cgi/doi/10.1073/pnas.1918465117 )
 .. [#] The mesoSPIM initiative: open-source light-sheet microscopes for imaging cleared tissue, Voigt et al., 2019 ( https://doi.org/10.1038/s41592-019-0554-0 )
 .. [#] MONAI Project website ( https://monai.io/ )
-
