Small docs update for WNet (#68)

Author: C-Achard

docs/TODO.md

@@ -2,7 +2,7 @@
 TODO:
 - [ ] Add a way to get the current version of the library
 - [x] Update all modules
-- [x] Better WNet tutorial
+- [x] Better WNet3D tutorial
 - [x] Setup GH Actions
 - [ ] Add a bibliography
 )

docs/_toc.yml

@@ -14,9 +14,9 @@ parts:
   - caption : Walkthroughs
     chapters:
       - file: source/guides/detailed_walkthrough.rst
+      - file: source/guides/training_wnet.rst
   - caption : Advanced guides
     chapters:
-      - file: source/guides/training_wnet.rst
       - file: source/guides/custom_model_template.rst
   - caption : Code
     chapters:

docs/source/guides/detailed_walkthrough.rst

@@ -1,6 +1,6 @@
 .. _detailed_walkthrough:
 
-Detailed walkthrough - Supervised learning
+Walkthrough - Supervised learning
 ==========================================
 
 This guide will show you step-by-step how to use the plugin's workflow, beginning with human annotated datasets, to generating predictions on new volumes.
@@ -116,7 +116,7 @@ In most cases this should left enabled.
    * **VNet** is a larger (than SegResNet) CNN from MONAI designed for medical image segmentation.
    * **TRAILMAP** is our implementation in PyTorch additionally trained on mouse cortical neural nuclei from mesoSPIM data.
    * **SwinUNetR** is a MONAI implementation of the SwinUNetR model. It is costly in compute and memory, but can achieve high performance.
-   * **WNet** is our reimplementation of an unsupervised model, which can be used to produce segmentation without labels.
+   * **WNet3D** is our extension of an unsupervised model, which can be used to produce segmentation without labels. See :ref:`training_wnet` for more information.
 
 
 * **The loss** : For 3D volume object detection, the Dice or Dice-focal Loss is the most efficient.

docs/source/guides/inference_module_guide.rst

@@ -23,7 +23,7 @@ Model            Link to original paper
 ==============   ================================================================================================
 SwinUNetR        `Swin Transformers for Semantic Segmentation of Brain Tumors in MRI Images`_
 SegResNet        `3D MRI brain tumor segmentation using autoencoder regularization`_
-WNet             `WNet, A Deep Model for Fully Unsupervised Image Segmentation`_
+WNet3D             `WNet3D, A Deep Model for Fully Unsupervised Image Segmentation`_
 TRAILMAP_MS       An implementation of the `TRAILMAP project on GitHub`_ using `3DUNet for PyTorch`_
 VNet             `Fully Convolutional Neural Networks for Volumetric Medical Image Segmentation`_
 ==============   ================================================================================================
