Spatial map over a tissue image — spatial • plotomics

Measurements plotted at their real coordinates on a slide, drawn on top of the histology image they came from. This is the layout of a spatial transcriptomics experiment: for a spatial assay the tissue is the axis, and a cluster tracing the edge of an invasive front says something an embedding cannot.

Usage

spatial(
  data,
  image,
  img_width,
  img_height,
  spot_diameter = 4,
  levels = NULL,
  colors = NULL,
  color_mode = c("auto", "categorical", "continuous"),
  colormap = c("viridis", "rdbu", "ltc", "ltcdiv"),
  spot_scale = 1,
  spot_opacity = 0.85,
  image_opacity = 1,
  show_image = TRUE,
  show_legend = TRUE,
  theme = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL
)

Arguments

data: A data frame with numeric x and y columns giving spot centres in image pixel coordinates. Optional color (character or numeric) and label (tooltip text) columns.
image: URL or path of the tissue image, as the browser will fetch it.
img_width, img_height: Natural size of that image in pixels.
spot_diameter: Spot diameter in image pixels.
levels, colors: Character vectors fixing the categorical order and colours. NULL derives them from the data and the theme palette.
color_mode: "auto" (detect from the column type), "categorical" or "continuous".
colormap: Sequential ramp for continuous colouring: "viridis", "rdbu", "ltc" (an earthy teal to sand to rust sequential ramp) or "ltcdiv" (its diverging counterpart, neutral cream at the midpoint).
spot_scale: Multiplier on spot_diameter; 1 draws true size.
spot_opacity, image_opacity: Opacities in [0, 1]. Lower the spot opacity to read the histology underneath.
show_image, show_legend: Toggle the underlay and the legend.
theme: Optional named list of theme overrides.
width, height: Widget dimensions (any valid CSS size).
element_id: Optional explicit DOM id.

Value

An htmlwidget object.

Details

The image and the spots share one "contain" fit, computed once, so histology and overlay cannot drift apart on resize, full-screen, or a high-DPI display.

color may be a character vector (categorical, discrete legend) or numeric (continuous, sequential ramp with a colourbar), which is what lets one view toggle between colouring by cluster and by a gene's expression.

Scale

Spots are drawn one at a time on a 2-D canvas, which suits a Visium-scale slide of a few thousand spots. This is not a renderer for Xenium or CosMx-scale single-cell output: a million cells will not stay interactive here. For that many points use embedding(), which draws on the GPU via regl-scatterplot, and accept that it has no image underlay. Plotting both a histology image and a million single cells is not something this package currently does.

Examples

df <- data.frame(
  x = c(100, 150, 200), y = c(120, 160, 90),
  color = c("Cluster 1", "Cluster 2", "Cluster 1")
)
spatial(df, image = "tissue.png", img_width = 600, img_height = 600,
        spot_diameter = 8)