cytomapperShiny: Shiny application to visualise gated cells on images
In cytomapper: Visualization of highly multiplexed imaging data in R

Description Usage Arguments Value User inputs The user interface (UI) Download of gated cells Passing further parameters Getting further help Author(s) See Also Examples

View source: R/cytomapperShiny.R

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

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

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

A Shiny app object for hierarchical gating of cells

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

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

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 .

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.

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

Tobias Hoch (tobias.hoch@dqbm.uzh.ch)

plotCells and plotPixels for the main plotting functions

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