How to guide: Clustering & Spatial Organization

How to guide: Clustering & Spatial Organization

Tool View

 

Purpose of the tool  

The Clustering & Spatial Organization Analysis App allows users to quantify how molecular clusters are spatially distributed relative to each other. The tool uses a K-nearest-neighbor (KNN) algorithm applied to cluster centroids generated during the clustering step to identify the nearest neighboring object (such as proteins). The tool outputs provide quantitative information about cluster spacing, local organization, and structural repetition within or between molecular populations, which reveals their spatial organization, how homogenously or heterogeneously distributed they are, and how far apart they are. 

In biology, this can be used to determine whether proteins are evenly distributed, clustered into nanoscale domains, polarized within a cellular compartment, or reorganized following a biological stimulus or treatment. For example, KNN can be used to quantify changes in membrane receptor clustering, characterize the spacing between nuclear pore complexes, or compare the spatial organization of protein assemblies between healthy and diseased cells. 

Overview   

The Clustering and Spatial-Organization analysis tool is based on the K-nearest-neighbor (KNN) algorithm [1-3], a spatial statistics method used to identify the nearest neighboring objects (such as proteins) based on the distance between object centroids.   

In CODI, objects are identified as localization-based clusters. The centroid position of each cluster is then used as the reference point for the KNN analysis. 

in KNN, the parameter K defines which neighboring cluster distance will be measured: 
  1. K = 1 measures the distance to the closest neighboring cluster. 
  2. K = 2 measures the distance from the first to the second closest neighboring cluster. 
  3. K = N measures the distance from the first to the Nth closest neighboring cluster.
The CODI implementation computes all nearest-neighbor distances from 1 up to the selected K value (5, by default) for every channel combination. The algorithm yields statistics based on the k-nearest neighbor results, such as the k-nearest distance from each cluster centroid and the mean nearest neighbor distance for a given k. 

When using this algorithm, it is important to bear the following points in mind regarding its suitability: 
  1. The algorithm only considers the distance between cluster centroids and does not account for any kind of area overlap. KNN treats each cluster as a single point located at its centroid, regardless of the cluster’s size, shape, or boundary. Two large clusters may physically overlap or touch at their edges, but if their centroids are far apart, KNN will report a large distance.
  2. The algorithm calculates the distance between cluster centroids and does not provide any information about the distribution of the localizations within a cluster itself.
  3. The algorithm may not be suitable for clusters with non-homogeneous shape or density or for cases where the centroid is highly variable and, thus, is not a good representation of the cluster’s position. The algorithm does not support alternative measures such as the nearest edge-to-edge distance between clusters. 

How KNN works 

The KNN analysis operates on clusters previously identified by the clustering tool, whereby each molecular cluster is converted into a coordinate.   

Examples:  
K = 1 measures the distance to the closest neighboring cluster.  
K = 2 measures the distance to the second closest neighboring cluster. 

The algorithm calculates the distance between the reference cluster centroid and all neighboring query cluster centroids. 

In the example above: 
  1. The shortest white arrow represents the first nearest neighbor distance (K=1)  
  2. The longer white arrow represents the second nearest neighbor distance (K=2)  
 
This calculation is repeated for every cluster in the dataset, generating a distribution of nearest-neighbor distances across the sample.


Running the tool  

The Clustering and Spatial Organization analysis app can be run via CODI on localization-based datasets. It contains all the steps required to cluster localizations and perform the KNN analysis in a step-by-step workflow. Specifically:  
  1. Drift correction  
  2. Localization filtering  
  3. Temporal Grouping 
  4. Annotation 
  5. Clustering 
  6. K-nearest-neighbor (KNN)  
All these steps are explained in detail in the general “How to Guides” section within the ONI Service Desk.   
Once clusters are defined, the KNN step can be run by setting up the parameter K and then clicking on the “play” icon. The parameter K defines which neighboring cluster distance will be measured. 
The default value in CODI is ”K up to = 5”, meaning CODI computes all distances from the first to the fifth nearest neighbor. The K value can be modified by accessing the back of the widget panel by clicking on the 3 dots on the top right of the widget. 

