Package: napari-clusters-plotter
napari-clusters-plotterA napari-plugin for clustering objects according to their properties.Jump to:UsageStarting pointMeasurementsTime-Lapse MeasurementsPlottingTime-Lapse PlottingDimensionality reduction: UMAP, t-SNE or PCAClusteringPlotting clustering resultsInstallationTroubleshooting installationContributingLicenseAcknowledgementsUsageStarting pointFor clustering objects according to their properties, the starting point is agrey-value imageand a label image
representing a segmentation of objects. For segmenting objects, you can for example use theVoronoi-Otsu-labelling approachin the napari pluginnapari-segment-blobs-and-things-with-membranes.In case you have 2D time-lapse data you need to convert it into a suitable shape using the menuTools > Utilities > Convert 3D stack to 2D time-lapse (time-slicer)(documentation).MeasurementsThe first step is deriving measurements from the labeled image and the corresponding pixels in the grey-value image.
Use the menuTools > Measurement tables > Regionprops (scikit-image, nsr)to get to the measurement widget (documentation).
Select the image, the corresponding label image and the measurements to analyse and click onRun.
A table with the measurements will open and afterwards, you can save and/or close the measurement table.
At this point it is recommended to close the table and the Measure widget to free space for following steps.You can also load your own measurements you can do this using the menuTools > Measurement tables > Load from CSV (nsr).
If you load custom measurements, please make sure that there is alabelcolumn that specifies the which measurement belongs to which labeled object.
Tables for time-lapse data need to include an additional column namedframe.PlottingOnce measurements were saved in the labels layer which was analysed, you can then plot these measurements using the menuTools > Visualization > Plot measurements (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. Click onPlotto draw the data points in the plot area.Under advanced options, you can also select the plot type histogram which will visualize a 2D histogram. 2D histogram visualization is recommended if you have a very high number of data points.If you choose the same measurement for the X and the Y axis, a histogram will be shown.Under advanced options you will also find the checkbox determining whether not-selected data points should be hidden (shown in grey) or automatically
clustered as another cluster.Manual clusteringYou can 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.Saving manual clusteringManual clustering results can be saved by going toTools > Measurement > Show table (nsr), and clicking onSave as csv.
The saved table will contain a "MANUAL_CLUSTER_ID" column. This column is overwritten every time different clusters are manually selected.Time-Lapse analysisWhen you plot your time-lapse datasets you will notice that the plots look slightly different.
Datapoints of the current time frame are highlighted in bright color and you can see the datapoints move through the plot while you navigate through time: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:If you have custom measurements from tracking data where each column specifies measurements for a track instead of a label at a specific time point, theframecolumn must not be added.Dimensionality reductionFor getting more insights into your data, you can reduce the dimensionality of the measurements, using these algorithms:Uniform Manifold Approximation Projection (UMAP)t-distributed stochastic neighbor embedding (t-SNE)Principal Component Analysis (PCA)Non-linear dimensionality reduction through Isometric Mapping (Isomap)Multi-dimensional Scaling (MDS)To apply them to your data use the menuTools > Measurement post-processing > 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.
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 onRunand 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 labels layer and can be further processed by other plugins.Afterwards, you can again save and/or close the table.ClusteringIf 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 menuTools > Measurement post-processing > Clustering (ncp),
select the analysed labels layer.
Select the measurements for clustering, e.g. selectonlytheUMAPmeasurements.
Select the clustering methodKMeansand click onRun.
The table of measurements will reappear with an additional columnALGORITHM_NAME_CLUSTERING_IDcontaining the cluster
ID of each datapoint.Afterwards, you can save and/or close the table.Plotting clustering resultsReturn to the Plotter widget using the menuTools > Visualization > Plot measurement (ncp).
SelectUMAP_0andUMAP_1as X- and Y-axis and theALGORITHM_NAME_CLUSTERING_IDasClustering, and click onPlot.InstallationDevbio-napari installationThe easiest way to install this plugin is to install thedevbio-napariplugin collection. The napari-clusters-plotter is part of it.Minimal installationGet a python environment, e.g. viamini-conda.
If you never used mamba/conda environments before, please follow the instructionsin this blog postfirst.Create a new environment, for example, like this:mamba create --name ncp-env python=3.9Activate the new environment via conda:mamba activate ncp-envInstallnapari, e.g. viaconda:mamba install -c conda-forge napariAfterwards, you can installnapari-clusters-plotter, e.g. viaconda:mamba install -c conda-forge napari-clusters-plotterTroubleshooting installationError: Could not build wheels for hdbscan which use PEP 517 and cannot be installed directlyThis can happen if you used pip for the installation. To solve this error, install hdbscan via conda before installing the plugin:mamba install -c conda-forge hdbscanValueError: numpy.ndarray size changed, may indicate binary incompatibility. Expected 96 from C header, got 88 from PyObjectSimilar 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:mambainstall-cconda-forgenaparihdbscan
pipinstallnapari-clusters-plotterContributingContributions are very welcome. Tests can be run withpytest, please ensure
the coverage at least stays the same before you submit a pull request.LicenseDistributed under the terms of theBSD-3license,
"napari-clusters-plotter" is free and open source softwareAcknowledgementsThis project was supported by the Deutsche Forschungsgemeinschaft under Germany’s Excellence Strategy – EXC2068 - Cluster of Excellence "Physics of Life" of TU Dresden.
This project has been made possible in part by grant number2021-240341 (Napari plugin accelerator grant)from the Chan Zuckerberg Initiative DAF, an advised fund of the Silicon Valley Community Foundation.IssuesIf you encounter any problems, pleasefile an issuealong
with a detailed description.