Marker gene dot plot

Features down the rows, groups across the columns, each cell a dot whose size is the fraction of the group expressing the gene and whose colour is the expression level. Two channels because colour alone cannot separate "high in a few cells" from "moderate in all of them", and that distinction is usually what decides whether a gene is a marker.

Usage

dotplot(
  data,
  genes = NULL,
  clusters = NULL,
  value_label = "mean expression",
  size_label = "% expressing",
  colormap = c("viridis", "rdbu", "ltc", "ltcdiv"),
  max_radius = 9,
  value_domain = NULL,
  show_grid = TRUE,
  show_legend = TRUE,
  theme = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL
)

Arguments

data

A data frame in long form, one row per dot, with gene and cluster key columns, a pct column (percent expressing, 0-100) driving dot size, and a value column (expression level) driving dot colour.

genes

Character vector fixing the row order. A factor gene column supplies it from its levels. Defaults to order of appearance.

clusters

Character vector fixing the column order, likewise.

value_label, size_label

Legend titles.

colormap

Sequential ramp for the colour channel: "viridis", "rdbu", "ltc" (an earthy teal to sand to rust sequential ramp) or "ltcdiv" (its diverging counterpart, neutral cream at the midpoint).

max_radius

Radius in pixels of a dot at 100 percent.

value_domain

Length-2 numeric fixing the colour scale. NULL uses the data range. Set it when comparing two dot plots side by side.

show_grid, show_legend

Toggle the gridlines and the legends.

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

Dot area, not radius, is proportional to the percentage. Scaling radius linearly would quadruple the ink for a doubled percentage, which is the classic way a dot plot overstates its strongest cells.

Rows and columns are drawn in the order given. Sorting genes by the group they best mark is an analysis decision, so the component does not do it.

Examples

df <- expand.grid(gene = c("CD3D", "MS4A1"), cluster = c("T", "B"),
                  stringsAsFactors = FALSE)
df$pct <- c(88, 4, 6, 91)
df$value <- c(2.4, 0.1, 0.2, 2.7)
dotplot(df)