Merge branch 'MouseLand:main' into distributed

Author: erjel

.github/ISSUE_TEMPLATE/bug_report.md

@@ -6,23 +6,34 @@ labels: bug
 assignees: ''
 
 ---
+## Before you fill out this form:
+**Did you review the FAQ?**
+- [ ] Yes, I reviewed the FAQ on the [cellpose ReadTheDocs](https://cellpose.readthedocs.io/en/latest/faq.html) 
 
-**Describe the bug**
+**Did you look through previous (open AND closed) issues posted on GH?**
+- [ ] Yes, I [searched for related previous GH issues](https://github.com/MouseLand/cellpose/issues?q=is%3Aissue).
+
+## Now fill this form out completely:
+### **Describe the bug**
 A clear and concise description of what the bug is.
 
-**To Reproduce**
+### **To Reproduce**
 Steps to reproduce the behavior:
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
 4. See error 
 
-**Run log**
+### **Run log**
 Please post all command line/notebook output for us to understand the problem. For this please make sure you are running with verbose mode on. So command line, with `--verbose` tag, or in a notebook first run 
 ```from cellpose import io 
 logger = io.logger_setup()
 ``` 
 before running any Cellpose functions.
 
-**Screenshots**
+<details><summary>Run logs</summary>
+your logs here.
+</details>
+
+### **Screenshots**
 If applicable, add screenshots to help explain your problem.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/feature_request.md

@@ -6,15 +6,22 @@ labels: enhancement
 assignees: ''
 
 ---
+## Before you fill out this form:
+**Did you review the FAQ?**
+- [ ] Yes, I reviewed the FAQ on the [cellpose ReadTheDocs](https://cellpose.readthedocs.io/en/latest/faq.html) 
 
-**Is your feature request related to a problem? Please describe.**
+**Did you look through previous (open AND closed) issues posted on GH?**
+- [ ] Yes, I [searched for related previous GH issues](https://github.com/MouseLand/cellpose/issues?q=is%3Aissue).
+
+## Now fill this form out completely:
+### **Is your feature request related to a problem? Please describe.**
 A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
 
-**Describe the solution you'd like**
+### **Describe the solution you'd like**
 A clear and concise description of what you want to happen.
 
-**Describe alternatives you've considered**
+### **Describe alternatives you've considered**
 A clear and concise description of any alternative solutions or features you've considered.
 
-**Additional context**
+### **Additional context**
 Add any other context or screenshots about the feature request here.

.github/ISSUE_TEMPLATE/installation-issue.md

@@ -6,14 +6,25 @@ labels: install
 assignees: ''
 
 ---
+## Before you fill out this form:
+**Did you review the FAQ?**
+- [ ] Yes, I reviewed the FAQ on the [cellpose ReadTheDocs](https://cellpose.readthedocs.io/en/latest/faq.html) 
 
-**Install problem**
+**Did you look through previous (open AND closed) issues posted on GH?**
+- [ ] Yes, I [searched for related previous GH issues](https://github.com/MouseLand/cellpose/issues?q=is%3Aissue).
+
+## Now fill this form out completely:
+### **Install problem**
 Let us know what issues you are having with installation.
 
-**Environment info**
+### **Environment info**
 Please run `conda list` in your cellpose environment in the terminal / anaconda prompt to let us know your software versions.
 
-**Run log**
+<details><summary>Conda list output</summary>
+your conda list output
+</details>
+
+### **Run log**
 Please post all command line/notebook output for us to understand the problem. For this please make sure you are running with verbose mode on. So command line, with `--verbose` tag, or in a notebook first run 
 
 ```from cellpose import io 

cellpose/core.py

@@ -77,7 +77,7 @@ def assign_device(use_torch=True, gpu=False, device=0):
     if isinstance(device, str):
         if device != "mps" or not(gpu and torch.backends.mps.is_available()):
             device = int(device)
-    if gpu and use_gpu(use_torch=True):
+    if gpu and use_gpu(gpu_number=device, use_torch=use_torch):
         try:
             if torch.cuda.is_available():
                 device = torch.device(f'cuda:{device}')

cellpose/io.py

@@ -692,7 +692,7 @@ def save_masks(images, masks, flows, file_names, png=True, tif=False, channels=[
         save_outlines (bool, optional): Save outlines of masks. Defaults to False.
         dir_above (bool, optional): Save masks/flows in directory above. Defaults to False.
         in_folders (bool, optional): Save masks/flows in separate folders. Defaults to False.
-        savedir (str, optional): Absolute path where images will be saved. If None, saves to image directory. Defaults to None.
+        savedir (str, optional): Absolute or relative path where images will be saved. If None, saves to image directory. Defaults to None.
         save_txt (bool, optional): Save masks as list of outlines for ImageJ. Defaults to False.
         save_mpl (bool, optional): If True, saves a matplotlib figure of the original image/segmentation/flows. Does not work for 3D.
                 This takes a long time for large images. Defaults to False.
@@ -724,11 +724,11 @@ def save_masks(images, masks, flows, file_names, png=True, tif=False, channels=[
 
     if savedir is None:
         if dir_above:
-            savedir = Path(file_names).parent.parent.absolute(
-            )  #go up a level to save in its own folder
+            savedir = Path(file_names).parent.parent#go up a level to save in its own folder
         else:
-            savedir = Path(file_names).parent.absolute()
+            savedir = Path(file_names).parent
 
+    savedir = Path(savedir).resolve()
     check_dir(savedir)
 
     basename = os.path.splitext(os.path.basename(file_names))[0]

cellpose/train.py

@@ -310,7 +310,7 @@ def train_seg(net, train_data=None, train_labels=None, train_files=None,
               train_labels_files=None, train_probs=None, test_data=None,
               test_labels=None, test_files=None, test_labels_files=None,
               test_probs=None, channel_axis=None,
-              load_files=True, batch_size=1, learning_rate=5e-5, SGD=False,
+              load_files=True, batch_size=1, learning_rate=1e-5, SGD=False,
               n_epochs=100, weight_decay=0.1, normalize=True, compute_flows=False,
               save_path=None, save_every=100, save_each=False, nimg_per_epoch=None,
               nimg_test_per_epoch=None, rescale=False, scale_range=None, bsize=256,
@@ -331,11 +331,10 @@ def train_seg(net, train_data=None, train_labels=None, train_files=None,
         test_labels_files (list or None): List of test label file paths. Defaults to None.
         test_probs (List[float], optional): List of floats - probabilities for each image to be selected during testing. Defaults to None.
         load_files (bool, optional): Boolean - whether to load images and labels from files. Defaults to True.
-        batch_size (int, optional): Integer - number of patches to run simultaneously on the GPU. Defaults to 8.
-        learning_rate (float or List[float], optional): Float or list/np.ndarray - learning rate for training. Defaults to 0.005.
-        n_epochs (int, optional): Integer - number of times to go through the whole training set during training. Defaults to 2000.
-        weight_decay (float, optional): Float - weight decay for the optimizer. Defaults to 1e-5.
-        momentum (float, optional): Float - momentum for the optimizer. Defaults to 0.9.
+        batch_size (int, optional): Integer - number of patches to run simultaneously on the GPU. Defaults to 1.
+        learning_rate (float or List[float], optional): Float or list/np.ndarray - learning rate for training. Defaults to 1e-5.
+        n_epochs (int, optional): Integer - number of times to go through the whole training set during training. Defaults to 100.
+        weight_decay (float, optional): Float - weight decay for the optimizer. Defaults to 0.1.
         SGD (bool, optional): Deprecated in v4.0.1+ - AdamW always used.
         normalize (bool or dict, optional): Boolean or dictionary - whether to normalize the data. Defaults to True.
         compute_flows (bool, optional): Boolean - whether to compute flows during training. Defaults to False.
@@ -344,7 +343,7 @@ def train_seg(net, train_data=None, train_labels=None, train_files=None,
         save_each (bool, optional): Boolean - save the network to a new filename at every [save_each] epoch. Defaults to False.
         nimg_per_epoch (int, optional): Integer - minimum number of images to train on per epoch. Defaults to None.
         nimg_test_per_epoch (int, optional): Integer - minimum number of images to test on per epoch. Defaults to None.
-        rescale (bool, optional): Boolean - whether or not to rescale images during training. Defaults to True.
+        rescale (bool, optional): Boolean - whether or not to rescale images during training. Defaults to False.
         min_train_masks (int, optional): Integer - minimum number of masks an image must have to use in the training set. Defaults to 5.
         model_name (str, optional): String - name of the network. Defaults to None.
 

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

tox.ini

@@ -36,5 +36,4 @@ deps =
 # ignoring contrib tests for now
 commands = 
     #linux: apt-get update && apt-get install libgl1
-    pytest -v --color=yes --cov=cellpose --cov-report=xml --ignore=tests/contrib
-    
+    pytest -vv -rA --color=yes --cov=cellpose --cov-report=xml --ignore=tests/contrib --durations=0