Plot Representations of Spatial Biology Data

Plot pretty much anything over the Representation class easily. Required arguments are a SpatialMap or Region object; a representation (e.g. "spatial", "umap"); and the name of something to plot, usually a column in cellMetadata, a marker, or other feature.

Usage

plotRepresentation(
  object,
  representation,
  what,
  graph = NULL,
  graph.keep = NULL,
  graph.linesize = 0.25,
  graph.alpha = 0.2,
  plot.type = c("single", "avg"),
  window = NULL,
  color.pal = NULL,
  data.slot = "Data",
  plot.title = NULL,
  plot.titles.from = NULL,
  outline.color = "black",
  trim = NULL,
  color.lims = NULL,
  scale = F,
  aspect.ratio = NULL,
  pointsize = 0.25,
  alpha = 1,
  invert = NULL,
  all.match = F,
  raster = F,
  pixel.res = 512,
  shuffle = FALSE,
  subsample = NULL,
  ...
)

Arguments

object

A SpatialMap or Region object

representation

The representation to plot (e.g. "spatial", "umap"). The first two columns of the representation will become the x and y axes of your plot.

what

What to color the plot by. A list of features, a metadata column, etc. Loose match

graph

The name of a network-graph representation to add to the plot

graph.keep

Indices (T/F) indicating nodes that should be kept while plotting edges. For example, the user could generate a plot showing only edges between celltype A and celltype B. When plotting from a SpatialMap object, the logical vector should be of length cells(sm).

graph.linesize

The thickness of network-graph lines

graph.alpha

The opacity of network-graph lines

plot.type

A single panel or an average of multiple markers?

window

Optional filtering by position in the form: list( c(x_min, x_max), c(y_min, y_max) )

color.pal

Vector of colors to plot with (passed to scale_color_ helpers)

data.slot

If the inputs are features, should we get values from NormalizedData (default), Data, or ScaledData slot in Region?

plot.title

Plot title

plot.titles.from

A projectMetadata or cellMetadata column from which to pull plot titles, e.g. "region_display_label" (for SpatialMap or Region objects, respectively). Takes precedence over plot.title. Only tested when the activeAnalysis is "regions"

outline.color

Outline color for polygons and other fill geoms

trim

Two-element vector denoting quantiles trimmed from the color scale, for continuous variables only (ignored if categorical)

color.lims

Enforce arbitrary limits on the color scale of the plot

scale

For continous variables only, whether to apply center-scaling

aspect.ratio

ggplot param

pointsize

ggplot param

alpha

ggplot param

invert

Whether to invert scales. Useful because certain image processing tools give coordinates relative to the top-left of an image, and ggplot2 will plot these relative to the bottom-left.

all.match

Argument passed to anyMatch

raster

Whether to raster points. Point representations only. Forces to TRUE with more than 150,000 points.

pixel.res

When raster is TRUE, sets the pixel resolution of the resultant image

shuffle

Whether to randomize how the points are stacked. Useful for very dense UMAPs, where the default would plot the last region on top, allowing it to dominate the visualization.

subsample

Whether to subsample the data for plotting. Accepts a proportion between 0 and 1. If NULL (default), subsampling will not be performed.

...

Additional arguments passed to .smapply

Value

A ggplot object

Details

See the analysis guide vignettes and vignette("Tutorial_Plotting_with_SpatialMap") for example workflows that make use of this function. Some features of plotRepresentation:

• Automatically recognize and interpret covariates from across the SpatialMap object.

• Pass expressions to subset data points or highlight categories.

• The same interface supports spatial coordinates, network graphs, and other embeddings (pca, umap, etc.).

• Customize colors and other graphical parameters

• Quantile trimming for quantitative data

• Pass coordinates to 'window' the data

• Raster points for huge plots

• Much more!