setup cellpose for usage within mcmicro (#514)

* 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 <[email protected]> Co-authored-by: Krešimir Beštak <[email protected]>
labsyspharm · Aug 23, 2023 · e1e2adf · e1e2adf
1 parent b6bf5c5
commit e1e2adf
Show file tree

Hide file tree

Showing 4 changed files with 100 additions and 3 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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}