From e1e2adf638e611f2b5caf3f9ac0e22b65fca56c4 Mon Sep 17 00:00:00 2001
From: VictorDidier <68292394+VictorDidier@users.noreply.github.com>
Date: Wed, 23 Aug 2023 04:37:44 +0200
Subject: [PATCH] setup cellpose for usage within mcmicro (#514)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Allow user model input

* Added pattern for MCQUANT that works with Cellpose masks

* Update mcquant default pattern

* setup cellpose for usage and added documentation

---------

Co-authored-by: kbestak <kbestak@gmail.com>
Co-authored-by: Krešimir Beštak <86408271+kbestak@users.noreply.github.com>
---
 config/defaults.yml      |  6 ++---
 config/schema.yml        |  1 +
 docs/parameters/core.md  | 48 ++++++++++++++++++++++++++++++++++++++++
 docs/parameters/other.md | 48 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 100 insertions(+), 3 deletions(-)

diff --git a/config/defaults.yml b/config/defaults.yml
index 624469ed..0e410ec4 100644
--- a/config/defaults.yml
+++ b/config/defaults.yml
@@ -14,7 +14,7 @@ options:
   ashlar: -m 30
   cypository: --model zeisscyto
   ilastik: --num_channels 1
-  mcquant: --masks cell*.tif
+  mcquant: --masks cell*.tif *_cp_masks*.tif
   naivestates: -p png
 modules:
   illumination:
@@ -78,9 +78,9 @@ modules:
       name: cellpose
       container: biocontainers/cellpose
       version: 2.1.1_cv2
-      cmd: cellpose --channel_axis 0 --save_tif --savedir .
+      cmd: cellpose --channel_axis 0 --save_tif --savedir . --verbose
       input: --image_path
-      channel: --chan
+      model: --pretrained_model
       idxbase: 0
       watershed: 'no'
   watershed:
diff --git a/config/schema.yml b/config/schema.yml
index 1c4e62ed..2273f97f 100644
--- a/config/schema.yml
+++ b/config/schema.yml
@@ -14,6 +14,7 @@ workflow:
   - ilastik-model
   - mesmer-model
   - background
+  - cellpose-model
 deprecated:
   quantification-mask: "--quant-opts '--masks ...'"
   illum: --start-at illumination
diff --git a/docs/parameters/core.md b/docs/parameters/core.md
index dffa25b4..ea0b13b5 100755
--- a/docs/parameters/core.md
+++ b/docs/parameters/core.md
@@ -500,6 +500,7 @@ Annotated narratives must be manually generated, and users must provide MCMICRO
 | [Ilastik](./core.html#ilastik) | Probability map generator | [Code](https://github.com/labsyspharm/mcmicro-ilastik) - [DOI](https://doi.org/10.1038/s41592-019-0582-9) |
 | [Cypository](./core.html#ilastik) | Probability map generator (cytoplasm only) | [Code](https://github.com/HMS-IDAC/Cypository) |
 | [Mesmer](./core.html#mesmer) | Instance segmentation | [Code](https://github.com/vanvalenlab/deepcell-applications) - [DOI](https://doi.org/10.1038/s41587-021-01094-0) |
+| [Cellpose](./core.html#cellpose) | Instance segmentation | [Code](https://github.com/MouseLand/cellpose) - [DOI](https://doi.org/10.1038/s41592-022-01663-4) |
 | [naivestates](./core.html#naivestates) | Cell type calling with Naive Bayes | [Code](https://github.com/labsyspharm/naivestates) |
 | [FastPG](./core.html#clustering) | Clustering (Louvain community detection) | [Code](https://github.com/labsyspharm/mcmicro-fastPG) - [DOI](https://www.biorxiv.org/content/10.1101/2020.06.19.159749v2) |
 | [scanpy](./core.html#clustering) | Clustering (Leiden community detection) | [Code](https://github.com/labsyspharm/mcmicro-scanpy) |
@@ -632,6 +633,53 @@ A segmentation mask, similar to the ones produced by S3segmenter. Nextflow will
 
 ---
 
+## Cellpose
+{: .fw-500}
+
+### Description
+Cellpose is a DL segmentation algorithm able to segment the nuclear or cytoplasmic compartments of the cell.  Publications of this algorithm can be found in [1](https://www.nature.com/articles/s41592-020-01018-x){:target="_blank"} and [2](https://www.nature.com/articles/s41592-022-01663-4){:target="_blank"}.  A thorough documentation of the script and CLI can be found [here](https://cellpose.readthedocs.io/en/latest/index.html){:target="_blank"}.
+
+### Usage
+
+To use this segmentation method add the line `segmentation: cellpose` in the workflow section of the `params.yml` file.  Under the options section of `params.yml` specify the input arguments of the cellpose script, such as segmentation model and channel(s) on which the model will be applied.  Notice that the channel(s) argument(s), i.e. --chan and --chan2, expect a zero-based index.  
+
+For large data sets it is recommended to use the parameters `segmentation-recyze: true` along with `segmentation-channel:`.  In the example below we consider an image stack of 10 channels with the nuclear marker in channel 2 and membrane marker in channel 7.  The use of `segmentation-recyze: true` will reduce the image stack to these two channels prior to segmentation, hence reindexing the stack channels such that 2-->0 and 7-->1.
+
+
+* Example `params.yml`:
+
+``` yaml
+workflow:
+  segmentation-channel: 2 7 
+  segmentation-recyze: true
+  segmentation: cellpose
+options:
+  cellpose: --pretrained_model cyto --chan 1 --chan2 0 --no_npy
+```
+* Running outside of MCMICRO: [Github](https://github.com/MouseLand/cellpose){:target="_blank"}, [Instructions](https://cellpose.readthedocs.io/en/latest/installation.html){:target="_blank"}.
+
+### Input
+
+* The image (`.tif`) to be segmented should be in the `registration/` subdirectory.
+* --pretained_model: name of the built-in model to be used for segmentation, options include “_nuclei_”,“_cyto_” and “_cyto2_”.  Alternatively you can give a file path to a custom retrained model.  Custom models can be trained in the [cellpose GUI](https://cellpose.readthedocs.io/en/latest/gui.html){:target="_blank"}.
+* --chan: zero-based index of the channel on which the segmentation model will be applied.  When using the “nuclei” model provide the index of the nuclear channel, e.g. DAPI.  In the case of the "cyto" models provide the channel of the membrane marker.
+* --chan2 [optional]: index of the nuclear marker channel.  This argument is valid only when using the "cyto" models.
+
+### Output
+
+A `.tif` image with the segmentation masks in the `segmentation/` subdirectory.
+
+### Optional arguments
+
+| Name | Description | Default Value |
+| :--- | :--- | :--- |
+| `--pretrained_model` | Name of a built-in segmentation model or a file path to a custom model. | `cyto` |
+| `--chan` | Index of the selected channel to segment.  | `0` |
+| `--chan2` | Index of the nuclear marker channel. | `0` |
+| `--no_npy` | Boolean flag to suppress saving the .npy files output (recommended to avoid overflow errors when processing large data sets). | `False` |
+
+---
+
 ## Clustering
 {: .fw-500}
 
diff --git a/docs/parameters/other.md b/docs/parameters/other.md
index 39f082eb..700bef16 100755
--- a/docs/parameters/other.md
+++ b/docs/parameters/other.md
@@ -12,6 +12,7 @@ Segmentation
 1. [Ilastik](./other.html#ilastik)
 1. [Cypository](./other.html#cypository)
 1. [Mesmer](./other.html#mesmer)
+1. [Cellpose](./other.html#cellpose)
 
 Clustering and cell type inference
 1. [Clustering](./other.html#clustering) 
@@ -147,6 +148,53 @@ A segmentation mask, similar to the ones produced by S3segmenter. Nextflow will
 
 ---
 
+## Cellpose
+{: .fw-500}
+
+### Description
+Cellpose is a DL segmentation algorithm able to segment the nuclear or cytoplasmic compartments of the cell.  Publications of this algorithm can be found in [1](https://www.nature.com/articles/s41592-020-01018-x){:target="_blank"} and [2](https://www.nature.com/articles/s41592-022-01663-4){:target="_blank"}.  A thorough documentation of the script and CLI can be found [here](https://cellpose.readthedocs.io/en/latest/index.html){:target="_blank"}.
+
+### Usage
+
+To use this segmentation method add the line `segmentation: cellpose` in the workflow section of the `params.yml` file.  Under the options section of `params.yml` specify the input arguments of the cellpose script, such as segmentation model and channel(s) on which the model will be applied.  Notice that the channel(s) argument(s), i.e. --chan and --chan2, expect a zero-based index.  
+
+For large data sets it is recommended to use the parameters `segmentation-recyze: true` along with `segmentation-channel:`.  In the example below we consider an image stack of 10 channels with the nuclear marker in channel 2 and membrane marker in channel 7.  The use of `segmentation-recyze: true` will reduce the image stack to these two channels prior to segmentation, hence reindexing the stack channels such that 2-->0 and 7-->1.
+
+
+* Example `params.yml`:
+
+``` yaml
+workflow:
+  segmentation-channel: 2 7 
+  segmentation-recyze: true
+  segmentation: cellpose
+options:
+  cellpose: --pretrained_model cyto --chan 1 --chan2 0 --no_npy
+```
+* Running outside of MCMICRO: [Github](https://github.com/MouseLand/cellpose){:target="_blank"}, [Instructions](https://cellpose.readthedocs.io/en/latest/installation.html){:target="_blank"}.
+
+### Input
+
+* The image (`.tif`) to be segmented should be in the `registration/` subdirectory.
+* --pretained_model: name of the built-in model to be used for segmentation, options include “_nuclei_”,“_cyto_” and “_cyto2_”.  Alternatively you can give a file path to a custom retrained model.  Custom models can be trained in the [cellpose GUI](https://cellpose.readthedocs.io/en/latest/gui.html){:target="_blank"}.
+* --chan: zero-based index of the channel on which the segmentation model will be applied.  When using the “nuclei” model provide the index of the nuclear channel, e.g. DAPI.  In the case of the "cyto" models provide the channel of the membrane marker.
+* --chan2 [optional]: index of the nuclear marker channel.  This argument is valid only when using the "cyto" models.
+
+### Output
+
+A `.tif` image with the segmentation masks in the `segmentation/` subdirectory.
+
+### Optional arguments
+
+| Name | Description | Default Value |
+| :--- | :--- | :--- |
+| `--pretrained_model` | Name of a built-in segmentation model or a file path to a custom model. | `cyto` |
+| `--chan` | Index of the selected channel to segment.  | `0` |
+| `--chan2` | Index of the nuclear marker channel. | `0` |
+| `--no_npy` | Boolean flag to suppress saving the .npy files output (recommended to avoid overflow errors when processing large data sets). | `False` |
+
+---
+
 ## Clustering
 {: .fw-500}