scatterEnrichment: Plot 2D Enrichment Distributions With Density or Hexplots

View source: R/scatterEnrichment.R

scatterEnrichmentR Documentation

Plot 2D Enrichment Distributions With Density or Hexplots

Description

Visualize the relationship between *two* enrichment scores at single-cell resolution. By default points are shaded by local 2-D density ('color.by = "density"'), but users can instead color by a metadata column (discrete) or by the raw gene-set scores themselves (continuous).

Usage

scatterEnrichment(
  input.data,
  assay = NULL,
  x.axis,
  y.axis,
  facet.by = NULL,
  group.by = NULL,
  color.by = c("density", "group", "x", "y"),
  style = c("point", "hex"),
  scale = FALSE,
  bins = 40,
  point.size = 1.2,
  alpha = 0.8,
  palette = "inferno",
  add.corr = FALSE
)

Arguments

input.data

Output of escape.matrix or a single‑cell object previously processed by runEscape.

assay

Name of the assay holding enrichment scores when 'input.data' is a single‑cell object. Ignored otherwise.

x.axis, y.axis

Gene-set names to plot on the *x* and *y* axes.

facet.by

Optional metadata column used to facet the plot.

group.by

Metadata column plotted. Defaults to the Seurat/SCE 'ident' slot when 'NULL'.

color.by

Aesthetic mapped to point color. Use '"density"' (default), '"group"', '"x"', or '"y"'. The latter two apply a continuous gradient to the corresponding axis.

style

'"point"' (density-aware points) or '"hex"' (hex-bin).

scale

Logical; if 'TRUE' scores are centered/scaled (Z‑score) prior to plotting.

bins

Number of hex bins along each axis when 'style = "hex"'.

point.size, alpha

Aesthetic tweaks for 'style = "point"'.

palette

Character. Any palette from hcl.pals.

add.corr

Logical. Add Pearson and Spearman correlation coefficients (top-left corner of the first facet).

Value

A ggplot2 object.

Examples

gs <- list(
  Bcells = c("MS4A1","CD79B","CD79A","IGH1","IGH2"),
  Tcells = c("CD3E","CD3D","CD3G","CD7","CD8A")
)
pbmc <- SeuratObject::pbmc_small |>
  runEscape(gene.sets = gs, min.size = NULL)

scatterEnrichment(
  pbmc,
  assay     = "escape",
  x.axis    = "Tcells",
  y.axis    = "Bcells",
  color.by  = "group",        
  group.by  = "groups",
  add.corr  = TRUE,
  point.size = 1
)


ncborcherding/escape documentation built on June 12, 2025, 1 p.m.