@@ -33,10 +33,10 @@ VNet             `Fully Convolutional Neural Networks for Volumetric Medical Ima
 .. _TRAILMAP project on GitHub: https://github.com/AlbertPun/TRAILMAP
 .. _3DUnet for Pytorch: https://github.com/wolny/pytorch-3dunet
 .. _Swin Transformers for Semantic Segmentation of Brain Tumors in MRI Images: https://arxiv.org/abs/2201.01266
-.. _WNet, A Deep Model for Fully Unsupervised Image Segmentation: https://arxiv.org/abs/1711.08506
+.. _WNet3D, A Deep Model for Fully Unsupervised Image Segmentation: https://arxiv.org/abs/1711.08506
 
 .. note::
-    For WNet-specific instruction please refer to the appropriate section below.
+    For WNet3D-specific instruction please refer to the appropriate section below.
 
 
 Interface and functionalities
@@ -142,23 +142,24 @@ In the ``notebooks`` folder you will find a plotting guide for cell statistics d
 Simply load the csv file in the notebook and use the provided functions to plot the desired statistics.
 
 
-Unsupervised model - WNet
--------------------------
+Unsupervised model - WNet3D
+--------------------------------
 
-| The `WNet model` is a fully unsupervised model used to segment images without any labels.
+| The `WNet3D model` is a fully unsupervised model used to segment images without any labels.
 | It functions similarly to the above models, with a few notable differences.
 
-.. _WNet model: https://arxiv.org/abs/1711.08506
+.. _WNet3D model: https://arxiv.org/abs/1711.08506
 
 .. note::
     Our provided, pre-trained model uses an input size of 64x64x64. As such, window inference is always enabled
     and set to 64. If you want to use a different size, you will have to train your own model using the options listed in :ref:`training_wnet`.
     Additionally, window inference and the number of classes are for now fixed in the plugin to support our pre-trained model only (2 classes and window size 64).
+
 For the best inference performance, the model should be retrained on images of the same modality as the ones you want to segment.
 Please see :ref:`training_wnet` for more details on how to train your own model.
 
 .. hint::
-  | WNet, as an unsupervised model, may not always output the background class in the same dimension.
+  | WNet3D, as an unsupervised model, may not always output the background class in the same dimension.
   | This might cause the result from inference to appear densely populated.
   | The plugin will automatically attempt to show the foreground class, but this might not always succeed.
   | If the displayed output seems dominated by the background, you can manually adjust the visible class. To do this, **use the slider positioned at the bottom of the napari window**.

docs/source/guides/installation_guide.rst

@@ -70,7 +70,7 @@ Successful installation will add the napari-cellseg3D plugin to napari’s Plugi
 
 
 M1/M2 (ARM64) Mac installation
--------------------------------
+--------------------------------------------
 .. _ARM64_Mac_installation:
 
 For ARM64 Macs, we recommend using our custom CONDA environment. This is particularly important for M1 or M2 MacBooks.
@@ -112,10 +112,10 @@ OR to install from source:
     pip install -e .
 
 Optional requirements
----------------------
+------------------------------
 
 Additional functionalities
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+______________________________
 
 Several additional functionalities are available optionally. To install them, use the following commands:
 
@@ -141,7 +141,7 @@ Several additional functionalities are available optionally. To install them, us
     pip install napari-cellseg3D[onnx-gpu]
 
 Development requirements
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+______________________________
 
 - Building the documentation:
 

docs/source/guides/review_module_guide.rst

@@ -1,14 +1,14 @@
 .. _review_module_guide:
 
-Review🔍
+Labeling🔍
 =================================
 
 .. figure:: ../images/plugin_review.png
     :align: center
 
     Layout of the review module
 
-**Review** allows you to inspect your labels, which may be manually created or predicted by a model, and make necessary corrections.
+**Labeling** allows you to inspect your labels, which may be manually created or predicted by a model, and make necessary corrections.
 The system will save the updated status of each file in a csv file.
 Additionally, the time taken per slice review is logged, enabling efficient monitoring.
 
@@ -38,7 +38,7 @@ Launching the review process
         - If an identical CSV file already exists, it will be used. If not, a new one will be generated.
         - If you choose to create a new dataset, a new CSV will always be created. If multiple copies already exist, a sequential number will be appended to the new file's name.
 
-4. **Beginning the Review:**
+4. **Beginning the labeling:**
     Press **`Start reviewing`** once you are ready to start the review process.
 
 .. warning::
@@ -51,9 +51,9 @@ Interface & functionalities
 .. figure:: ../images/review_process_example.png
     :align: center
 
-    Interface of the review process.
+    Interface for the labeling process.
 
-Once you have launched the review process, you will have access to the following functionalities:
+Once you have launched the labeling process, you will have access to the following functionalities:
 
 .. hlist::
    :columns: 1

docs/source/guides/training_module_guide.rst

@@ -26,7 +26,7 @@ Model            Link to original paper
 ==============   ================================================================================================
 SegResNet        `3D MRI brain tumor segmentation using autoencoder regularization`_
 SwinUNetR         `Swin UNETR, Swin Transformers for Semantic Segmentation of Brain Tumors in MRI Images`_
-WNet             `WNet, A Deep Model for Fully Unsupervised Image Segmentation`_
+WNet3D             `WNet3D, A Deep Model for Fully Unsupervised Image Segmentation`_
 TRAILMAP_MS       An implementation of the `TRAILMAP project on GitHub`_ using `3DUNet for PyTorch`_
 VNet             `Fully Convolutional Neural Networks for Volumetric Medical Image Segmentation`_
 ==============   ================================================================================================
@@ -36,7 +36,7 @@ VNet             `Fully Convolutional Neural Networks for Volumetric Medical Ima
 .. _TRAILMAP project on GitHub: https://github.com/AlbertPun/TRAILMAP
 .. _3DUnet for Pytorch: https://github.com/wolny/pytorch-3dunet
 .. _Swin UNETR, Swin Transformers for Semantic Segmentation of Brain Tumors in MRI Images: https://arxiv.org/abs/2201.01266
