Module: Groups

The Groups module organizes sets of images into groups.
Once the images have been identified with the Images module, have had metadata associated with them using the Metadata module, and have been assigned names by the NamesAndTypes module, you have the option of further sub-dividing the image sets into groups that share a common feature. Some downstream modules of CellProfiler are capable of processing groups of images in useful ways (e.g., object tracking within a set of images comprising a time series, illumination correction within a set of images comprising an experimental batch, data export for a set of images comprising a plate).

What is an image "group"?

The key to understanding why grouping may be necessary is that CellProfiler processes the input images sequentially and in the order given by the NamesAndTypes module. If you have multiple collections (or "groups") of images that should be processed independently from each other, CellProfiler will simply finish processing one collection and proceed to the next, ignoring any distinction between them unless told otherwise via the Groups module.

To illustrate this idea, below are two examples where the grouping concept can be useful or important:

What are the inputs?

Using this module assumes that you have already adjusted the following Input modules:

What do the settings mean?

See below for help on the individual settings. Selecting this module will display a panel, allowing you to select whether you want to create groups or not. A grouping may be defined as according to any or as many of the metadata categories as defined by the Metadata module. By selecting a metadata tag from the drop-down for the metadata category, the Groups module will sub-divide and assemble the image sets according to their unique metadata value. Upon adding a metadata category, the two tables underneath will update to show the resultant organization of the image sets for each group.

What do I get as output?

The final product of the Groups module is a list defining subsets of image sets that will be processed independently of the other subsets.

The two tables at the bottom provide the following information when a metadata category is selected:

Available measurements

Technical notes

To perform grouping, only one analysis worker (i.e., copy of CellProfiler) will be allocated to handle each group. This means that you may have multiple workers created (as set under the Preferences), but only a subset of them may actually be active, depending on the number of groups you have.

Settings:

Do you want to group your images?

Select Yes if you need to split your images into image subsets (or groups) such that each group is processed independently of each other. See the main module help for more details.

Metadata category

Specify the metadata category with which to define a group. Once a selection is made, the two listings below will display the updated values: You may specify multiple metadata tags to group with by clicking the "Add" button. This would be necessary if a combination of metadata is required in order to define a group. Upon adding a metadata category, the two tables will update in the panels below showing the resulting organization of the image data for each group.

As an example, an time-lapse experiment consists of a set of movie images (indexed by a frame number), collected on a per-well basis. The plate, well, wavelength and frame number metadata have been extracted using the Metadata module. Using the NamesAndTypes module, the two image channels (OrigBlue, w1 and OrigGreen, w2) have been set up in the following way:
Image set numberOrigBlue (w1) file nameOrigGreen (w2) file namePlateWellFrameNumber
1P-12345_A01_t001_w1.tifP-12345_A01_t001_w2.tifP-12345A01t001
2P-12345_A01_t002_w1.tifP-12345_A01_t002_w2.tifP-12345A01t002
3P-12345_B01_t001_w1.tifP-12345_B01_t001_w2.tifP-12345B01t001
4P-12345_B01_t002_w1.tifP-12345_B01_t002_w2.tifP-12345B01t002
52-ABCDF_A01_t001_w1.tif2-ABCDF_A01_t001_w2.tif2-ABCDF_A01t001
62-ABCDF_A01_t002_w1.tif2-ABCDF_A01_t002_w2.tif2-ABCDF_A01t002
72-ABCDF_B01_t001_w1.tif2-ABCDF_B01_t001_w2.tif2-ABCDF_B01t001
82-ABCDF_B01_t002_w1.tif2-ABCDF_B01_t002_w2.tif2-ABCDF_B01t002
We would like to perform object tracking for each movie, i.e., for each plate and well. Without the use of groups, even though image sets 1–2, 3–4, 5–6, and 7–8 represent different movies, image set 3 will get processed immediately after image set 2, image set 5 after 4, and so on. For an object tracking assay, failure to recognize where the movies start and end would lead to incorrect tracking results.

Selecting the Plate followed by the Well metadata as the metadata categories will create four groups based on the unique plate and well combinations:
Grouping tagsImage set tagsChannels
Group numberGroup indexImage set numberPlateWellFrameNumberOrigBlueOrigGreen
111P-12345A01t001P-12345_A01_t001_w1.tifP-12345_A01_t001_w2.tif
22P-12345A01t002P-12345_A01_t002_w1.tifP-12345_A01_t002_w2.tif
213P-12345B01t001P-12345_B01_t001_w1.tifP-12345_B01_t001_w2.tif
24P-12345B01t002P-12345_B01_t002_w1.tifP-12345_B01_t002_w2.tif
3152-ABCDFA01t0012-ABCDF_A01_t001_w1.tif2-ABCDF_A01_t001_w2.tif
262-ABCDFA01t0022-ABCDF_A01_t002_w1.tif2-ABCDF_A01_t002_w2.tif
4172-ABCDFB01t0012-ABCDF_B01_t001_w1.tif2-ABCDF_B01_t001_w2.tif
282-ABCDFB01t0022-ABCDF_B01_t002_w1.tif2-ABCDF_B01_t002_w2.tif
Each group will be processed independently from the others, which is the desired behavior.

Grouping list

This list shows the unique values of the selected metadata under the "Group" column; each of the unique values comprises a group. The "Count" column shows the number of image sets that included in a given group; this is useful as a "sanity check", to make sure that the expected number of images are present. For example, if you are grouping by per-plate metadata from a 384-well assay with 2 sites per well consisting of 3 plates, you would expect to see 3 groups (each from the 3 unique plate IDs), with 384 wells × 2 sites/well = 768 image sets in each.

Image sets

This list displays the file name and location of each of the image sets that comprise the group. For example, if you are grouping by per-plate metadata from a 384-well assay with 2 sites per well consisting of 3 plates, you would expect to see a table consisting of 3 plates × 384 wells/plate ×2 sites/well = 2304 rows.