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):
- Length: The length of the worm skeleton.
- Angle: The angle at each of the control points
- ControlPointX_N, ControlPointY_N: The X,Y coordinate of a control point N. A control point is a sampled location along the worm shape used to construct the model.
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:
- A boxplot of the direction angle shape costs. The direction angles (which are between -π and π) are the angles between lines joining consective control points. The angle 0 corresponds to the case when two adjacent line segments are parallel (and thus belong to the same line).
- A cumulative boxplot of the worm lengths as determined by the model.
- A cumulative boxplot of the worm angles as determined by the model.
- A heatmap of the covariance matrix of the feature vectors. For N control points, the feature vector is of length N-1 and contains N-2 elements for each of the angles between them, plus an element representing the worm length.
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
- Wählby C, Kamentsky L, Liu ZH, Riklin-Raviv T, Conery AL, O'Rourke EJ, Sokolnicki KL, Visvikis O, Ljosa V, Irazoqui JE, Golland P, Ruvkun G, Ausubel FM, Carpenter AE (2012). "An image analysis toolbox for high-throughput C. elegans assays." Nature Methods 9(7): 714-716. (link)
Settings:
Train or untangle worms?
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 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.
- 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.
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:
- 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
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:
- 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://my_institution.edu/server/my_username/TrainingSet.xml
To access this file, you would choose URL and enter
http://my_institution.edu/server/my_username/
as the path location.
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.
- Increase
the overlap weight to make UntangleWorms avoid overlapping
portions of worms.
- Decrease the overlap weight to make
UntangleWorms ignore overlapping portions of worms.
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.
- Increase the leftover weight to make UntangleWorms
cover more foreground with worms.
- Decrease the overlap weight to make UntangleWorms
ignore uncovered foreground.
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.