Module: UntangleWorms

UntangleWorms untangles overlapping worms.
This module either assembles a training set of sample worms in order to create a worm model, or takes a binary image and the results of worm training and labels the worms in the image, untangling them and associating all of a worm's pieces together.

The results of untangling the input image will be an object set that can be used with downstream measurment modules. If using the overlapping style of objects, these can be saved as images using SaveImages to create a multi-page TIF file by specifying "Objects" as the type of image to save.

Available measurements

Object measurements (for "Untangle" mode only):

Technical notes

Training involves extracting morphological information from the sample objects provided from the previous steps. Using the default training set weights is recommended. Proper creation of the model is dependent on providing a binary image as input consisting of single, separated objects considered to be worms. You can the Identify modules to find the tentative objects and then filter these objects to get individual worms, whether by using FilterObjects, EditObjectsManually or the size criteria in IdentifyPrimaryObjects. A binary image can be obtained from an object set by using ConvertObjectsToImage.

At the end of the training run, a final display window is shown displaying the following statistical data:

Untangling involves untangles the worms using a provided worm model, built from a large number of samples of single worms. If the result of the untangling is not satisfactory (e.g., it is unable to detect long worms or is too stringent about shape variation) and you do not wish to re-train, you can adjust the provided worm model manually by opening the .xml file in a text editor and changing the values for the fields defining worm length, area etc. You may also want to adjust the "Maximum Complexity" module setting which controls how complex clusters the untangling will handle. Large clusters (> 6 worms) may be slow to process.

References

Settings:

Train or untangle worms?

UntangleWorms has two modes: Please see the Groups module for more details on the proper use of metadata for grouping

Select the input binary image

A binary image where the foreground indicates the worm shapes. The binary image can be produced by the ApplyThreshold module.

Overlap style

This setting determines which style objects are output. If two worms overlap, you have a choice of including the overlapping regions in both worms or excluding the overlapping regions from both worms.

Name the output overlapping worm objects

(Used only if "Untangle" mode and "Both" or "With overlap" overlap style are selected)
This setting names the objects representing the overlapping worms. When worms cross, they overlap and pixels are shared by both of the overlapping worms. The overlapping worm objects share these pixels and measurements of both overlapping worms will include these pixels in the measurements of both worms.

Name the output non-overlapping worm objects

(Used only if "Untangle" mode and "Both" or "With overlap" overlap style are selected)
This setting names the objects representing the worms, excluding those regions where the worms overlap. When worms cross, there are pixels that cannot be unambiguously assigned to one worm or the other. These pixels are excluded from both worms in the non-overlapping objects and will not be a part of the measurements of either worm.

Maximum complexity

(Used only if "Untangle" mode is selected)
This setting controls which clusters of worms are rejected as being too time-consuming to process. UntangleWorms judges complexity based on the number of segments in a cluster where a segment is the piece of a worm between crossing points or from the head or tail to the first or last crossing point. The choices are:

Custom complexity

(Used only if "Untangle" mode and "Custom" complexity are selected ) Enter the maximum number of segments of any cluster that should be processed.

Training set file location

Select the folder containing the training set to be loaded. You can choose among the following options which are common to all file input/output modules:

Elsewhere and the two sub-folder options all require you to enter an additional path name. You can use an absolute path (such as "C:\imagedir\image.tif" on a PC) or a relative path to specify the file location relative to a directory):

An additional option is the following:

Training set file name

This is the name of the training set file.

Use training set weights?

Select Yes to use the overlap and leftover weights from the training set.

Select No to override these weights with user-specified values.

Overlap weight

(Used only if not using training set weights)
This setting controls how much weight is given to overlaps between worms. UntangleWorms charges a penalty to a particular putative grouping of worms that overlap equal to the length of the overlapping region times the overlap weight.

Leftover weight

(Used only if not using training set weights)
This setting controls how much weight is given to areas not covered by worms. UntangleWorms charges a penalty to a particular putative grouping of worms that fail to cover all of the foreground of a binary image. The penalty is equal to the length of the uncovered region times the leftover weight.

Retain outlines of the overlapping objects?

