Function to visualize pixel-level information of multi-channel images

Source: R/plotPixels.R

This function takes a CytoImageList object to colour pixels by marker expression. Additionally, a SingleCellExperiment object and CytoImageList object containing segmentation masks can be provided to outline cells based on metadata.

plotPixels(
  image,
  object = NULL,
  mask = NULL,
  cell_id = NULL,
  img_id = NULL,
  colour_by = NULL,
  outline_by = NULL,
  bcg = NULL,
  colour = NULL,
  ...
)

Arguments

image

a CytoImageList object containing single or multi-channel Image objects (see details below).

object

an optional SingleCellExperiment object.

mask

an optional CytoImageList object containing segmentaion masks in form of single-channel Image objects (see details below)

cell_id

character specifying the colData(object) entry, in which the integer cell IDs are stored. These IDs should match the integer pixel values in the segmentation mask object.

img_id

character specifying the colData(object), mcols(image) and mcols(mask) entry, in which the image IDs are stored (see section 'Linking the SingleCellExperiment and CytoImageList objects' below)

colour_by

character or character vector specifying the features (contained in channelNames(image)) used to colour individual cells. Pixels can be coloured by up to six features.

outline_by

single character indicating the colData(object) entry by which to outline individual cells

bcg

a list with names matching the entries to colour_by. Each entry contains a numeric vector of three entries:

  1. brightness value added to the specified channel

  2. contrast value multiplied with the specified channel

  3. gamma value (channel is exponentiated by this value)

Default is c(0,1,1).

colour

a list with names matching the entries to colour_by and/or outline_by. When setting the colour for continous features, at least two colours need to be provided indicating the colours for minimum and maximum values. When outlining by discrete values, a colour for each unique entry needs to be provided (see section 'Setting the colours' and examples)

...

Further arguments passed to ?"plotting-param"

Value

a list if return_images and/or return_plot

is TRUE (see ?"plotting-param").

  • plot: a single plot object (display = "all") or a list of plot objects (display = "single")

  • images: a SimpleList object containing three-colour Image objects.

Multi-channel image and segmentation mask objects

In the plotPixels function, image refers to a CytoImageList object that contains a single or multiple single- or multi-channel Image objects. Up to six channels can be overlayed to generate a composite image. When outlining cells, a SingleCellExperiment object and CytoImageList object containing segmentation masks must be provided. The function assumes that each object in the segmentation mask is a cell. The key features of such segmentation masks include:

  • each Image object contains only one channel

  • pixel values are integers indicating the cells' IDs

Linking SingleCellExperiment and CytoImageList objects

To outline individual cells contained in the segmentation masks based on metadata stored in the SingleCellExperiment object, an img_id and cell_id entry needs to be provided. Image IDs are matched between the SingleCellExperiment and CytoImageList objects via entries to the colData(object)[,img_id], mcols(image)[,img_id] and the mcols(image)[,img_id] slots. Cell IDs are matched between the SingleCellExperiment and CytoImageList object via entries to colData(object)[,cell_id] and the integer values of the segmentation masks.

Setting the colours

By default, features and metadata are coloured based on internally-set colours. To set new colours, a list object must be provided. The names of the object must correspond to the entries to colour_by and/or outline_by. When setting the colours for continous expression values or continous metadata entries, a vector of at least two colours need to be specified. These colours will be passed onto colorRampPalette for interpolation. Cells can be outlined by discrete metadata entries when specifying a named vector in which each entry corresponds to a unique entry to the metadata vector.

Subsetting the CytoImageList objects

The CytoImageList object(s) can be subsetted before calling the plotPixels function. In that case, only the selected images are displayed.

Subsetting the SingleCellExperiment object

The SingleCellExperiment object can be subsetted before calling the plotPixels function. In that case, only cells contained in the SingleCellExperiment object are outlined.

Colour scaling

When plotting pixel intensities, colours are scaled to the minimum and maximum per channel across all images that are being displayed. Therefore, when subsetting images, displayed intensities might change. However, the colour legend will display the correct numeric minimum and maximum pixel intensity across all displayed images per channel.

See also

For further plotting parameters see ?"plotting-param". For instructions on how to normalize images see normalize.

Author

Nils Eling (nils.eling@dqbm.uzh.ch)

Nicolas Damond (nicolas.damond@dqbm.uzh.ch)

Examples

data(pancreasMasks)
data(pancreasImages)
data(pancreasSCE)

# Visualize the images - by default the first channel
plotPixels(pancreasImages)


# Colour the channels
plotPixels(pancreasImages, colour_by = c("CD99", "CDH"))


# Outline the cells based on metadata
plotPixels(pancreasImages, object = pancreasSCE, mask = pancreasMasks,
            img_id = "ImageNb", cell_id = "CellNb",
            colour_by = c("CD99", "CDH"), outline_by = "CellType")


# Enhance individual channels
plotPixels(pancreasImages, colour_by = c("CD99", "CDH"),
            bcg = list(CD99 = c(0, 2, 1)))


# Subset the images
cur_images <- getImages(pancreasImages, 1:2)
plotPixels(cur_images, colour_by = c("CD99", "CDH"))


# Set colour
plotPixels(pancreasImages, colour_by = c("CD99", "CDH"),
            colour = list(CD99 = c("black", "green"),
                            CDH = c("black", "blue")))