Merge pull request #1341 from MouseLand/faq_update

Faq update

Author: mrariden

docs/faq.rst

@@ -1,6 +1,10 @@
 FAQ
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
+----------------------
+Cellpose settings and usage
+----------------------
+
 **Q: What should I set the** ``--flow_threshold``/``--cellprob_threshold``/``--diameter`` **parameter to?**
 
     These parameters should be set experimentally by running Cellpose, viewing the results, and tuning the parameters
@@ -18,20 +22,6 @@ FAQ
     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 new Cellpose-SAM model (cpsam) will be downloaded from `https://huggingface.co/mouseland/cellpose-sam/blob/main/cpsam`_.
-    
-    The old 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').
@@ -68,6 +58,24 @@ FAQ
     `here <https://pytorch.org/docs/stable/threading_environment_variables.html>`_.
 
 
+----------------------
+Models and training
+----------------------
+
+**Q: How do I download the pretrained models?**
+
+    The new Cellpose-SAM model (cpsam) will be downloaded from `huggingface <https://huggingface.co/mouseland/cellpose-sam/blob/main/cpsam>`_.
+    
+    The old 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 does HITL work?**
 
     In cellpose HITL training always starts from a pretrained model but incorporates more training 
@@ -111,4 +119,35 @@ colab/a cluster)**
 
     5. Evaluate the trained model on the next image.
 
-    6. Repeat 3-5 until you have a working fine-tuned model. 
+    6. Repeat 3-5 until you have a working fine-tuned model. 
+
+
+**Q: Why should I always start from the built-in cellpose model for fine-tuning rather than my fine-tuned model?**
+   
+    Cellpose uses transfer learning,
+    where a pre-trained network is used as a starting point that is 'good enough'. Cellpose was trained on a large
+    and diverse training set of images so that it is a generalist segmentation model: it will segment many types
+    of images. However, it is not perfect. This means that the
+    network parameters are somewhat close to predicting good outputs for a new dataset. 
+    
+    After HITL training, you have a new trained network, with parameterst that are closer to your ideal network for that
+    particular image dataset. To improve the model, you should then take this better performing network and train it again, no? 
+
+    This is actually a bad idea. The result would be that the network would learn on your data, but it would start to 
+    memorize your data instead of generalizing. This is because each time you train a model, you are moving away from the 
+    generalist, pre-trained parameters, and toward a smaller target distribution of images. Done enough times, the network
+    may lose the ability to generalize to new images. 
+
+    Instead, the cellpose GUI forces you to always start with a pretrained model that is known to perform well to make 
+    the iteration cycle more robust. New data is added each cycle, but the model will always start with the generalist
+    pre-trained model to produce a new fine-tuned model. As you continue the training cycle, the model will converge
+    on the best model parameters to segment your images. You *should* use the new models to predict the segmentation, 
+    that is the point of the HITL design. Eventually, you will have a model that doesn't need additional training 
+    to accurately predict your segmentation.
+
+
+**Q: Why not train from scratch?**
+
+    You also have the option to train from scratch, but that will take much 
+    longer and requires much more data. The CP4 network leverages extensive pretraining (300k natural images, 
+    23k cellular images). You will need something similar to this to get generalist results. 

docs/notebook.rst

@@ -23,6 +23,6 @@ See :ref:`Settings` for more information on run settings.
 
     masks, flows, styles = model.eval(imgs)
 
-See example notebook at `run_cellpose.ipynb`_. 
+See example notebook at `run_Cellpose-SAM.ipynb`_. 
 
-.. _run_cellpose.ipynb: https://nbviewer.jupyter.org/github/MouseLand/cellpose/blob/master/notebooks/run_cellpose.ipynb
+.. _run_cellpose.ipynb: https://github.com/MouseLand/cellpose/blob/main/notebooks/run_Cellpose-SAM.ipynb