Skip to content

Commit f483eff

Browse files
veegalinovaveegalinova
committed
initial commit
0 parents  commit f483eff

19 files changed

Lines changed: 851 additions & 0 deletions

‎LICENSE‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
BSD 3-Clause License
2+
3+
Copyright (c) 2024, AI4Life Open Calls
4+
5+
Redistribution and use in source and binary forms, with or without
6+
modification, are permitted provided that the following conditions are met:
7+
8+
1. Redistributions of source code must retain the above copyright notice, this
9+
list of conditions and the following disclaimer.
10+
11+
2. Redistributions in binary form must reproduce the above copyright notice,
12+
this list of conditions and the following disclaimer in the documentation
13+
and/or other materials provided with the distribution.
14+
15+
3. Neither the name of the copyright holder nor the names of its
16+
contributors may be used to endorse or promote products derived from
17+
this software without specific prior written permission.
18+
19+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎README.md‎

Lines changed: 236 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,236 @@
1+
<p align="center">
2+
<a href="https://ai4life.eurobioimaging.eu/open-calls/">
3+
<img src="https://github.com/ai4life-opencalls/.github/blob/main/AI4Life_banner_giraffe_nodes_OC.png?raw=true" width="70%">
4+
</a>
5+
</p>
6+
7+
# Project #11: Segmentation and tracking of epithelial cells
8+
9+
---
10+
This page was created by the [AI4Life project](https://ai4life.eurobioimaging.eu) using data provided by Madeline Lovejoy and Rafael Garcia-Mata (PhD) at [Garcia-Mata Lab](https://www.garciamatalab.com/)
11+
12+
13+
If any of the instructions are not working, please [open an issue](https://github.com/ai4life-opencalls/project_11/issues) or contact us at [ai4life@fht.org](ai4life@fht.org)!
14+
15+
**Project challenges**: denoising, cell instance segmentation, cell tracking.
16+
17+
18+
## Table of Contents
19+
1. [Introduction](#introduction)
20+
2. [Installation](#installation)
21+
3. [Denoising with N2V](#step-1-denoising-with-n2v)
22+
4. [Segmentation with Cellpose](#step-2-segmentation-with-cellpose)
23+
6. [Tracking with Trackmate-Cellpose](#step-3-tracking-with-trackmate-cellpose-in-fiji)
24+
7. [Conclusion](#conclusion)
25+
26+
27+
## Introduction
28+
Researchers from [The University of Toledo](https://www.utoledo.edu/) [Garcia-Mata Lab](https://www.garciamatalab.com/) are imaging a confluent 2D monolayer of epithelial cells. The monolayer is scratched with a pipette tip, and the video shows the migration of the cells to close the wound. They would like to compare the behavior of different cell lineages automatically. They are interested in segmenting and tracking individual cells and nuclei in time.
29+
30+
In this tutorial, we will demonstrate how to segment and track individual epithelial cells in a series of images obtained with fluorescence microscopy.
31+
32+
We will start by denoising the images using [N2V](https://github.com/juglab/n2v) Python package, which denoises microscopy images using deep learning. Next, we will segment cells using [Cellpose](https://www.cellpose.org/), a popular deep-learning cell segmentation algorithm. Finally, we'll track the segmented cells using the TrackMate plugin in Fiji.
33+
34+
Here is a visualization of the original data and resulting tracking:
35+
<div>
36+
<img src="resources/tutorial_images/MAX_CTRL_Wound1_cropped_result.gif" width="100%">
37+
</div>
38+
39+
Data is provided under a CC-BY license.
40+
41+
Let's get started! 🚀
42+
43+
## Installation
44+
45+
### Install Python package manager
46+
We recommend installing [conda](https://conda.io/projects/conda/en/latest/user-guide/install/index.html) or [mamba](https://mamba.readthedocs.io/en/latest/). Go to the website and follow the installation instructions for your operating system.
47+
During installation, select the installation folder that you have permissions for, such as your home folder.
48+
49+
### Install N2V
50+
Follow [N2V installation](https://github.com/juglab/n2v) for official instructions.
51+
<details>
52+
<summary>N2V installation details</summary>
53+
54+
1. Open terminal (such as Terminal on MacOS, for Windows we recommand [Git for Windows](https://gitforwindows.org/))
55+
2. Create and activate a new conda environment:
56+
```bash
57+
conda create -n n2v python=3.9
58+
conda activate n2v
59+
```
60+
3. Install Tensorflow by following the [official instructions](https://www.tensorflow.org/install/pip#linux_1). If you have no GPU available, install the CPU version.
61+
N2V only supports Tensorflow 2. We'll now install version 2.13.0 with GPU support as an example:
62+
```bash
63+
pip install tensorflow[and-cuda]==2.13.0
64+
```
65+
4. Check if the installation is correct. If you are using GPU, this command should return a list of available devices:
66+
```bash
67+
python -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"
68+
```
69+
5. Install N2V and Jupyter:
70+
```bash
71+
pip install n2v jupyter
72+
```
73+
</details>
74+
75+
### Install Cellpose
76+
Follow [Cellpose installation](https://github.com/MouseLand/cellpose) for official instructions.
77+
If you are using GPU check out [GPU version (CUDA) on Windows or Linux](https://github.com/MouseLand/cellpose?tab=readme-ov-file#gpu-version-cuda-on-windows-or-linux) section.
78+
79+
<details>
80+
<summary>Cellpose installation details</summary>
81+
82+
1. We recommend creating a new separate environment:
83+
```bash
84+
conda create -n cellpose python=3.9
85+
conda activate cellpose
86+
```
87+
2. Install PyTorch by following the [official instructions](https://pytorch.org/).
88+
If you have a GPU, select a version that is compatible with your driver version. Follow [this link](https://pytorch.org/get-started/previous-versions/) for older versions.
89+
We will be installing PyTorch version 1.12 and cudatoolkit version 11.3 as an example:
90+
```bash
91+
conda install pytorch==1.12.0 torchvision==0.13.0 cudatoolkit=11.3 -c pytorch
92+
```
93+
3. Check if the installation is correct. If you are using GPU, this command should return a list of available devices:
94+
```bash
95+
python -c "import torch; print([torch.cuda.get_device_properties(i) for i in range(torch.cuda.device_count())])"`
96+
```
97+
4. Install Cellpose:
98+
```bash
99+
pip install pyqt5 "cellpose[gui]"
100+
```
101+
5. Check the installation by running Cellpose. You should see the Cellpose window open:
102+
```bash
103+
cellpose
104+
```
105+
</details>
106+
107+
### Install TrackMate-Cellpose
108+
Follow [TrackMate-Cellpose](https://imagej.net/plugins/trackmate/detectors/trackmate-cellpose) for official instructions.
109+
<details>
110+
<summary>TrackMate-Cellpose installation details</summary>
111+
112+
1. Open Fiji.
113+
2. Add The **TrackMate-Cellpose** update site and restart Fiji.
114+
3. In your **cellpose** conda environment, run this command to find where your python is installed:
115+
```bash
116+
which python
117+
```
118+
4. Open TrackMate and select **Cellpose detector** from the list of available detectors.
119+
5. Insert the path to your python in Path to Cellpose
120+
</details>
121+
122+
## Step #1: Denoising with N2V
123+
If the images are noisy, denoising can help achieve better segmentation performance. Most deep learning segmentation models are trained with clean images, so noise in the data severely affects the resulting accuracy.
124+
125+
You will likely need to re-train the denoising model for different experiments because differences in noise distribution will affect the performance, but worry not N2V is quite fast to train!
126+
127+
N2V offers a [Python package](https://github.com/juglab/n2v) and a [napari plugin](https://github.com/juglab/napari-n2v), or if you do not have a GPU available, you can try using a Google Colab N2V notebook from [ZeroCostDL4Mic](https://github.com/HenriquesLab/ZeroCostDL4Mic).
128+
129+
### Usage:
130+
1. Download the example jupyter notebook here: [N2V_denoising.ipynb](resources/notebooks/N2V_denoising.ipynb)
131+
2. Download example data series here: **TBD**
132+
3. Activate the conda environment
133+
```bash
134+
conda activate n2v
135+
```
136+
4. Run jupyter service
137+
```bash
138+
jupyter notebook
139+
```
140+
5. In the opened browser page, open the notebook and follow the instructions.
141+
6. To run a pre-trained model, download and unzip the [pretrained model](resources/trained_models/n2v_2D.zip). Then, in the Jupyter Notebook, go to the section *7. Prediction*.
142+
143+
Here is an example of an original and denoised image:
144+
<div>
145+
<img src="resources/tutorial_images/noisy_denoised.jpg" width="100%">
146+
</div>
147+
148+
149+
## Step #2: Segmentation with Cellpose
150+
### Usage
151+
[Cellpose](https://github.com/MouseLand/cellpose) is a popular deep-learning cell segmentation algorithm.
152+
1. Download and unzip pre-trained models for membrane and nuclei segmentation: [cellpose_membrane_model.zip](resources/trained_models/cellpose_membrane_model.zip)
153+
2. Activate the conda environment
154+
```bash
155+
conda activate cellpose
156+
```
157+
3. Run Cellpose
158+
```bash
159+
cellpose
160+
```
161+
4. Select the channels you want to segment. If you want to segment entire cells, add the membranes as `chan to segment` and nuclei as `chan2`. If you want to segment only nuclei, and them to `chan to segment` and leave `chan2` empty.
162+
5. Calibrate the average object size automatically by clicking `callibrate`. The circle on the bottom-left should be approximately the size of the objects you want to segment.
163+
6. Check how default models perform on the data by clicking any in the `model zoo` section.
164+
7. Add a custom pretrained model to the interface: ``Models > Add custom torch model to GUI``.
165+
8. Select this model in the `custom models` section and run it by clicking `run model`.
166+
167+
<div>
168+
<img src="resources/tutorial_images/cellpose_interface.png" width="70%">
169+
</div>
170+
171+
172+
### How to train your own model
173+
174+
You can watch a video tutorial on how to use Cellpose here - [https://www.cellpose.org/](https://www.cellpose.org/)
175+
176+
1. Find the best working model from the `model zoo` section.
177+
2. Look through the errors in the predictions and correct a few of them. `Click Help` > `Help with GUI` for help with labeling controls.
178+
3. Train a new model on the corrected data. Click `Models` > `Train new model`.
179+
4. Choose the best model from step 3 as an initial model. You cannot select a custom model as an initial model.
180+
5. We suggest using the following settings:
181+
<div>
182+
<img src="resources/tutorial_images/cellpose_settings.png" width="50%">
183+
</div>
184+
185+
6. After training, you’ll see your new model in the `custom models` section. It will also be saved in the folder with your data. `Cell diameter` will also be updated with what the model learned from the data.
186+
7. You can continue iterating: predict with the model - fix a couple of mistakes - train a new model - fix mistakes - train a new model
187+
188+
189+
# Step #3: Tracking with Trackmate-Cellpose in Fiji
190+
191+
To use the resulting model on a time series and track the segmentations, install the [TrackMate-Cellpose](https://imagej.net/plugins/trackmate/detectors/trackmate-cellpose)
192+
integration in Fiji.
193+
194+
### Usage
195+
1. Open a **denoised** time series.
196+
2. Check if `Path to cellpose` is correct.
197+
3. Select `Custom` model from `Pretrained model`.
198+
4. Select the channels you want to segment.
199+
5. Select the path to your model. Enter the channels you want to segment and the approximate diameter of your objects.
200+
Here is an example of the settings:
201+
<div>
202+
<img src="resources/tutorial_images/trackmate_cellpose.png" width="50%">
203+
</div>
204+
205+
6. Press `preview` to run prediction on one timepoint and check the result. The objects on the image should now be highlighted.
206+
<div>
207+
<img src="resources/tutorial_images/first_prediction.jpg" width="50%">
208+
</div>
209+
210+
7. Press `next` to run prediction on all time points (it can take a while). Do not filter the resulting spots.
211+
8. For tracking, we chose the LAP tracker. Here are the settings we used:
212+
<div>
213+
<img src="resources/tutorial_images/trackmate_tracking_settings.png" width="50%">
214+
</div>
215+
216+
9. Here are the visualization settings we used:
217+
<div>
218+
<img src="resources/tutorial_images/trackmate_vis_settings.png" width="50%">
219+
</div>
220+
221+
10. To improve the results, consider different distance settings, feature penalties, and track filtering.
222+
223+
<div align="left">
224+
<img src="resources/tutorial_images/trackmate_result.gif" width="50%">
225+
</div>
226+
227+
## Conclusion
228+
In this tutorial, we showed how to use [N2V](https://github.com/juglab/n2v), [https://www.cellpose.org/](https://www.cellpose.org/), and [TrackMate-Cellpose](https://imagej.net/plugins/trackmate/detectors/trackmate-cellpose) to segment and track nuclei of epithelial cells in a series of images obtained with fluorescence microscopy.
229+
230+
[AI4Life](https://ai4life.eurobioimaging.eu) is a Horizon Europe-funded project that brings together the computational and life science communities.
231+
232+
AI4Life has received funding from the European Union’s Horizon Europe research and
233+
innovation programme under grant agreement number 101057970. Views and opinions
234+
expressed are however those of the author(s) only and do not necessarily reflect those
235+
of the European Union or the European Research Council Executive Agency. Neither the
236+
European Union nor the granting authority can be held responsible for them.

‎README.pdf‎

2.27 MB
Binary file not shown.

0 commit comments

Comments
 (0)