Merge pull request #714 from mrariden/update_faq

Create FAQ & Update Docs

docs/command.rst

@@ -1,8 +1,8 @@
 Command line
 ------------------------
 
-See the CLI documentation: :ref:`Cellpose CLI`. A description of the most
-important settings can be found on the :ref:`Settings` page.
+The full list of options and what they do can be found on the Command Line Interface (CLI) documentation
+page: :ref:`Cellpose CLI`. A description of the most important settings can be found on the :ref:`Settings` page.
 
 .. _Command line examples:
 
@@ -28,4 +28,3 @@ estimated:
 
 .. warning:: 
     The path given to ``--dir`` must be an absolute path.
-

docs/faq.rst

@@ -0,0 +1,58 @@
+FAQ
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Q: What should I set the** ``--flow_threshold``/``--cell_prob``/``--diam`` **parameter to?**
+
+    These parameters should be set experimentally by running Cellpose, viewing the results, and tuning the parameters
+    to get the best results. The default parameters are set to work well for most images, but may not be optimal
+    for your images. See :ref:`Settings` for more information.
+
+
+**Q: What accuracy is good enough? Is there a quantitative threshold that should be met before implementing a model?**
+
+    Generally speaking you want to meet or exceed the accuracy of a human. You can estimate human accuracy by labeling
+    the same image twice and evaluating accuracy metrics. In practice human accuracy is often lower than you would
+    expect. You can see our results from this analysis in our Cellpose 2
+    `paper <https://www.biorxiv.org/content/10.1101/2022.04.01.486764v1>`_.
+
+    Some additional information on precision and accuracy can be found `here <https://forum.image.sc/t/how-to-interpret-cellposes-average-precision-model-evaluation-value/75231/3>`_.
+
+
+**Q: How do I download the pretrained models?**
+
+    The models will be downloaded automatically from the `website <https://www.cellpose.org/>`_ when you first run a
+    pretrained model in cellpose. If you are having issues with the downloads, you can download them from this
+    `google drive zip file <https://drive.google.com/file/d/1zHGFYCqRCTwTPwgEUMNZu0EhQy2zaovg/view?usp=sharing>`_,
+    unzip the file and put the models in your home directory under the path ``.cellpose/models/``,
+    e.g. on Windows this would be ``C:/Users/YOUR_USERNAME/.cellpose/models/`` or on Linux this would be
+    ``/home/YOUR_USERNAME/.cellpose/models/``, so ``/home/YOUR_USERNAME/.cellpose/models/cyto_0`` is the full
+    path to one model for example. If you cannot access google drive, the models are also available on
+    baidu: https://pan.baidu.com/s/1CARpRGCBHIYaz7KeyoX-fg thanks to @qixinbo!
+
+
+**Q: How can I use cellpose to recognize different types of cells in the same image?**
+
+    Cellpose does not natively support recognizing different types of cells (aka 'multiclass segmentation').
+    However, you can train individual models that are capable of recognizing only a given cell type at a time and run
+    Cellpose multiple times on the same image. With sufficient training, the result will be two sets of
+    outputs that could be combined in post-processing to identify the different cell types.
+
+
+**Q: Why does the PNG mask file look dim at the top and light at the bottom? I can't see the cell masks.**
+
+    This is expected and intended behavior, although it is dependent on the image viewer used to view
+    the mask file. The mask file is saved with each pixel as background
+    (represented by a 0), or as a cell label (represented by the cell label number). The gradient is
+    produced because each cell label is unique and monotonically increasing from top to bottom.
+
+    You can use different look up tables (LUTs) in ImageJ to view the resulting masks or threshold everything
+    above zero to get everything that cellpose detects. Image post processing is outside the scope
+    of cellpose, but you can find additional help at https://forum.image.sc/tag/cellpose.
+
+**Q: The Cellpose GUI is unresponsive/frozen. Is it broken?**
+
+    Cellpose is likely not broken; it is just busy. Currently, the GUI cannot receive input while computing
+    segmentation. Cellpose is a fairly computationally intensive program and may take a long time
+    to run, depending on computer hardware specifications. Cellpose will take a long time to run on large images.
+    Using hardware with a faster CPU and with more available memory will speed up the process. Using a GPU will
+    also speed up the process, especially if you are training with a large dataset.

docs/index.rst

@@ -50,6 +50,7 @@ Cellpose 1.0
    models
    train
    openvino
+   faq
 
 .. toctree::
    :maxdepth: 3

docs/installation.rst

@@ -37,7 +37,23 @@ by Peter Sobolewski. From the command line you can choose the Mac device with
 ::
 
    python -m cellpose --dir path --gpu_device mps --use_gpu
-   
+
+AMD GPU ROCm installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As an alternative to the CUDA acceleration for NVIDIA GPUs, you can use the ROCm acceleration for AMD GPUs.
+This is not yet supported on Windows, but is supported on Linux. Installation instructions are `available here
+<https://docs.amd.com/bundle/ROCm-Installation-Guide-v5.5/page/Introduction_to_ROCm_Installation_Guide_for_Linux.html>`_.
+Just like the NVIDIA CUDA installation, you will need to install the ROCm drivers first and then install Cellpose.
+Be warned that the ROCm project is significantly less mature than CUDA, and you may run into issues.
+
+.. warning::
+   The ROCm acceleration is not yet supported on Windows, and is only supported on Linux.
+   If you are on Windows, you will need to use CUDA acceleration.
+
+.. warning::
+   ROCm is significantly less mature than the CUDA acceleration, and you may run into issues.
+
 
 Common issues
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -64,7 +80,6 @@ If you are having other issues with the graphical interface and QT, see some adv
 If you have errors related to OpenMP and libiomp5, then try 
 
 ::
-
    conda install nomkl
 
 If you receive an error associated with **matplotlib**, try upgrading

docs/outputs.rst

@@ -14,7 +14,6 @@ _seg.npy output
 - *filename* : filename of image
 - *img* : image with chosen channels (nchan x Ly x Lx) (if not multiplane)
 - *masks* : each pixel in the image is assigned to an ROI (0 = NO ROI; 1,2,... = ROI labels)
-- *colors* : colors for ROIs
 - *outlines* : outlines of ROIs (0 = NO outline; 1,2,... = outline labels)
 - *chan_choose* : channels that you chose in GUI (0=gray/none, 1=red, 2=green, 3=blue)
 - *ismanual* : element *k* = whether or not mask *k* was manually drawn or computed by the cellpose algorithm

docs/settings.rst

@@ -39,6 +39,7 @@ Set channels to a list with each of these elements, e.g.
 
 On the command line the above would be ``--chan 0 --chan2 0`` or ``--chan 2 --chan2 3``.
 
+.. _diameter:
 Diameter 
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -85,7 +86,7 @@ always set to an array of zeros. Therefore set the first channel as
 
 If the nuclear model isn't working well, try the cytoplasmic model.
 
-Flow threshold (aka model fit threshold in GUI)
+Flow threshold
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Note there is nothing keeping the neural network from predicting