Module: UntangleWorms

UntangleWorms has two modes:

• Train creates one training set per image group, using all of the worms in the training set as examples. It then writes the training file at the end of each image group.
• Untangle uses the training file to untangle images of worms.

Please see Help > Using CellProfiler > How Data Is Handled > Image Grouping for more details on the proper use of metadata for grouping

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

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.

• Choose With overlap to save objects including overlapping regions.
• Choose Without overlap to save only the portions of objects that do not overlap.
• Choose Both to save two versions: with and without overlap.

(Used only if untangling and overlap style is "Both" or "With overlap")
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.

(Used only if untangling and overlap style is "Both" or "Without overlap")
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.

(Used only if untangling)
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:

• Medium: 200 segments (takes up to several minutes to process)
• High: 600 segments (takes up to a quarter-hour to process)
• Very high: 1000 segments (can take hours to process)
• Custom: allows you to enter a custom number of segments.
• Process all clusters: Process all worms, regardless of complexity

(Used only if untangling and custom complexity) Enter the maximum number of segments of any cluster that should be processed.

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:

• Default Input Folder: Use the default input folder.
• Default Output Folder: Use from the default output folder.
• Elsewhere...: Use a particular folder you specify.
• Default input directory sub-folder: Enter the name of a subfolder of the default input folder or a path that starts from the default input folder.
• Default output directory sub-folder: Enter the name of a subfolder of the default output folder or a path that starts from the default output folder.

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):

• Use one period to represent the current directory. For example, if you choose Default Input Folder sub-folder, you can enter "./MyFiles" to look in a folder called "MyFiles" that is contained within the Default Input Folder.
• Use two periods ".." to move up one folder level. For example, if you choose Default Input Folder sub-folder, you can enter "../MyFolder" to look in a folder called "MyFolder" at the same level as the Default Input Folder.

An additional option is the following:

• URL: Use the path part of a URL. For instance, your training set might be hosted at http://university.edu/~johndoe/TrainingSet.xml To access this file, you would choose URL and enter https://svn.broadinstitute.org/CellProfiler/trunk/ExampleImages/ExampleSBSImages as the path location.

This is the name of the training set file.

Check this setting to use the overlap and leftover weights from the training set. Uncheck the setting to override these weights.

(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. Increase the overlap weight to make UntangleWorms avoid overlapping portions of worms. Decrease the overlap weight to make UntangleWorms ignore overlapping portions of worms.

(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. Increase the leftover weight to make UntangleWorms cover more foreground with worms. Decrease the overlap weight to make UntangleWorms ignore uncovered foreground.

(Used only if untangling and overlap style is "Both" or "With overlap")
Check this setting to save an image of the outlines of the objects with overlap. Leave the setting unchecked if you do not need the outline image.

(Used only if untangling and overlap style is "Both" or "With overlap" and retaining outlines)
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

(Used only if untangling and overlap style is "Both" or "With overlap")
This is the name of the outlines of the overlapped worms. You can use this image to display the untangling results, for instance, by composting the outlines image with the OverlayOutlines module

(Used only if untangling and overlap style is "Both" or "Without overlap")
Check this setting to save an image of the outlines of the non-overlapping worms. Leave it unchecked if you do not need the image of the outlines.

(Used only if untangling and overlap style is "Both" or "Without overlap")
This is the name of the of the outlines of the worms with the overlapping sections removed.

(Used only if training)
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.

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

(Used only if training)
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

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

(Used only if training)
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.

(Used only if training)
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

(Used only if training)
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

(Used only if training)
UntangleWorms uses this setting to compute the maximum length as described in Maximum length percentile above

(Used only if training)
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.

(Used only if training)
UntangleWorms uses this setting to compute the cost threshold as described in Maximum cost percentile above.

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

(Used only if training)
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.

(Used only if training)
UntangleWorms uses this setting to compute the maximum radius as described in Maximum radius percentile above.