Module: LoadImages

Load Images allows you to specify which images or movies are to be loaded and in which order.
This module tells CellProfiler where to retrieve images and gives each image a meaningful name by which other modules can access it. You can also use LoadImages to extract or define the relationships between images and their associated metadata. For example, you could load a group of images (such as three channels that represent the same field of view) together for processing in a single CellProfiler cycle. Finally, you can use this module to retrieve a label matrix and give the collection of objects a meaningful name.

Disclaimer: Please note that the Input modues (i.e., Images, Metadata, NamesAndTypes and Groups) largely supercedes this module. However, old pipelines loaded into CellProfiler that contain this module will provide the option of preserving them; these pipelines will operate exactly as before.

When used in combination with a SaveImages module, you can load images in one file format and save them in another, using CellProfiler as a file format converter.

Using metadata in LoadImages

If you would like to use the metadata-specific settings, please see Help > General help > Using metadata in CellProfiler for more details on metadata usage and syntax. Briefly, LoadImages can extract metadata from the image filename using pattern-matching strings, for grouping similar images together for the analysis run and for metadata-specfic options in other modules; see the settings help for Where to extract metadata, and if an option for that setting is selected, Regular expression that finds metadata in the file name for the necessary syntax.

Available measurements

See also the Input modules, LoadData, LoadSingleImage, SaveImages.

Settings:

File type to be loaded

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.

File selection method

Three options are available:

Number of images in each group?

(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.

Exclude certain files?

(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.

Type the text that the excluded images have in common

(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.

Analyze all subfolders within the selected folder?

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

Select 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.

Check image sets for unmatched or duplicate files?

(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.

Group images by metadata?

(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.

Specify metadata fields to group by

(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.

Text that these images have in common (case-sensitive)

(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.

Position of this image in each group

(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.

Load the input as images or objects?

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

Name this loaded image

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:

Name this loaded object

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

Retain outlines of loaded objects?

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

Name the outline image

(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.

Channel number

(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.

Rescale intensities?

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.

Extract metadata from where?

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

Regular expression that finds metadata in the file name

(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
_sDiscard 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.

Type the regular expression that finds metadata in the subfolder path

(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.

Group the movie frames?

(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.

Grouping method

(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 #
111
221
312
422
513
623

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

Frame #Channel #Image cycle #
111
212
313
421
522
623

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

Number of channels per group

(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 2nd, 5,th 8th and 11th frame will be assigned to channel 2 and the 3rd, 6th, 9th, and 12th 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.

Input image file location

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:

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