This can be applied between clusters from the same channel, or between clusters from different channels. To know more about the tool, please refer to the “Understanding the KNN CSV Outputs" section.  
 

Example 1 - KNN applied on beads datasets   

In the image below, Tetraspeck beads were acquired on an ONI Nanoimager using the 638 nm laser (Channel 1) and 561 nm laser (channel 0). During the acquisition, the stage was shifted by around 50 nm along the y-axis and 40 nm along the x-axis to create a series of grid patterns within a Field of View (FOV). The two channels were mapped with an intentional 20 nm displacement such that they would appear not colocalized. The resulting image on CODI was a grid made of paired magenta (channel 1) and cyan (channel 0) localization clusters.  

 

When running KNN between the magenta and cyan clusters, we expect to find for k = 1 a cluster distance of around 20 nm. Given the grid pattern, we also expect a distance between 40 to 50 nm range for k = 1, when comparing beads from the same channel. 
 
The tool computes all distances from each cluster centroid to its Kth nearest neighboring cluster centroid for each channel combination. 
 
Users can select the desired channel combination and visualize the corresponding histogram directly in the CODI UI, for example: 
  1. Channel 0 → Channel 0 
  2. Channel 0 → Channel 1 
 
The histogram represents the distribution of K-nearest-neighbor distances across all detected clusters.  
 
X-axis: Represents nearest-neighbor distance in nanometers (nm)  
Y-axis: Represents number of clusters detected at a given distance 
 
Individual k-value histograms can be shown/hidden by clicking on the corresponding line in the legend. This helps visualize differences in specific nearest neighbor populations. 
 
By hovering the mouse cursor over each of the K values, a summary of parameters, such as mean, median, and standard deviation, will be shown in the CODI UI. 
 
The mean and median nearest-neighbor distances indicate the typical spatial separation between Channel 0 clusters and Channel 1 clusters.  In this example: 
  1. Most Channel 0 clusters have their 1st nearest Channel 1 neighbor located around 17 nm away, which is in alignment with the expected 20 nm. 
  2. Most Channel 0 clusters have their 1st nearest Channel 0 neighbor located around 48 nm away, which is in alignment with the expected 50 nm. 
The standard deviation (SD) measures how variable the spatial organization is across the dataset. The narrow distribution and low SD of 9 nm suggest that the spatial organization is relatively consistent across the sample. 
 
The multiple peaks may indicate repeated spatial scales, periodic structures, or hierarchical organizations. 

 

If the analysis is run on a Region of Interest (ROI) with a single beads grid, then the SD for k=1 drops as the average distance between channel 0 and channel 1 is more consistent. 

Example 2 - KNN applied to DNA-PAINT nanorulers   


To demonstrate how KNN can be used to characterize nanoscale structures, the tool was applied to GATTA-PAINT HiRes 20Y nanorulers from GATTAquant. These DNA origami structures contain three Cy3B imager strand docking sites arranged with an expected spacing of approximately 20 nm between adjacent sites.

Since all clusters belong to the same molecular population, the analysis was performed using the same channel as both the reference and query population (561 → 561). 

The narrow histogram distribution and low standard deviation indicate that the spacing between neighboring docking sites is highly consistent across the dataset. The measured distances closely match the expected nanoruler geometry, demonstrating that KNN can accurately recover known nanoscale distances and assess the structural uniformity of repeated molecular assemblies. 

In this example, k = 1 corresponds to the distance between adjacent docking sites within a nanoruler and yields a median distance of approximately 19 nm and SD of 3 nm, in agreement with the expected 20 nm separation. k = 2 measures the distance to the second nearest neighboring site and therefore captures the separation between the two outer docking sites of the nanoruler, resulting in a distance of approximately 38–40 nm. As the K value increases further, the analysis progressively probes larger spatial scales. Consequently, k = 3 and higher-order neighbors begin to capture distances between neighboring nanorulers rather than distances between docking sites within the same nanoruler (see table below). 

K Value 
Mean Distance (nm) 
Median Distance (nm) 
SD (nm) 
K = 1 
19 
19 
2 
K = 2 
33 
38 
8 
K = 3 
291 
265 
45 
K = 4 
306 
281 
45 