-.. _WNet, A Deep Model for Fully Unsupervised Image Segmentation: https://arxiv.org/abs/1711.08506
+.. _WNet3D, A Deep Model for Fully Unsupervised Image Segmentation: https://arxiv.org/abs/1711.08506
 
 Training
 ===================
@@ -167,7 +167,7 @@ ____________________
 1) **Advanced** tab
 ___________________
 
-This tab is only available with WNet training. For more information please see the :ref:`WNet parameters list <When using the WNet training module>` section.
+This tab is only available with WNet3D training. For more information please see the :ref:`WNet3D parameters list <When using the WNet3D training module>` section.
 
 Running the training
 ____________________
@@ -195,7 +195,7 @@ The model's inputs (image, label) and outputs (raw & binarized) will also be dis
 Unsupervised model
 ==============================================
 
-The training of our custom WNet implementation is now available as part of the Training module.
+The training of our custom WNet3D implementation is now available as part of the Training module.
 
 Please see the :ref:`training_wnet` section for more information.
 

docs/source/guides/training_wnet.rst

@@ -1,20 +1,20 @@
 .. _training_wnet:
 
-Advanced : WNet training
-========================
+Walkthrough - WNet3D training
+===============================
 
-This plugin provides a reimplemented, custom version of the WNet model from `WNet, A Deep Model for Fully Unsupervised Image Segmentation`_.
+This plugin provides a reimplemented, custom version of the WNet3D model from `WNet, A Deep Model for Fully Unsupervised Image Segmentation`_.
 For training your model, you can choose among:
 
 * Directly within the plugin
 * The provided Jupyter notebook (locally)
 * Our Colab notebook (inspired by ZeroCostDL4Mic)
 
-The WNet does not require a large amount of data to train, but during inference images should be similar to those
+The WNet3D does not require a large amount of data to train, but during inference images should be similar to those
 the model was trained on; you can retrain from our pretrained model to your image dataset to quickly reach good performance.
 
 .. note::
-        - The WNet relies on brightness to distinguish objects from the background. For better results, use image regions with minimal artifacts. If you notice many artifacts, consider training on one of the supervised models.
+        - The WNet3D relies on brightness to distinguish objects from the background. For better results, use image regions with minimal artifacts. If you notice many artifacts, consider training on one of the supervised models.
         - The model has two losses, the **`SoftNCut loss`**, which clusters pixels according to brightness, and a reconstruction loss, either **`Mean Square Error (MSE)`** or **`Binary Cross Entropy (BCE)`**. Unlike the method described in the original paper, these losses are added in a weighted sum and the backward pass is performed for the whole model at once. The SoftNcuts and BCE are bounded between 0 and 1; the MSE may take large positive values. It is recommended to watch for the weighted sum of losses to be **close to one on the first epoch**, for training stability.
         - For good performance, you should wait for the SoftNCut to reach a plateau; the reconstruction loss must also decrease but is generally less critical.
 
@@ -27,7 +27,7 @@ Parameters
 
     Advanced tab
 
-_`When using the WNet training module`, the **Advanced** tab contains a set of additional options:
+_`When using the WNet3D training module`, the **Advanced** tab contains a set of additional options:
 
 - **Number of classes** : Dictates the segmentation classes (default is 2). Increasing the number of classes will result in a more progressive segmentation according to brightness; can be useful if you have "halos" around your objects or artifacts with a significantly different brightness.
 - **Reconstruction loss** : Choose between MSE or BCE (default is MSE). MSE is more precise but also sensitive to outliers; BCE is more robust against outliers at the cost of precision.

docs/welcome.rst

@@ -160,7 +160,7 @@ This plugin mainly uses the following libraries and software:
 
 * `pyclEsperanto`_ (for the Voronoi Otsu labeling) by Robert Haase
 
-* A custom re-implementation of the `WNet`_ by Xia and Kulis [3]_
+* A new unsupervised 3D model based on the `WNet`_ by Xia and Kulis [3]_
 
 .. _Mathis Laboratory of Adaptive Motor Control: http://www.mackenziemathislab.org/
 .. _Wyss Center: https://wysscenter.ch/

napari_cellseg3d/napari.yaml

@@ -27,7 +27,7 @@ contributions:
 
   widgets:
   - command: napari_cellseg3d.load
-    display_name: Review
+    display_name: Labeling
 
   - command: napari_cellseg3d.infer
     display_name: Inference