cytomapperShiny {cytomapper} | R Documentation

## 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 (nils.eling@dqbm.uzh.ch)

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

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

[Package cytomapper version 1.2.1 Index]