Module: IdentifyPrimaryObjects

Identify Primary Objects identifies biological components of interest in grayscale images containing bright objects on a dark background.

What is a primary object?

In CellProfiler, we use the term object as a generic term to refer to an identifed feature in an image, usually a cellular subcompartment of some kind (for example, nuclei, cells, colonies, worms). We define an object as primary when it can be found in an image without needing the assistance of another cellular feature as a reference. For example:

What do I need as input?

To use this module, you will need to make sure that your input image has the following qualities: If this is not the case, other modules can be used to pre-process the images to ensure they are in the proper form:

If you have images in which the foreground and background cannot be distinguished by intensity alone (e.g, brightfield or DIC images), you can use the ilastik package bundled with CellProfiler to perform pixel-based classification (Windows only). You first train a classifier by identifying areas of images that fall into one of several classes, such as cell body, nucleus, background, etc. Then, the ClassifyPixels module takes the classifier and applies it to each image to identify areas that correspond to the trained classes. The result of ClassifyPixels is an image in which the region that falls into the class of interest is light on a dark background. Since this new image satisfies the constraints above, it can be used as input in IdentifyPrimaryObjects. See the ClassifyPixels module for more information.

What do the settings mean?

See below for help on the individual settings. The following icons are used to call attention to key items:

What do I get as output?

A set of primary objects are produced by this module, which can be used in downstream modules for measurement purposes or other operations. See the section "Available measurements" below for the measurements that are produced by this module.

Once the module has finished processing, the module display window will show the following panels:

Available measurements

Image measurements:

Object measurements:

Technical notes

CellProfiler contains a modular three-step strategy to identify objects even if they touch each other. It is based on previously published algorithms (Malpica et al., 1997; Meyer and Beucher, 1990; Ortiz de Solorzano et al., 1999; Wahlby, 2003; Wahlby et al., 2004). Choosing different options for each of these three steps allows CellProfiler to flexibly analyze a variety of different types of objects. The module has many options, which vary in terms of speed and sophistication. More detail can be found in the Settings section below. Here are the three steps, using an example where nuclei are the primary objects:

  1. CellProfiler determines whether a foreground region is an individual nucleus or two or more clumped nuclei.
  2. The edges of nuclei are identified, using thresholding if the object is a single, isolated nucleus, and using more advanced options if the object is actually two or more nuclei that touch each other.
  3. Some identified objects are discarded or merged together if they fail to meet certain your specified criteria. For example, partial objects at the border of the image can be discarded, and small objects can be discarded or merged with nearby larger ones. A separate module, FilterObjects, can further refine the identified nuclei, if desired, by excluding objects that are a particular size, shape, intensity, or texture.

References

See also IdentifySecondaryObjects, IdentifyTertiaryObjects, IdentifyObjectsManually and ClassifyPixels

Settings:

Select the input image

Select the image that you want to use to identify objects.

Name the primary objects to be identified

Enter the name that you want to call the objects identified by this module.

Typical diameter of objects, in pixel units (Min,Max)

This setting allows the user to make a distinction on the basis of size, which can be used in conjunction with the Discard objects outside the diameter range? setting below to remove objects that fail this criteria.
  The units used here are pixels so that it is easy to zoom in on objects and determine typical diameters. To measure distances in an open image, use the "Measure length" tool under Tools in the display window menu bar. If you click on an image and drag, a line will appear between the two endpoints, and the distance between them shown at the right-most portion of the bottom panel.

A few important notes:

Discard objects outside the diameter range?

Select Yes to discard objects outside the range you specified in the Typical diameter of objects, in pixel units (Min,Max) setting. Select No to ignore this criterion.

Objects discarded based on size are outlined in magenta in the module's display. See also the FilterObjects module to further discard objects based on some other measurement.

  Select Yes allows you to exclude small objects (e.g., dust, noise, and debris) or large objects (e.g., large clumps) if desired.

