Module: Images

The Images module specifies the location of image files to be analyzed by your pipeline.
The Images module allows you to specify the location of files to be analyzed by the pipeline; setting this module correctly is the first step in creating a new project in CellProfiler. These files can be located on your hard drive, on a networked computer elsewhere, or accessible with a URL. You can also provide rules to specify only those files that you want analyzed out of a larger collection (for example, from a folder containing both images for analysis and non-image files that should be disregarded).

What is a "digital image"?

A digital image is a set of numbers arranged into a two-dimensional format of rows and columns; a pixel refers to the row/column location of a particular point in the image. Pixels in grayscale or monochrome (black/white) images contain a single intensity value, whereas in color images, each pixel contains a red, green, and blue (RGB) triplet of intensity values. Additionally, the term image can be used as short-hand for an image sequence, that is, an image collection such as a time-lapse series (2-D + t), confocal Z-stacks (3-D), etc.

CellProfiler can read a wide variety of image formats by using a library called Bio-Formats; see here for the formats available. Some image formats are better than others for use in image analysis. Some are "lossy" (information is lost in the conversion to the format) like most JPG/JPEG files; others are "lossless" (no image information is lost). For image analysis purposes, a lossless format like TIF or PNG is recommended.

What do I need as input?

The most straightforward way to provide image files to the Images module is to simply drag-and-drop them on the file list panel (the blank space indicated by the text "Drop files and folders here").

Using the file explorer tool of your choice (e.g., Explorer in Windows, Finder in Mac), you can drag-and-drop individual files and/or entire folders into this panel. You can also right-click in the File list panel to bring up a file selection window to browse for individual files; on the Mac, folders can be drag-and-dropped from this window and you can select multiple files using Ctrl-A (Windows) or Cmd-A (Mac).
Right-clicking on the file list panel will provide a context menu with options to modify the file list:

What do the settings mean?

If you have a subset of files that you want to analyze from the full listing shown in the panel, you can filter the files according to a set of rules. This is useful in cases such as: You may specify as many rules as necessary to define the desired list of images.

After you have filtered the file list, press the "Apply" button to update the view of the file list. You can also toggle the "Show file excluded by filters" box to modify the display of the files:

What do I get as output?

The final product of the Images module is a file list in which any files that are not intended for further processing have been removed, whether manually or using filtering. This list will be used when collecting metadata (if desired) and when assembling the image sets in NamesAndTypes. The list can be filtered further in NamesAndTypes to specify, for example, that a subset of these images represents a particular wavelength.


Filter images?

The Images module will pass all the files specified in the file list panel downstream to have a meaningful name assigned to it (so other modules can access it) or optionally, to define the relationships between images and associated metadata. Enabling file filtering will allow you to specify a subset of the files from the file list panel by defining rules to filter the files. This approach is useful if, for example, you drag-and-dropped a folder onto the file list panel which contains a mixture of images that you want to analyze and other files that you want to ignore.

Several options are available for this setting:

Select the rule criteria

Specify a set of rules to narrow down the files to be analyzed.

Clicking the rule menus shows you all the file attributes, operators and conditions you can specify to narrow down the image list.

  1. For each rule, first select the attribute that the rule is to be based on. For example, you can select "File" to define a rule that will filter files on the basis of their filename.
  2. The operator drop-down is then updated with operators applicable to the attribute you selected. For example, if you select "File" as the attribute, the operator menu includes text operators such as Contain or Starts with. On the other hand, if you select "Extension" as the attribute, you can choose the logical operators "Is" or "Is not" from the menu.
  3. In the operator drop-down menu, select the operator you want to use. For example, if you want to match data exactly, you may want the "Exactly match" or the "Is" operator. If you want the condition to be more loose, select an operator such as "Contains".
  4. Use the condition box to type the condition you want to match. The more you type, the more specific the condition is.
    • As an example, if you create a new filter and select File as the attribute, then select "Does" and "Contain" as the operators, and type "Channel" as the condition, the filter finds all files that include the text "Channel", such as "Channel1.tif" "Channel2.jpg", "1-Channel-A01.BMP" and so on.
    • If you select "Does" and "Start with" as the operators and "Channel1" in the Condition box, the rule will includes such files as "Channel1.tif" "Channel1-A01.png", and so on.
  5. You can also create regular expressions (an advanced syntax for pattern matching; see below) in order to select particular files.

To add another rule, click the plus buttons to the right of each rule. Subtract an existing rule by clicking the minus button.

You can also link a set of rules by choosing the logical expression All or Any. If you use All logical expression, all the rules be true for a file to be included in the File list. If you use the Any option, only one of the conditions has to be met for a file to be included.

If you want to create more complex rules (e.g, some criteria matching all rules and others matching any), you can create sets of rules, by clicking the ellipsis button (to the right of the plus button). Repeat the above steps to add more rules to the filter until you have all the conditions you want to include.

Details on regular expressions

A regular expression is a general term refering to a method of searching for pattern matches in text. There is a high learning curve to using them, but are quite powerful once you understand the basics.

Patterns are specified using combinations of metacharacters and literal characters. There are a few classes of metacharacters, partially listed below. Some helpful links follow:

The following metacharacters match exactly one character from its respective set of characters:

.Any character
[]Any character contained within the brackets
[^]Any character not contained within the brackets
\wA word character [a-z_A-Z0-9]
\WNot a word character [^a-z_A-Z0-9]
\dA digit [0-9]
\DNot a digit [^0-9]
\sWhitespace [ \t\r\n\f\v]
\SNot whitespace [^ \t\r\n\f\v]

The following metacharacters are used to logically group subexpressions or to specify context for a position in the match. These metacharacters do not match any characters in the string:

( )Group subexpression
|Match subexpression before or after the |
^Match expression at the start of string
$Match expression at the end of string
\<Match expression at the start of a word
\>Match expression at the end of a word

The following metacharacters specify the number of times the previous metacharacter or grouped subexpression may be matched:

*Match zero or more occurrences
+Match one or more occurrences
?Match zero or one occurrence
{n,m}Match between n and m occurrences

Characters that are not special metacharacters are all treated literally in a match. To match a character that is a special metacharacter, escape that character with a '\'. For example '.' matches any character, so to match a '.' specifically, use '\.' in your pattern. Examples: