Calculate nearest neighbour

Measures the shortest distance between all objects in the specified input collection and all other objects in the same, or a different collection.

Description

Measures the shortest distance between all objects in the specified input collection and all other objects in the same, or a different collection. The shortest distance (nearest neighbour distance) is recorded as a measurement associated with the input object. Optionally, the distances between all objects can be calculated and exported as a standalone spreadsheet.

Parameters

Parameter	Description
Save location	Select where the image should be saved. "Mirrored directory" Save the image to a new directory structure which has the same layout as the input. This is useful when batch processing from a multi-layer folder structure. The subdirectory layout will match that of the input structure, but will have its root at the folder specified in "Mirrored directory root". "Match Output Control" Save the image to the folder specified by the "Save location" parameter in "Output control". "Save with input file" Save the image in the same file as the root file for this workspace (i.e. the image specified in "Input control". "Specific location" Save the image to a specific folder.
Mirrored directory root	The root path for the mirrored directory structure. This path is the equivalent of the folder specified in "Input control". All subfolders will be in the same relative locations to their input counterparts.
File path	Path to folder where images will be saved.
File name (generic)
Save name mode	Controls how saved image names will be generated. "Match input file name" Use the same name as the root file for this workspace (i.e. the input file in "Input control". "Specific name" Use a specific name for the output file. Care should be taken with this when working in batch mode as it's easy to continuously write over output images.
File name	Filename for saved image. Care should be taken with this when working in batch mode as it's easy to continuously write over output images.
Append series mode	Controls if any series information should be appended to the end of the filename. This is useful when working with multi-series files, as it should help prevent writing files from multiple runs with the same filename. Series numbers are prepended by "S". Choices are: None, Series name, Series number.
Append date/time mode	Controls under what conditions the time and date will be appended on to the end of the image filename. This can be used to prevent accidental over-writing of images from previous runs: "Always" Always append the time and date on to the end of the filename. "If file exists" Only append the time and date if the results file already exists. "Never" Never append time and date (unless the file is open and unwritable).
Add filename suffix	A custom suffix to be added to each filename.
Input objects	Objects for which the distance to a closest neighbour will be calculated. The closest distance will be stored as a measurement associated with this object.
Relationship mode	Controls whether the nearest neighbour distance from each input object will be calculated relative to all other objects in that input collection ("Within same object set") or to all objects in another object collection ("Different object set").
Neighbour objects	If "Relationship mode" is set to "Different object set", the distance from the input objects to these objects will be calculated and the shortest distance recorded.
Reference mode	Controls the method used for determining the nearest neighbour distances: "Centroid (2D)" Distances are between the input and neighbour object centroids, but only in the XY plane. These distances are always positive; increasing as the distance between centroids increases. "Centroid (3D)" Distances are between the input and neighbour object centroids. These distances are always positive; increasing as the distance between centroids increases. "Surface (2D)" Distances are between the closest points on the input and neighbour surfaces, but only in the XY plane. These distances increase in magnitude the greater the minimum input-neighbour object surface distance is; however, they are assigned a positive value if the closest input object surface point is outside the neighbour and a negative value if the closest input object surface point is inside the neighbour. For example, a closest input object surface point 5px outside the neighbour will be simply "5px", whereas a closest input object surface point 5px from the surface, but contained within the neighbour object will be recorded as "-5px". Note: Any instances where the input and neighbour object surfaces overlap will be recorded as "0px" distance. "Surface (3D)" Distances are between the closest points on the input and neighbour surfaces. These distances increase in magnitude the greater the minimum input-neighbour object surface distance is; however, they are assigned a positive value if the closest input object surface point is outside the neighbour and a negative value if the closest input object surface point is inside the neighbour. For example, a closest input object surface point 5px outside the neighbour will be simply "5px", whereas a closest input object surface point 5px from the surface, but contained within the neighbour object will be recorded as "-5px". Note: Any instances where the input and neighbour object surfaces overlap will be recorded as "0px" distance.
Only calculate for objects in same parent	When selected, only distances between objects within the same parent (specified by "Parent objects") will be considered.
Parent objects	When "Only calculate for objects in same parent" is selected, objects must have this same parent to have their nearest neighbour distances calculated.
Limit linking distance	When selected, nearest neighbour distances will only be calculated if that distance (as calculated by the "Reference mode" metric) is less than or equal to the distance defined by "Maximum linking distance".
Maximum linking distance	If "Limit linking distance" is selected, this is the maximum permitted distance between objects for them to have their nearest neighbour distance recorded.
Calibrated distance	When selected, linking distances are to be specified in calibrated units; otherwise, units are specified in pixels.
Only link objects in same frame	When selected, objects must be in the same time frame for them to be linked.
Export all distances	For each analysis run, create a separate spreadsheet file, which records the distance of all objects to all other objects.
Inside/outside mode	When relating objects by surfaces it's possible to only consider objects inside, outside or on the edge of the neighbouring object. This parameter controls which objects are allowed to be related to a neighbour. Choices are: Inside and outside (all distances), Inside only (distances < 0), Inside and on surface (distances <= 0), On surface only (distances = 0), Outside and on surface (distances >= 0), Outside only (distances > 0).
Include timepoints	Include a column recording the timepoint that the objects were present in. If only linking objects in the same frame, there will be a single timepoint column; however, if links are permitted between objects in different timepoints, a timepoint colummn for each of the related objects will be included.
Include input object parent	Include a column recording the ID number of a specific parent of the input object. For example, this could be a track ID number.
Input object parent	Parent object collection of the input object. If "Include input object parent" is selected, the corresponding parent ID number will be included as a column in the output distances spreadsheet.
Include neighbour object parent	Include a column recording the ID number of a specific parent of the neighbour object. For example, this could be a track ID number.
Neighbour object parent	Parent object collection of the neighbour object. If "Include neighbour object parent" is selected, the corresponding parent ID number will be included as a column in the output distances spreadsheet.