Try to merge too small objects with nearby larger objects?

Select Yes to cause objects that are smaller than the specified minimum diameter to be merged, if possible, with other surrounding objects.

This is helpful in cases when an object was incorrectly split into two objects, one of which is actually just a tiny piece of the larger object. However, this could be problematic if the other settings in the module are set poorly, producing many tiny objects; the module will take a very long time trying to merge the tiny objects back together again; you may not notice that this is the case, since it may successfully piece together the objects again. It is therefore a good idea to run the module first without merging objects to make sure the settings are reasonably effective.

Discard objects touching the border of the image?

Select Yes to discard objects that touch the border of the image. Select No to ignore this criterion.
  Removing objects that touch the image border is useful when you do not want to make downstream measurements of objects that are not fully within the field of view. For example, morphological measurements obtained from a portion of an object would not be accurate.

Objects discarded due to border touching are outlined in yellow in the module's display. Note that if a per-object thresholding method is used or if the image has been previously cropped or masked, objects that touch the border of the cropped or masked region may also discarded.

Threshold strategy

The thresholding strategy determines the type of input that is used to calculate the threshold. The image thresholds can be based on: These options allow you to calculate a threshold based on the whole image or based on image sub-regions such as user-defined masks or objects supplied by a prior module.
The choices for the threshold strategy are:

Thresholding method

The intensity threshold affects the decision of whether each pixel will be considered foreground (region(s) of interest) or background. A higher threshold value will result in only the brightest regions being identified, whereas a lower threshold value will include dim regions. You can have the threshold automatically calculated from a choice of several methods, or you can enter a number manually between 0 and 1 for the threshold.

Both the automatic and manual options have advantages and disadvantages.

  An automatically-calculated threshold adapts to changes in lighting/staining conditions between images and is usually more robust/accurate. In the vast majority of cases, an automatic method is sufficient to achieve the desired thresholding, once the proper method is selected.
In contrast, an advantage of a manually-entered number is that it treats every image identically, so use this option when you have a good sense for what the threshold should be across all images. To help determine the choice of threshold manually, you can inspect the pixel intensities in an image of your choice. To view pixel intensities in an open image, use the pixel intensity tool which is available in any open display window. When you move your mouse over the image, the pixel intensities will appear in the bottom bar of the display window..
  The manual method is not robust with regard to slight changes in lighting/staining conditions between images.
The automatic methods may ocasionally produce a poor threshold for unusual or artifactual images. It also takes a small amount of time to calculate, which can add to processing time for analysis runs on a large number of images.

The threshold that is used for each image is recorded as a per-image measurement, so if you are surprised by unusual measurements from one of your images, you might check whether the automatically calculated threshold was unusually high or low compared to the other images. See the FlagImage module if you would like to flag an image based on the threshold value.

There are a number of methods for finding thresholds automatically:

References

Select binary image

(Used only if Binary image selected for thresholding method)
Select the binary image to be used for thresholding.

Manual threshold

(Used only if Manual selected for thresholding method)
Enter the value that will act as an absolute threshold for the images, a value from 0 to 1.

Select the measurement to threshold with

(Used only if Measurement is selected for thresholding method)
Choose the image measurement that will act as an absolute threshold for the images.

Two-class or three-class thresholding?

(Used only for the Otsu thresholding method)
Note that whether two- or three-class thresholding is chosen, the image pixels are always finally assigned two classes: foreground and background.
  Three-class thresholding may be useful for images in which you have nuclear staining along with low-intensity non-specific cell staining. Where two-class thresholding might incorrectly assign this intermediate staining to the nuclei objects for some cells, three-class thresholding allows you to assign it to the foreground or background as desired.
  However, in extreme cases where either there are almost no objects or the entire field of view is covered with objects, three-class thresholding may perform worse than two-class.

Assign pixels in the middle intensity class to the foreground or the background?

