Module: LoadImages

CellProfiler accepts the following image file types. For movie file formats, the files are opened as a stack of images and each image is processed individually, although TrackObjects can be used to relate objects across timepoints.

• individual images: Each file represents a single image. Some methods of file compression sacrifice image quality ("lossy") and should be avoided for automated image analysis if at all possible (e.g., .jpg). Other file compression formats retain exactly the original image information but in a smaller file ("lossless") so they are perfectly acceptable for image analysis (e.g., .png, .tif, .gif). Uncompressed file formats are also fine for image analysis (e.g., .bmp).
• avi,mov movies: AVIs (Audio Video Interleave) and MOVs (QuicktTime) files are types of movie files. Only uncompressed AVIs are supported; supported MOVs are listed here. Note that .mov files are not supported on 64-bit systems.
• stk movies: STKs are a proprietary image format used by MetaMorph (Molecular Devices). It is typically used to encode 3D image data, e.g. from confocal microscopy, and is a special version of the TIF format.
• tif,tiff,flex,zvi movies: A TIF/TIFF movie is a file that contains a series of images as individual frames. The same is true for the FLEX file format (used by Evotec Opera automated microscopes). ZVIs are a proprietary image format used by Zeiss. It is typically used to encode 3D image data, e.g. from fluorescence microscopy.

Three options are available:

• Text-Exact match: Used to load image (or movie) files that have a particular piece of text in the name. The specific text that is entered will be searched for in the filenames and the files that contain that text exactly will be loaded and given the name you specify. The search for the text is case-sensitive.
• Text-Regular expressions: Used to load image (or movie) files that match a pattern of regular expressions. Patterns are specified using combinations of metacharacters and literal characters. There are a few classes of metacharacters, partially listed below. Some helpful links follow:
  • A more extensive explanation of regular expressions can be found here
  • A helpful quick reference can be found here
  • Pythex provides quick way to test your regular expressions. Here is an example to capture information from a common microscope nomenclature.

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

  Metacharacter	Meaning
  .	Any character
  []	Any character contained within the brackets
  [^]	Any character not contained within the brackets
  \w	A word character [a-z_A-Z0-9]
  \W	Not a word character [^a-z_A-Z0-9]
  \d	A digit [0-9]
  \D	Not a digit [^0-9]
  \s	Whitespace [ \t\r\n\f\v]
  \S	Not 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:
  
  

  Metacharacter	Meaning
  ( )	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:
  
  

  Metacharacter	Meaning
  *	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:

  • [trm]ail matches 'tail' or 'rail' or 'mail'.
  • [0-9] matches any digit between 0 to 9.
  • [^Q-S] matches any character other than 'Q' or 'R' or 'S'.
  • [[]A-Z] matches any upper case alphabet along with square brackets.
  • [ag-i-9] matches characters 'a' or 'g' or 'h' or 'i' or '-' or '9'.
  • [a-p]* matches '' or 'a' or 'aab' or 'p' etc.
  • [a-p]+ matches 'a' or 'abc' or 'p' etc.
  • [^0-9] matches any string that is not a number.
  • ^[0-9]*$ matches either a blank string or a natural number.
  • ^-[0-9]+$|^\+?[0-9]+$ matches any integer.
• Order: Used when image (or movie) files are present in a repeating order, like "DAPI, FITC, Red; DAPI, FITC, Red;" and so on. Images are loaded based on the order of their location on the hard disk, and they are assigned an identity based on how many images are in each group and what position within each group the file is located (e.g., three images per group; DAPI is always first).

(Used only when Order is selected for file loading)
Enter the number of images that comprise a group. For example, for images given in the order: DAPI, FITC, Red; DAPI, FITC, Red and so on, the number of images that in each group would be 3.

(Used only if "Text-Exact match" for loading files is selected)
The image/movie files specified with the Text options may also include files that you want to exclude from analysis (such as thumbnails created by an imaging system). Select Yes to enter text to match against such files for exclusion.

(Used only if file exclusion is selected)
Specify text that marks files for exclusion. LoadImages looks for this text as an exact match within the filename and not as a regular expression.

This setting determines whether LoadImages analyzes just the images in the specified folder or whether it analyzes images in subfolders as well:

• All: Analyze all matching image files in subfolders under your specified image folder location.
• None: Only analyze files in the specified location.
• Some: Select which subfolders to analyze.

Use this control to select some subfolders and exclude others from analysis. Press the button to see the folder tree and check or uncheck the checkboxes to enable or disable analysis of the associated folders.

(Used only if metadata is extracted from the image file and not loading by order)
Select Yes to examine the filenames for unmatched or duplicate files based on extracted metadata. This is useful for images generated by HCS systems where acquisition may produce a corrupted image and create a duplicate as a correction or may miss an image entirely. See the Extract metadata from where? setting for more details on obtaining, extracting, and using metadata tags.

