dropclust 0.0.6
A microscopical image and video platform applied to the analysis of levitating droplet clusters
License: BSD

# <p>  <b>DropClust</b> </p>

<!-- [![Documentation Status](https://readthedocs.org/projects/cellpose/badge/?version=latest)](https://cellpose.readthedocs.io/en/latest/?badge=latest) -->
[![PyPI version](https://badge.fury.io/py/dropclust.svg)](https://badge.fury.io/py/dropclust)
[![Downloads](https://pepy.tech/badge/dropclust)](https://pepy.tech/project/dropclust)
[![Downloads](https://pepy.tech/badge/dropclust/month)](https://pepy.tech/project/dropclust)
[![Python version](https://img.shields.io/pypi/pyversions/dropclust)](https://pypistats.org/packages/dropclust)
<!-- [![Licence: GPL v3](https://img.shields.io/github/license/ITMO-MMRM-lab/cellpose)](https://github.com/ITMO-MMRM-lab/cellpose/blob/master/LICENSE) -->
<!-- [![Contributors](https://img.shields.io/github/contributors-anon/ITMO-MMRM-lab/cellpose)](https://github.com/ITMO-MMRM-lab/cellpose/graphs/contributors) -->
<!-- [![website](https://img.shields.io/website?url=https%3A%2F%2Fwww.cellpose.org)](https://www.cellpose.org) -->
<!-- [![repo size](https://img.shields.io/github/repo-size/ITMO-MMRM-lab/cellpose)](https://github.com/ITMO-MMRM-lab/cellpose/) -->
<!-- [![GitHub stars](https://img.shields.io/github/stars/ITMO-MMRM-lab/cellpose?style=social)](https://github.com/ITMO-MMRM-lab/cellpose/) -->
<!-- [![GitHub forks](https://img.shields.io/github/forks/ITMO-MMRM-lab/cellpose?style=social)](https://github.com/ITMO-MMRM-lab/cellpose/) -->

<img src="https://gitlab.com/MeLlamoArroz/DropClustGUI/-/raw/master/repo/logo.png" width="200" title="dropclust" alt="dropclust"/>

DropClust is an analytical tool that combines computer vision and machine learning algorithms to assess the morphology, geometry, and dynamics of frame videos of droplet clusters (or similar objects). \
Feature extraction capabilities were also added for further visual representation of the results.

Developed by the InfoChemistry scientific center, part of ITMO University.

### Installation

We suggest throught `conda` and `pip` (with `python>=3.9`).

1. Install [Anaconda](https://www.anaconda.com/download/).
2. Open an `anaconda` prompt / command prompt which has conda for python 3 in the path.
3. For a new environment for CPU only, run:\
 `conda create -n dropclust 'python==3.9'`
4. To activate the new environment, run `conda activate dropclust`
5. For NVIDIA GPUs, run:\
 `pip install torch torchvision` \
   We suggest to install CUDA 12.6
6. To install the latest PyPi release of Dropclust and its dependencies (see [setup.py](https://github.com/ITMO-MMRM-lab/cellpose/blob/main/setup.py)), run:\
  `pip install dropclust`.

### System requirements

Linux, Windows and Mac OS are supported for running the code. For running the graphical interface you will need a Mac OS later than Yosemite. At least 8GB of RAM is required to run the software. 16GB-32GB may be required for larger images. The software has been tested on Windows 10, Windows 11, Ubuntu 24.04, Manjaro and limitedly tested on Mac OS.

### Features
We calculate the following metrics / algorithms:

* Subject counting (amount of subjects).
* Area of subject (𝜇𝑚²).
* Roundness (0.0 - 1.0), having 1.0 for a perfect circle.
* Relative center coordinates.
* Voronoi diagram based on the centers.
* Voronoi entropy, a measure of order/chaos in the cells' positions.
* Convex hull.
* Continuous symmetry measure (CSM).
* Subjects segmentation and clustering.
* Color classification.
* Subject detection + tracking.

### General workflow

<img src="https://gitlab.com/MeLlamoArroz/DropClustGUI/-/raw/master/repo/workflow.png" width="800" />

In order to obtain metrics from segmented cells, the initial stained images are merged into a
single image and organized into sub folders to be processed. A cell segmentation
procedure is performed using [Cellpose](https://github.com/MouseLand/cellpose), then we extract the metrics 
and finally we store the results in the form of images and CSV files.

### How to use

Launching Dropclust GUI: 

- Activate the conda environment: `conda activate dropclust` 
- Enter to launch the GUI `python -m dropclust`
- Now, you can load or drag-drop your desired image/video for analysis

Further, we present a usage example:

<!-- ![demo_gif]("/home/mellamoarroz/Documents/dropclust/dropclust_example.gif") -->
<img src="https://gitlab.com/MeLlamoArroz/DropClustGUI/-/raw/master/repo/dropclust_example.gif" width="800"/>

**IMPORTANT**: It’s mandatory to set a pixel-to-micrometer(μm) conversion value (μm per pixel), in order to calculate the droplets area. The input field for this value in the GUI, is named as “Length in μm”. By default this value is automatically acquired if the corresponding metadata file (generated by the microscope after image obtaining) is present in the same folder as the image, and if it shares the same name of the image + ”_Properties.xml”.

<img src="https://gitlab.com/MeLlamoArroz/DropClustGUI/-/raw/master/repo/metrics.png" width="450"/>

Along, there are geometrical and morphological metrics for droplets and droplets clusters respectively as: area, roundness, Voronoi entropy and Continuous Symmetry Measure. \
There is also the option to calculate these metrics for a current single frame or a whole set of frames (video or gif).
After clicking "calculate" it will take a few moments until we get a folder with the same name as the source image, containing the result values ​​in .csv and .png formats. For extra feedback about the processes and alerts, we suggest to stay pending of the python shell.

<img src="https://gitlab.com/MeLlamoArroz/DropClustGUI/-/raw/master/repo/clustering.png" width="450"/>

The second section offers to perform a clustering of droplets (with the option to use centroids as color seeds for each cluster). \
This functionality can be performed post-segmentation, and it is aimed to group droplets by color as their most distinctive feature.

<img src="https://gitlab.com/MeLlamoArroz/DropClustGUI/-/raw/master/repo/models.png" width="450"/>

The third section presents a set of models and custom parameters for droplet segmentation. Allowing the user to preview the result of the segmentation and their outlines once is done (masks and outlines checkboxes), to estimate the size of each droplet (subject diameter) and to make a color distinction based on a predominant primary color present in the droplets (chan to segment). 


### Citation

Work in progress

<!-- If you find our project helpful, use the following bibtex to reference our [paper](https://arxiv.org/abs/2410.18738).

~~~
@article{huaman2024cellpose+,
  title={Cellpose+, a morphological analysis tool for feature extraction of stained cell images},
  author={Huaman, Israel A and Ghorabe, Fares DE and Chumakova, Sofya S and Pisarenko, Alexandra A and Dudaev, Alexey E and Volova, Tatiana G and Ryltseva, Galina A and Ulasevich, Sviatlana A and Shishatskaya, Ekaterina I and Skorb, Ekaterina V and others},
  journal={arXiv preprint arXiv:2410.18738},
  year={2024}
}
~~~

As we work over Cellpose, we ask you to also cite the Cellpose [paper](https://t.co/kBMXmPp3Yn?amp=1). -->