cytomapperShiny: Shiny application to visualise gated cells on images

In BodenmillerGroup/cytomapper: Visualization of highly multiplexed imaging data in R

Shiny application to visualise gated cells on images

Description

This shiny application allows users to gate cells based on their raw or transformed expression values and visualises gated cells on their corresponding images.

Usage

cytomapperShiny(
  object,
  mask = NULL,
  image = NULL,
  cell_id = NULL,
  img_id = NULL,
  ...
)

Arguments

object	a SingleCellExperiment object.
mask	(optional) a CytoImageList containing single-channel Image objects.
image	(optional) a CytoImageList object containing single or multi-channel Image objects.
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 (mask).
img_id	character specifying the colData(object) and mcols(mask) and/or mcols(image) entry, in which the image IDs are stored.
...	parameters passed to the plotCells or plotPixels function.

Value

A Shiny app object for hierarchical gating of cells

User inputs

This function requires at least a SingleCellExperiment input object. Gating is performed on cell-specific marker counts stored in the assay slots of the object. These can either be raw counts (usually stored in the counts slot) or transformed/scaled counts stored in other assay slots. Gating can only be performed sample-wise; therefore, even if mask or image are not specified, img_id needs to point to the colData entry storing unique sample IDs. Furthermore, the cell_id entry is required to identify cells during hierarchical gating.

If mask is specified, marker expression values and selected cells will be visualised by using the plotCells function. To visualise pixel-level information with plotPixels, the user has to further provide multi-channel images stored in a CytoImageList.

The user interface (UI)

The UI's body is composed of two tabs (Scatter Plots and Images). The side bar contains the General Control and Plots panels. Both panels can be collapsed; however only one can be expanded again.. Using the control panel, the user can set the number of plots, which sample to display and which assay slot to use for plotting expression. The Plots panel can be used to select up to two markers per plot. A one-marker selection is displayed as violin and jittered points, two markers are shown as scatter plot. To define a subset of cells, the user can draw gates on the plots. When using multiple plots, the gate applied in a plot will define the subset of cells displayed in the next plot. The number of plots, the marker selection and the applied gates will be transferred when switching between samples. When switching markers or assay slots, the gates will be removed.

By switching to the Images tab, the user can inspect marker expression levels and the result of the gating. This requires either an entry to mask and (optionally) image. Depending on the input, the left image visualises the expression of the selected markers by using plotCells (if mask is supplied) or plotPixels (if image is supplied). Displayed markers can be changed using the dropdown menu. If images are provided, the user can change the contrast of the selected markers. The right image colors (masks) or outlines (images) gated cells. Both the left and the right image come with a zoom-in functionality.

The header section of the shiny allows to hide the side bar, to download selected cells (see below), or to display the sessionInfo output and the Help section (see below).

Download of gated cells

The user can download the selected cells in form of a SingleCellExperiment object. The output is a subset of the input SingleCellExperiment object. The downloaded object (in form of a .rds file) contains a new colData entry containing the label of the subset defined by the user (using the Cell label argument). The cell label is stored in colData(object)$cytomapper_CellLabel

The metadata slot of the SingleCellExperiment object will be converted to a list. It contains the original metadata (metadata(object)$metadata), gating parameters (e.g. metadata(object)$cytomapper_gate_1), sessionInfo() output (metadata(object)$cytomapper_SessionInfo), and the date (metadata(object)$cytomapper_GatingDate).

Passing further parameters

To customise the visual output of cytomapperShiny, refer to plotting-param. Further arguments can be passed to the plotCells and plotPixels function. As an example: To avoid interpolation of output images, set interpolate = FALSE. Passing the parameter interpolate = FALSE will make images less blurry, which might be useful while using the zoom-in functionality of cytomapperShiny .

Getting further help

Please refer to the Help section found when clicking the '?' button in the upper right corner. The Help section contains a recommended workflow on how to use the app.

Author(s)

Nils Eling ([e-mail])

Tobias Hoch ([e-mail])

See Also

plotCells and plotPixels for the main plotting functions

Examples

## Only run this example in interactive R sessions
if (interactive()) {
   # Load example data sets
   data("pancreasSCE")
   data("pancreasImages")
   data("pancreasMasks")

   # Use shiny with SCE object, images and masks
   cytomapperShiny(object = pancreasSCE, mask = pancreasMasks, 
                 image = pancreasImages, cell_id = "CellNb", 
                 img_id = "ImageNb")

   # Use shiny with SCE object and masks
   cytomapperShiny(object = pancreasSCE, mask = pancreasMasks,
                 cell_id = "CellNb", img_id = "ImageNb")

   # Use shiny with SCE object only
   cytomapperShiny(object = pancreasSCE,
                 cell_id = "CellNb", img_id = "ImageNb")
}

BodenmillerGroup/cytomapper documentation built on July 1, 2024, 3:45 p.m.