(Used only if metadata is extracted from the image file or if movies are used)
Select Yes to process those images that share a particular metadata tag as a group. For example, if you are performing per-plate illumination correction and the plate metadata is part of the image file name, image grouping will enable you to process those images that have the same plate field together (the alternative would be to place the images from each plate in a separate folder). The next setting allows you to select the metadata tags by which to group.Please see the Groups module for more details on the proper use of metadata for grouping

Please note that if you are loading a movie file(e.g., TIFs, FLEX, STKs, AVIs, ZVIs), each movie is already treated as a group of images, so there is no need to enable here.

(Used only if grouping images by metadata)
Select the fields by which you want group the image files. You can select multiple tags. For example, if a set of images had metadata for "Run", "Plate", "Well", and "Site", selecting Run and Plate will create groups containing images that share the same [Run,Plate] pair of fields.

(Used only for the image-loading Text options)
For Text-Exact match, type the text string that all the images have in common. For example, if all the images for the given channel end with the text "D.TIF", type D.TIF here.

For Text-Regular expression, type the regular expression that would capture all the images for this channel. See the module help for more information on regular expressions.

(Used only for the image-loading Order option)
Enter the number in the image order that this image channel occupies. For example, if the order is "DAPI, FITC, Red; DAPI, FITC, Red" and so on, the DAPI channel would occupy position 1.

This setting determines whether you load an image as image data or as segmentation results (i.e., objects):

• Images: The input image will be given a user-specified name by which it will be refered downstream. This is the most common usage for this module.
• Objects: Use this option if the input image is a label matrix and you want to obtain the objects that it defines. A label matrix is a grayscale or color image in which the connected regions share the same label, and defines how objects are represented in CellProfiler. The labels are integer values greater than or equal to 0. The elements equal to 0 are the background, whereas the elements equal to 1 make up one object, the elements equal to 2 make up a second object, and so on. This option allows you to use the objects without needing to insert an Identify module to extract them first. See IdentifyPrimaryObjects for more details.

What do you want to call the images you are loading for use downstream in the pipeline? Give your images a meaningful name that you can use to refer to these images in later modules. Keep the following points in mind:

• Image names can consist of any combination of characters (e.g., letters, digits, and other non-alphanumeric characters). However, if you are using ExportToDatabase, these names will become part of the measurement column name, and some characters are not permitted in MySQL (e.g., slashes).
• Names are not case sensitive. Therefore, OrigBlue, origblue, and ORIGBLUE will all correspond to the same name, and unexpected results may ensue.
• Although CellProfiler can accept names of any length, you may want to avoid making the name too long, especially if you are uploading to a database. The name is used to generate the column header for a given measurement, and in MySQL the total bytes used for all column headers cannot exceed 64K. A warning will be generated later if this limit has been exceeded.

(Used only if objects are output)
This is the name for the objects loaded from your image

(Used only if objects are output)
Select Yes if you want to create an image of the outlines of the loaded objects.

(Used only if objects are output and outlines are saved)
Enter a name that will allow the outlines to be selected later in the pipeline.

Special note on saving images: You can use the settings in this module to pass object outlines along to the module OverlayOutlines, and then save them with the SaveImages module.

(Used only if a movie image format is selected as file type and movie frame grouping is selected)
The channels of a multichannel image are numbered starting from 1. Each channel is a greyscale image, acquired using different illumination sources and/or optics. Use this setting to pick the channel to associate with the above image name.

This option determines whether image metadata should be used to rescale the image's intensities. Some image formats save the maximum possible intensity value along with the pixel data. For instance, a microscope might acquire images using a 12-bit A/D converter which outputs intensity values between zero and 4095, but stores the values in a field that can take values up to 65535.

Select Yes to rescale the image intensity so that saturated values are rescaled to 1.0 by dividing all pixels in the image by the maximum possible intensity value.

Select No to ignore the image metadata and rescale the image to 0 – 1.0 by dividing by 255 or 65535, depending on the number of bits used to store the image.

Metadata fields can be specified from the image filename, the image path (including subfolders), or both. The metadata entered here can be used for image grouping (see the Group images by metadata? setting) or simply used as additional columns in the exported measurements (see the ExportToSpreadsheet module).

(Used only if you want to extract metadata from the file name)
The regular expression to extract the metadata from the file name is entered here. Note that this field is available whether you have selected Text-Regular expressions to load the files or not. Please see the general module help for more information on construction of a regular expression.

Clicking the magnifying glass icon to the right will bring up a tool for checking the accuracy of your regular expression. The regular expression syntax can be used to name different parts of your expression. The syntax (?P<fieldname>expr) will extract whatever matches expr and assign it to the measurement,fieldname for the image.

For instance, a researcher uses plate names composed of a string of letters and numbers, followed by an underscore, then the well, followed by another underscore, followed by an "s" and a digit representing the site taken within the well (e.g., TE12345_A05_s1.tif). The following regular expression will capture the plate, well, and site in the fields "Plate", "Well", and "Site":

