interpretSpheres: Interactive interpretation of hyperspheres
In cydar: Using Mass Cytometry for Differential Abundance Analyses

Description Usage Arguments Details Value Navigation Putting in additional plots Inspecting label propagation Author(s) See Also Examples

View source: R/interpretSpheres.R

Launches a Shiny app to assist interpretation of hyperspheres.

interpretSpheres(x, markers=NULL, labels=NULL, select=NULL, metrics=NULL, 
    num.per.row=6, plot.height=100, xlim=NULL, p=0.01, 
    red.coords=NULL, red.highlight=NULL, red.plot.height=500, 
    add.plot=NULL, add.plot.height=500, run=TRUE, ...)

`x`	A CyData object generated by `countCells`, containing counts and coordinates for each hypersphere.
`markers`	A character vector indicating the markers to use, and the order they should be plotted in. If `NULL`, all markers are used in the order corresponding to the columns of `intensities(x)`.
`labels`	A character vector containing existing labels for the hyperspheres. This should be of length equal to the number of rows in `x`.
`select`	A logical or integer vector indicating which rows of `x` should be inspected. Defaults to all rows.
`metrics`	A dataframe containing metrics to be reported for each hypersphere, with number of rows equal to `x`.
`num.per.row`	An integer scalar specifying the number of plots per row.
`plot.height`	An integer scalar specifying the height of each plot in pixels.
`xlim`	A numeric vector of length two specifying the x-axis limits for all plots. Otherwise, `intensityRanges` is used to define limits for each marker.
`p`	A numeric scalar to be passed to `intensityRanges`.
`red.coords`	A numeric matrix with two columns and number of rows equal to `nrow(x)`, containing a reduced-dimension representation of hypersphere coordinates. The first and second columns should contain the x- and y-coordinates, respectively.
`red.highlight`	A logical or integer vector specifying which rows of `x` should be highlighed on the reduced dimensionality plot.
`red.plot.height`	An integer scalar specifying the height of the reduced-dimension plot.
`add.plot`	A function taking two arguments (see below) to create additional plots in the app.
`add.plot.height`	An integer scalar specifying the height of the additional plots.
`run`	A logical scalar specifying whether the Shiny app should be run.
`...`	Additional arguments to be passed to `density`.

This function creates a Shiny app in which density plots are constructed for intensities across all cells, one for each marker. For a given hypersphere, the median intensity is plotted as a red circle on top of the density plot for each marker. This allows users to quickly determine the biological meaning of each hypersphere, based on its median marker expression (and other statistics in metrics).

For each marker, the area under the curve is highlighted using the viridis colour scheme. This is based on whether the median is relatively high (yellow) or low (purple) compared to all of the cells. An interval around the median is also displayed, representing the range of intensities across a given percentage (default 95%) of cells in the hypersphere. This provides more information about the spread of intensities within each hypersphere.

Each hypersphere can be labelled with some meaningful term, e.g., the cell type that corresponds to the suite of expressed markers. For each hypersphere, the closest hyperspheres that have already been labelled are shown, along with the Euclidean distances to their locations. This is designed to assist with the labelling process by identifying pre-labelled hyperspheres in the neighbouring space.

Finally, the labels can be saved to R using the “Save to R” button. This stops the app and returns a character vector of labels in the R session. Existing labels can also be re-used by supplying them to labels, to allow users to label parts of the data set at a time.

If run=FALSE, a Shiny app is returned that can be run with runApp. This passes control to a browser window in which labels can be entered for each hypersphere. Upon stopping the app, a character vector of length equal to the number of rows in x is returned.

If run=TRUE, a Shiny app is opened directly in a browser window. This returns a character vector upon stopping, as previously described.

Users can navigate through the data set using the “Previous” or “Next” buttons. This moves across hyperspheres specified by select, i.e., pressing “Next” will jump to the next hypersphere in select. By default, select=NULL which means that the app will progress through all hyperspheres in x. It is often worth setting select, e.g., to non-redundant significant hyperspheres in order to reduce the number of elements that need to be inspected.

Users can also jump to a particular row/hypersphere by providing an integer scalar in the “Go to sphere” field. This specifies the row index for the hypersphere of interest, and works for either selected or unselected hyperspheres. However, pressing “Previous” or “Next” will jump to the nearest index of the selected hyperspheres. The navigation history at any given time is shown in the side bar.

A reduced-dimensionality plot is also constructed using specified coordinates in two-dimensional space for each hypersphere. The current hypersphere is marked on this plot with a red dot. Previously visited and labelled hyperspheres are marked in black. Users can also highlight particular hyperspheres in orange with red.highlight, e.g., if they are significantly differential or not.

Users can define add.plot as a function taking two arguments:

An integer scalar, specifying the row index of the second argument. This corresponds to the hypersphere currently being inspected.
A CyData object, which is set internally to the value of x used in interpretSpheres. This should contain information about all hyperspheres.

add.plot should generate a plot on the current graphics device. This is usually done in a hypersphere-specific manner, where the first argument is used to extract the relevant information from the second argument. For example, the abundances of all samples can be visualized directly for each hypersphere in the app.

If red.dim is supplied and at least one cell is labelled, the “Update labels” button can be used to propagate the labels to surrounding cells. Specifically, for each unlabelled cell, the closest labelled cell is identified and its label is assigned to the unlabelled cell. A plot is then created showing the distribution of cells for each label in the low-dimensional space.

This functionality is useful for determining how the labels would be automatically assigned by labelSpheres. If many distinct clusters have the same label, it suggests that more manual labelling is required to distinguish clusters. Note that the automatically assigned labels are not recorded, they are only used here for visualization purposes.

Aaron Lun

density, intensityRanges, runApp

# Mocking up some data.
example(prepareCellData, echo=FALSE)
cnt <- countCells(cd, filter=1)

# Constructing the app
app <- interpretSpheres(cnt, run=FALSE)

## Not run: # Running the app from the object.
labels <- shiny::runApp(app)

#Or directly running the app from the function.
labels <- interpretSpheres(cnt)

## End(Not run)

# Doing it with metrics and coordinates.
N <- nrow(cnt)
metrics <- data.frame(logFC=rnorm(N), PValue=runif(N))
coords <- matrix(rnorm(N*2), ncol=2)
app <- interpretSpheres(cnt, red.coord=coords, metrics=metrics, run=FALSE)

# Doing it with an extra plot.
app <- interpretSpheres(cnt, run=FALSE, add.plot=function(i, x) {
    barplot(assay(x)[i,]/x$totals*100, ylab="Percentage of cells")
})