This demonstrates how KNN can be used to investigate both the internal organization of nanoscale structures and the spatial distribution of those structures across the sample. 

Understanding the KNN CSV Outputs 

After a K-nearest-neighbor (KNN) analysis is completed in CODI for a single dataset, two CSV files are generated by clicking the Download CSVs button. These files contain both the per-cluster nearest-neighbor measurements, and the global statistical summaries used to generate the histograms displayed in the CODI UI. The CSV outputs provide a quantitative description of the spatial organization between molecular clusters across all analyzed channel combinations and K values. 

Single Dataset Analysis 

For a single dataset, CODI generates two CSV files: 
  1. cluster_spatial_organization_results.csv contains the individual nearest-neighbor measurements for every detected cluster. Each row corresponds to one cluster ID and includes cluster properties such as centroid coordinates, localization counts, area, density, and other morphological descriptors, together with the nearest-neighbor distances calculated for each channel combination and K value. The analysis is directional.
    Therefore: Channel 0 → Channel 1 or Channel 1 → Channel 0 will likely generate different outputs depending on the density and spatial organization of the two molecular populations. The results.csv file provides the complete nearest-neighbor distance distribution at the individual cluster level and can be used for downstream statistical analysis and plotting.  
  2. cluster_spatial_organization_summary.csv contains the statistical summary of the KNN analysis. For each channel combination and K value, the file reports the minimum, median, mean, standard deviation, and maximum nearest-neighbor distance. These values correspond to the summary statistics displayed in the CODI user interface and provide a rapid overview of the spatial organization within the dataset. 

Batch Analysis 

When KNN is executed through the CODI Batch Analysis workflow, three CSV files are generated. 
  1. cluster_spatial_organization_results_batch.csv contains equivalent content to the results.csv but for all datasets analyzed in batch
  2. cluster_spatial_organization_summary_batch.csv contains equivalent content to the summary.csv but for all datasets analyzed in batch. 
  3. clusters_batch.csv contains the cluster properties generated during the clustering step for every dataset processed in the batch. This file includes morphological measurements such as localization count, area, density, circularity, radius, and centroid coordinates, and can be used to investigate whether differences in spatial organization are associated with changes in cluster morphology. 

References 

[1] Pedregosa et al. (2011) 
Scikit-learn: Machine Learning in Python 
Journal of Machine Learning Research. 
 
[2] Cover, T. and Hart, P. (1967) 
Nearest Neighbor Pattern Classification 
IEEE Transactions on Information Theory. 
 
[3] Fix, E., & Hodges, J. L. (1951). 
Discriminatory Analysis, Nonparametric Discrimination: Consistency Properties. 
USAF School of Aviation Medicine Technical Report. 
 

    • Related Articles

    • How to guide: Clustering & Co-Organization

      Purpose of the tool The Clustering and Co-Organization analysis tool aims to give insights into the spatial organization of diverse molecular distributions in a quantitative and automatic manner. Overview The Clustering and Co-Organization analysis ...

    • How to guide: Clustering tool

      Tool view Purpose of tool The tool performs clustering on localisation data to find biological structures and quantify their statistical and morphological properties. The default clustering method is HDBSCAN. The cluster results can then be ...

    • Release Note: CODI & CODI System App

      July 2026 Update with CSA 1.3.14 July 8, 2026 This update introduces 2 new CODI analysis apps for understanding clusters spatial organization, addresses general instrument reliability issues, and introduces significant improvement to the autofocus ...

    • How to guide: Counting tool

      Tool view Purpose of tool Counts the number of localisations or ‘bins’ by channel around a set of centre points - currently the centroids of a clustering result. Contents Inputs Results Outputs Inputs The centre points for counting come from a loaded ...

    • August 2023 Clustering User Interface Improvement

      While optimizing CODI during its beta phase, we noticed some inconsistencies in the clustering widget when using the DBSCAN* algorithm, whereby the CODI user interface misrepresents information pertaining to number of clusters and localizations. Data ...