^(?P<Plate>.*)_(?P<Well>[A-P][0-9]{1,2})_s(?P<Site>[0-9])
^	Start only at beginning of the file name
(?P<Plate>	Name the captured field Plate
.*	Capture as many characters as follow
_	Discard the underbar separating plate from well
(?P<Well>	Name the captured field Well
[A-P]	Capture exactly one letter between A and P
[0-9]{1,2}	Capture one or two digits that follow
_s	Discard the underbar followed by s separating well from site
(?P<Site>	Name the captured field Site
[0-9]	Capture one digit following

The regular expression can be typed in the upper text box, with a sample file name given in the lower text box. Provided the syntax is correct, the corresponding fields will be highlighted in the same color in the two boxes. Press Submit to enter the typed regular expression.

You can create metadata tags for any portion of the filename or path, but if you are specifying metadata for multiple images in a single LoadImages module, an image cycle can only have one set of values for each metadata tag. This means that you can only specify the metadata tags which have the same value across all images listed in the module. For example, in the example above, you might load two wavelengths of data, one named TE12345_A05_s1_w1.tif and the other TE12345_A05_s1_w2.tif, where the number following the w is the wavelength. In this case, a "Wavelength" tag should not be included in the regular expression because while the "Plate", "Well" and "Site" metadata is identical for both images, the wavelength metadata is not.

Note that if you use the special fieldnames <WellColumn> and <WellRow> together, LoadImages will automatically create a <Well> metadata field by joining the two fieldname values together. For example, if <WellRow> is "A" and <WellColumn> is "01", a field <Well> will be "A01". This is useful if your well row and column names are separated from each other in the filename, but you want to retain the standard well nomenclature.

(Used only if you want to extract metadata from the path)
Enter the regular expression for extracting the metadata from the path. Note that this field is available whether you have selected Text-Regular expressions to load the files or not.

Clicking the magnifying glass icon to the right will bring up a tool that will allow you to check the accuracy of your regular expression. The regular expression syntax can be used to name different parts of your expression. The syntax (?<fieldname>expr) will extract whatever matches expr and assign it to the image's fieldname measurement.

For instance, a researcher uses folder names with the date and subfolders containing the images with the run ID (e.g., ./2009_10_02/1234/) The following regular expression will capture the plate, well, and site in the fields Date and Run:

.*[\\/](?P<Date>.*)[\\/](?P<Run>.*)$
.*[\\/]	Skip characters at the beginning of the pathname until either a slash (/) or backslash (\) is encountered (depending on the operating system)
(?P<Date>	Name the captured field Date
.*	Capture as many characters that follow
[\\/]	Discard the slash/backslash character
(?P<Run>	Name the captured field Run
.*	Capture as many characters as follow
$	The Run field must be at the end of the path string, i.e., the last folder on the path. This also means that the Date field contains the parent folder of the Date folder.

(Used only if a movie image format is selected as file type)
LoadImages can load several frames from a movie into different images within the same cycle. For example, a movie's first frame might be an image of the red fluorescence channel at time zero, the second might be the green channel at time zero, the third might be the red channel at time one, etc. Select Yes to extract both channels for this movie as separate images within the same cycle.

LoadImages refers to the individual images in a group as channels. Channels are numbered consecutively, starting at channel 1. To set up grouping, first specify how the channels are grouped (interleaving and number of channels per group), then assign image names to each of the channels individually.

(Used only if a movie image format is selected as file type and movie frame grouping are selected)
Channels in a movie can be interleaved or separated.

In an interleaved movie, the first frame is channel 1, the second is channel 2 and so on up to the number of channels per group for a given image cycle. In a separated movie, all of the frames for channel 1 are processed as the first image cycle, then the frames for channel 2 for the second image cycle, and so on.

For example, a movie may consist of 6 frames and we would like to process the movie as two channels per group. An interleaved movie would be processed like this:

Frame #	Channel #	Image cycle #
1	1	1
2	2	1
3	1	2
4	2	2
5	1	3
6	2	3

For a separated movie, the channels would be processed like this:

Frame #	Channel #	Image cycle #
1	1	1
2	1	2
3	1	3
4	2	1
5	2	2
6	2	3

Note the difference in which frames are processed in which image cycle between the two methods.

(Used only if a movie image format is selected as file type and movie frame grouping is selected)
This setting controls the number of frames to be grouped together. As an example, for an interleaved movie with 12 frames and three channels per group, the first, fourth, seventh and tenth frame will be assigned to channel 1, the 2^nd, 5,^th 8^th and 11^th frame will be assigned to channel 2 and the 3^rd, 6^th, 9^th, and 12^th will be assigned to channel 3. For a separated movie, frames 1 through 4 will be assigned to channel 1, 5 through 8 to channel 2 and 9 through 12 to channel 3.

Select the folder containing the images 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.