A plugin to use with napari for clustering objects according to their properties
Project description
napari-clusters-plotter
A plugin to use with napari for clustering objects according to their properties.
This napari plugin was generated with Cookiecutter using with @napari's cookiecutter-napari-plugin template.
Usage
Starting point
For clustering objects according to their properties, the starting point is a grey-value image and a label image representing a segmentation of objects. For segmenting objects, you can for example use the Voronoi-Otsu-labelling approach in the napari plugin napari-segment-blobs-and-things-with-membranes.
Measurements
The first step is deriving measurements from the labelled image and the corresponding pixels in the grey-value image.
You can use the menu Tools > Measurement > Measure intensity, shape and neighbor counts (ncp)
for that.
Just select the image, the corresponding label image and the measurements to analyse and click on Run
.
A table with the measurements will open:
Afterwards, you can save and/or close the measurement table. Also, close the Measure widget.
Time-Lapse Measurements
If you have 3D time-lapse data this will automatically be detected. In case you have 2D time-lapse data you need to
convert it into a suitable shape using the function: Tools > Utilities > Convert 3D stack to 2D time-lapse (time-slicer)
,
which can be found in the napari time slicer.
Note that tables for time-lapse data will include an additional column named "frame", which indicates which slice in
time the given row refers to. If you want to import your own csv files for time-lapse data make sure to include this column!
Plotting
Once measurements were made, these measurements were saved in the properties
of the labels layer which was analysed.
You can then plot these measurements using the menu Tools > Measurement > Plot measurement (ncp)
.
In this widget, you can select the labels layer which was analysed and the measurements which should be plotted
on the X- and Y-axis. If you cannot see any options in axes selection boxes, but you have performed measurements, click
on Update Axes/Clustering Selection Boxes
to refresh them. Click on Run
to draw the data points in the plot area.
You can also manually select a region in the plot. To use lasso (freehand) tool use left mouse click, and to use a rectangle - right click. The resulting manual clustering will also be visualized in the original image. To optimize visualization in the image, turn off the visibility of the analysed labels layer.
Hold down the SHIFT key while annotating regions in the plot to manually select multiple clusters.
Time-Lapse Plotting
When you plot your time-lapse datasets you will notice that the plots look slightly different. Datapoints of the current time frame are highlighted in white and you can see the datapoints move through the plot if you press play:
You can also manually select groups using the lasso tool and plot a measurement per frame and see how the group behaves in time. Furthermore, you could also select a group in time and see where the datapoints lie in a different feature space:
Dimensionality reduction: UMAP, t-SNE or PCA
For getting more insights into your data, you can reduce the dimensionality of the measurements, e.g.
using the UMAP algorithm, t-SNE
or PCA.
To apply it to your data use the menu Tools > Measurement > Dimensionality reduction (ncp)
.
Select the label image that was analysed and in the list below, select all measurements that should be
dimensionality reduced. By default, all measurements are selected in the box. If you cannot see any measurements, but
you have performed them, click on Update Measurements
to refresh the box. You can read more about parameters of both
algorithms by hovering over question marks or by clicking on them. When you are done with the selection, click on Run
and after a moment, the table of measurements will re-appear with two additional columns representing the reduced
dimensions of the dataset. These columns are automatically saved in the properties
of the labels layer so there is no
need to save them for usage in other widgets unless you wish to do so.
Afterwards, you can again save and/or close the table. Also, close the Dimensionality Reduction widget.
Clustering
If manual clustering, as shown above, is not an option, you can automatically cluster your data, using these implemented algorithms:
- k-means clustering (KMEANS)
- Hierarchical Density-Based Spatial Clustering of Applications with Noise (HDBSCAN)
- Gaussian Mixture Model (GMM)
- Mean Shift (MS)
- Agglomerative clustering (AC)
Therefore, click the menu Tools > Measurement > Clustering (ncp)
,
again, select the analysed labels layer.
This time select the measurements for clustering, e.g. select only the UMAP
measurements.
Select the clustering method KMeans
and click on Run
.
The table of measurements will reappear with an additional column ALGORITHM_NAME_CLUSTERING_ID
containing the cluster
ID of each datapoint.
Afterwards, you can again save and/or close the table. Also, close the clustering widget.
Plotting clustering results
Return to the Plotter widget using the menu Tools > Measurement > Plot measurement (ncp)
.
Select UMAP_0
and UMAP_1
as X- and Y-axis and the ALGORITHM_NAME_CLUSTERING_ID
as Clustering
, and click on Run
.
Example of k-means clustering results:
Installation
- Get a python environment, e.g. via mini-conda. If you never used python/conda environments before, please follow the instructions here first. It is recommended to install python 3.9 to your new conda environment from the start. The plugin is not yet supported with Python 3.10. Create a new environment, for example, like this:
conda create --name ncp-env python=3.9
- Activate the new environment via conda:
conda activate ncp-env
- Install pyopencl, e.g. via conda:
conda install -c conda-forge pyopencl
python -m pip install "napari[all]"
Afterwards, you can install napari-clusters-plotter
via pip:
pip install napari-clusters-plotter
Troubleshooting installation
- If the plugin does not appear in napari 'Plugins' menu, and in 'Plugin errors...' you can see such an error:
ImportError: DLL load failed while importing _cl
Try downloading and installing a pyopencl with a lower cl version, e.g. cl12 : pyopencl=2020.1. However, in this case, you will need an environment with a lower python version (python=3.8).
Error: Could not build wheels for hdbscan which use PEP 517 and cannot be installed directly
Install hdbscan via conda before installing the plugin:
conda install -c conda-forge hdbscan
ValueError: numpy.ndarray size changed, may indicate binary incompatibility. Expected 96 from C header, got 88 from PyObject
Similar to the above-described error, this error can occur when importing hdbscan through pip or in the wrong order. This can be fixed by installing packages separately through conda and in the following order:
conda install -c conda-forge napari pyopencl hdbscan
pip install napari-clusters-plotter
WARNING: No ICDs were found
orLogicError: clGetPlatformIDs failed: PLATFORM_NOT_FOUND_KHR
Make your system-wide implementation visible by installing either of the following conda packages:
conda install -c conda-forge ocl-icd-system
conda install -c conda-forge ocl_icd_wrapper_apple
Contributing
Contributions are very welcome. Tests can be run with pytest, please ensure the coverage at least stays the same before you submit a pull request.
License
Distributed under the terms of the BSD-3 license, "napari-clusters-plotter" is free and open source software
Issues
If you encounter any problems, please file an issue along with a detailed description.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for napari-clusters-plotter-0.5.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | e76018d65b4f23906623c319a7174838241b7f116cf17fff9666910ccc8d05a5 |
|
MD5 | 967416a331313c404f9a90dd2bf65328 |
|
BLAKE2b-256 | 9938b900ce2c588e00fcc032caaf5baf3c15afe52ac739681ae8c39fcbb5cd19 |
Hashes for napari_clusters_plotter-0.5.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6eded530e75697f03b8ec2382b9d10f51a0f4a99e010ca387d677711deeaf331 |
|
MD5 | 60780ac948c59ca6eb741965085fc306 |
|
BLAKE2b-256 | 3525ce0fd604e59fc01f276248e00645fca5716bca7ae3a432edbcf194560063 |