(Used only for three-class thresholding)
Choose whether you want the pixels with middle grayscale intensities to be assigned to the foreground class or the background class.

Approximate fraction of image covered by objects?

(Used only when applying the MoG thresholding method)
Enter an estimate of how much of the image is covered with objects, which is used to estimate the distribution of pixel intensities.

Method to calculate adaptive window size

(Used only if an adaptive thresholding method is used)
The adaptive method breaks the image into blocks, computing the threshold for each block. There are two ways to compute the block size:

Size of adaptive window

(Used only if an adaptive thresholding method with a Custom window size are selected)
Enter the window for the adaptive method. For example, you may want to use a multiple of the largest expected object size.

Threshold correction factor

This setting allows you to adjust the threshold as calculated by the above method. The value entered here adjusts the threshold either upwards or downwards, by multiplying it by this value. A value of 1 means no adjustment, 0 to 1 makes the threshold more lenient and > 1 makes the threshold more stringent.
  When the threshold is calculated automatically, you may find that the value is consistently too stringent or too lenient across all images. This setting is helpful for adjusting the threshold to a value that you empirically determine is more suitable. For example, the Otsu automatic thresholding inherently assumes that 50% of the image is covered by objects. If a larger percentage of the image is covered, the Otsu method will give a slightly biased threshold that may have to be corrected using this setting.

Lower and upper bounds on threshold

Enter the minimum and maximum allowable threshold, a value from 0 to 1. This is helpful as a safety precaution when the threshold is calculated automatically, by overriding the automatic threshold.
  For example, if there are no objects in the field of view, the automatic threshold might be calculated as unreasonably low; the algorithm will still attempt to divide the foreground from background (even though there is no foreground), and you may end up with spurious false positive foreground regions. In such cases, you can estimate the background pixel intensity and set the lower bound according to this empirically-determined value.
To view pixel intensities in an open image, use the pixel intensity tool which is available in any open display window. When you move your mouse over the image, the pixel intensities will appear in the bottom bar of the display window.

Select the smoothing method for thresholding

(Only used for strategies other than Automatic and Binary image)
The input image can be optionally smoothed before being thresholded. Smoothing can improve the uniformity of the resulting objects, by removing holes and jagged edges caused by noise in the acquired image. Smoothing is most likely not appropriate if the input image is binary, if it has already been smoothed or if it is an output of the ClassifyPixels module.
The choices are:

Threshold smoothing scale

(Only used if smoothing for threshold is Manual)
This setting controls the scale used to smooth the input image before the threshold is applied. The scale should be approximately the size of the artifacts to be eliminated by smoothing. A Gaussian is used with a sigma adjusted so that 1/2 of the Gaussian's distribution falls within the diameter given by the scale (sigma = scale / 0.674)

Automatically calculate the size of objects for the Laplacian of Gaussian filter?

(Used only when applying the LoG thresholding method)

Select Yes to use the filtering diameter range above when constructing the LoG filter.

Select No in order to manually specify the size. You may want to specify a custom size if you want to filter using loose criteria, but have objects that are generally of similar sizes.

Enter LoG filter diameter

(Used only when applying the LoG thresholding method)
The size to use when calculating the LoG filter. The filter enhances the local maxima of objects whose diameters are roughly the entered number or smaller.

Method to distinguish clumped objects

This setting allows you to choose the method that is used to segment objects, i.e., "declump" a large, merged object into individual objects of interest. To decide between these methods, you can run Test mode to see the results of each.

Method to draw dividing lines between clumped objects

This setting allows you to choose the method that is used to draw the line bewteen segmented objects, provided that you have chosen to declump the objects. To decide between these methods, you can run Test mode to see the results of each.

Automatically calculate size of smoothing filter for declumping?

(Used only when distinguishing between clumped objects)
Select Yes to automatically calculate the amount of smoothing applied to the image to assist in declumping. Select No to manually enter the smoothing filter size.

