plotPixels {cytomapper} | R Documentation

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

### Description

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.

### Usage

    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: brightness value added to the specified channel contrast value multiplied with the specified channel 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.

### Author(s)

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

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

### See Also

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

### 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")))

[Package cytomapper version 1.2.1 Index]