(Used only if "Untangle" mode and "Both" or "With overlap" overlap style are selected)
Select Yes to retain the outlines of the new objects for later use in the pipeline. For example, a common use is for quality control purposes by overlaying them on your image of choice using the OverlayOutlines module and then saving the overlay image with the SaveImages module.

Outline colormap?

(Used only if "Untangle" mode, "Both" or "With overlap" overlap style and retaining outlines are selected )
This setting controls the colormap used when drawing outlines. The outlines are drawn in color to highlight the shapes of each worm in a group of overlapping worms

Name the overlapped outline image

(Used only if "Untangle" mode and "Both" or "With overlap" overlap style are selected)
This is the name of the outlines of the overlapped worms.

Retain outlines of the non-overlapping worms?

(Used only if "Untangle" mode and "Both" or "With overlap" overlap style are selected)
Select Yes to retain the outlines of the new objects for later use in the pipeline. For example, a common use is for quality control purposes by overlaying them on your image of choice using the OverlayOutlines module and then saving the overlay image with the SaveImages module.

Name the non-overlapped outlines image

(Used only if "Untangle" mode and "Both" or "With overlap" overlap style are selected)
This is the name of the of the outlines of the worms with the overlapping sections removed.

Minimum area percentile

(Used only if "Train" mode is selected)
UntangleWorms will discard single worms whose area is less than a certain minimum. It ranks all worms in the training set according to area and then picks the worm at this percentile. It then computes the minimum area allowed as this worm's area times the minimum area factor.

Minimum area factor

(Used only if "Train" mode is selected)
This setting is a multiplier that is applied to the area of the worm, selected as described in the documentation for Minimum area percentile.

Maximum area percentile

(Used only if "Train" mode is selected)
UntangleWorms uses a maximum area to distinguish between single worms and clumps of worms. Any blob whose area is less than the maximum area is considered to be a single worm whereas any blob whose area is greater is considered to be two or more worms. UntangleWorms orders all worms in the training set by area and picks the worm at the percentile given by this setting. It then multiplies this worm's area by the Maximum area factor (see below) to get the maximum area

Maximum area factor

(Used only if "Train" mode is selected)
The Maximum area factor setting is used to compute the maximum area as decribed above in Maximum area percentile.

Minimum length percentile

(Used only if "Train" mode is selected)
UntangleWorms uses the minimum length to restrict its search for worms in a clump to worms of at least the minimum length. UntangleWorms sorts all worms by length and picks the worm at the percentile indicated by this setting. It then multiplies the length of this worm by the Mininmum length factor (see below) to get the minimum length.

Minimum length factor

(Used only if "Train" mode is selected)
UntangleWorms uses the Minimum length factor to compute the minimum length from the training set as described in the documentation above for Minimum length percentile

Maximum length percentile

(Used only if "Train" mode is selected)
UntangleWorms uses the maximum length to restrict its search for worms in a clump to worms of at least the maximum length. It computes this length by sorting all of the training worms by length. It then selects the worm at the Maximum length percentile and multiplies that worm's length by the Maximum length factor to get the maximum length

Maximum length factor

(Used only if "Train" mode is selected)
UntangleWorms uses this setting to compute the maximum length as described in Maximum length percentile above

Maximum cost percentile

(Used only if "Train" mode is selected)
UntangleWorms computes a shape-based cost for each worm it considers. It will restrict the allowed cost to less than the cost threshold. During training, UntangleWorms computes the shape cost of every worm in the training set. It then orders them by cost and uses Maximum cost percentile to pick the worm at the given percentile. It them multiplies this worm's cost by the Maximum cost factor to compute the cost threshold.

Maximum cost factor

(Used only "Train" mode is selected)
UntangleWorms uses this setting to compute the cost threshold as described in Maximum cost percentile above.

Number of control points

(Used only if "Train" mode is selected)
This setting controls the number of control points that will be sampled when constructing a worm shape from its skeleton.

Maximum radius percentile

(Used only if "Train" mode is selected)
UntangleWorms uses the maximum worm radius during worm skeletonization. UntangleWorms sorts the radii of worms in increasing size and selects the worm at this percentile. It then multiplies this worm's radius by the Maximum radius factor (see below) to compute the maximum radius.

Maximum radius factor

(Used only if "Train" mode is selected)
UntangleWorms uses this setting to compute the maximum radius as described in Maximum radius percentile above.