This setting, along with the Minimum allowed distance between local maxima setting, affects whether objects close to each other are considered a single object or multiple objects. It does not affect the dividing lines between an object and the background.

Please note that this smoothing setting is applied after thresholding, and is therefore distinct from the threshold smoothing method setting above, which is applied before thresholding.

The size of the smoothing filter is automatically calculated based on the Typical diameter of objects, in pixel units (Min,Max) setting above. If you see too many objects merged that ought to be separate or too many objects split up that ought to be merged, you may want to override the automatically calculated value.

Size of smoothing filter

(Used only when distinguishing between clumped objects)
If you see too many objects merged that ought to be separated (under-segmentation), this value should be lower. If you see too many objects split up that ought to be merged (over-segmentation), the value should be higher. Enter 0 to prevent any image smoothing in certain cases; for example, for low resolution images with small objects ( < ~5 pixels in diameter).

Reducing the texture of objects by increasing the smoothing increases the chance that each real, distinct object has only one peak of intensity but also increases the chance that two distinct objects will be recognized as only one object. Note that increasing the size of the smoothing filter increases the processing time exponentially.

Automatically calculate minimum allowed distance between local maxima?

(Used only when distinguishing between clumped objects)
Select Yes to automatically calculate the distance between intensity maxima to assist in declumping. Select No to manually enter the permissible maxima distance.

This setting, along with the Size of smoothing filter setting, affects whether objects close to each other are considered a single object or multiple objects. It does not affect the dividing lines between an object and the background. Local maxima that are closer together than the minimum allowed distance will be suppressed (the local intensity histogram is smoothed to remove the peaks within that distance). The distance can be automatically calculated based on the minimum entered for the Typical diameter of objects, in pixel units (Min,Max) setting above, but if you see too many objects merged that ought to be separate, or too many objects split up that ought to be merged, you may want to override the automatically calculated value.

Suppress local maxima that are closer than this minimum allowed distance

(Used only when distinguishing between clumped objects)
Enter a positive integer, in pixel units. If you see too many objects merged that ought to be separated (under-segmentation), the value should be lower. If you see too many objects split up that ought to be merged (over-segmentation), the value should be higher.

The maxima suppression distance should be set to be roughly equivalent to the minimum radius of a real object of interest. Any distinct "objects" which are found but are within two times this distance from each other will be assumed to be actually two lumpy parts of the same object, and they will be merged.

Speed up by using lower-resolution image to find local maxima?

(Used only when distinguishing between clumped objects)
Select Yes to down-sample the image for declumping. This can be helpful for saving processing time on large images.

Note that if you have entered a minimum object diameter of 10 or less, checking this box will have no effect.

Retain outlines of the identified objects?

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 outline image

(Used only if the outline image is to be retained for later use in the pipeline)
Enter a name for the outlines of the identified objects. The outlined image can be selected in downstream modules by selecting them from any drop-down image list.

Fill holes in identified objects?

Select After both thresholding and declumping to fill in background holes that are smaller than the maximum object size prior to declumping and to fill in any holes after declumping. Select After declumping only to fill in background holes located within identified objects after declumping. Select Never to leave holes within objects.

Please note that if a foreground object is located within a hole and this option is enabled, the object will be lost when the hole is filled in.

Handling of objects if excessive number of objects identified

This setting deals with images that are segmented into an unreasonable number of objects. This might happen if the module calculates a low threshold or if the image has unusual artifacts. IdentifyPrimaryObjects can handle this condition in one of three ways:
  • Continue: Don't check for large numbers of objects.
  • Truncate: Limit the number of objects. Arbitrarily erase objects to limit the number to the maximum allowed.
  • Erase: Erase all objects if the number of objects exceeds the maximum. This results in an image with no primary objects. This option is a good choice if a large number of objects indicates that the image should not be processed.

Maximum number of objects

(Used only when handling images with large numbers of objects by truncating)
This setting limits the number of objects in the image. See the documentation for the previous setting for details.