Skip to contents

Batch single-cell feature plots with shared color limits

PlotFeaturePlots.Rd

Loops over features, generates a Seurat::FeaturePlot() split by split.by, applies a shared per-gene color gradient (0 → max expression), strips legends from individual panels, and attaches a single shared legend.

Usage

PlotFeaturePlots(
  seurat_object,
  assay = "RNA",
  reduction = "umap",
  features,
  layout_method = "auto",
  split.by = NULL,
  row.by = NULL,
  colors = c("#053061", "#2166AC", "#D1E5F0", "#FDDBC7", "#F4A582", "#D6604D", "#B2182B",
    "#67001F"),
  legend.side = "right",
  legend.direction = "vertical",
  join_plots = FALSE,
  join_nrow = NULL,
  join_ncol = NULL,
  output_dir = NULL,
  object_name = "",
  subset_name = "",
  order = TRUE,
  label = FALSE,
  label.by = NULL,
  label_colors = NULL,
  repel = FALSE,
  label.size = 2,
  pt.size = 0.001,
  add_boxplot = FALSE,
  plot_type = "violin",
  alpha = 0.7,
  ref_group = NULL,
  comparisons = NULL,
  group_colors = NULL,
  label_format = "p.signif",
  hide_ns = FALSE,
  file_name = NULL,
  width = NULL,
  height = NULL,
  timestamp = FALSE
)

GenerateFeatureMaps(
  seurat_object,
  assay = "RNA",
  reduction = "umap",
  features,
  layout_method = "auto",
  split.by = NULL,
  row.by = NULL,
  colors = c("#053061", "#2166AC", "#D1E5F0", "#FDDBC7", "#F4A582", "#D6604D", "#B2182B",
    "#67001F"),
  legend.side = "right",
  legend.direction = "vertical",
  join_plots = FALSE,
  join_nrow = NULL,
  join_ncol = NULL,
  output_dir = NULL,
  object_name = "",
  subset_name = "",
  order = TRUE,
  label = FALSE,
  label.by = NULL,
  label_colors = NULL,
  repel = FALSE,
  label.size = 2,
  pt.size = 0.001,
  add_boxplot = FALSE,
  plot_type = "violin",
  alpha = 0.7,
  ref_group = NULL,
  comparisons = NULL,
  group_colors = NULL,
  label_format = "p.signif",
  hide_ns = FALSE,
  file_name = NULL,
  width = NULL,
  height = NULL,
  timestamp = FALSE
)

Arguments

seurat_object

A Seurat object.

assay

Character. assay to use for expression values. Default "RNA".

reduction

Character. Dimensional reduction for the UMAP. Default "umap".

features

Character vector of gene names to plot.

layout_method

Character. "auto" (default) or "metadata". In "metadata" mode row.by must be specified.

split.by

Character. Metadata column to split UMAP panels by.

row.by

Character or NULL. In "metadata" layout, the metadata column whose levels define the rows of the grid.

colors

Character vector. Color gradient from low to high expression.

legend.side

Character. Where to place the legend panel: "right" (default), "left", "bottom", or "top".

legend.direction

Character. Internal layout of legend entries: "vertical" (default, entries stacked) or "horizontal" (entries in rows). Also controls colorbar orientation.

join_plots

Logical. When features has more than one gene, combine all per-gene figures into a single page/PDF instead of one each. Default FALSE.

join_nrow, join_ncol

Integer or NULL. Grid layout for join_plots. NULL auto-arranges into a near-square grid.

output_dir

Character or NULL. Directory to write PDFs. If NULL, the plot is returned instead of saved.

object_name

Character. Label appended to PDF filenames. Default "".

subset_name

Character. Second label appended to PDF filenames. Default "".

order

Logical. Plot higher-expression cells on top. Default TRUE.

label

Logical. Overlay cell-type / cluster labels on UMAP panels. Default FALSE.

label.by

Character. Metadata column to use for labels. If NULL (default) and label = TRUE, labels are drawn using Seurat::Idents(). Accepts any metadata column - avoids Seurat's ident-order problem and the error that occurs when a column is literally named "idents".

label_colors

Named character vector mapping each label value to a hex color (e.g. c("Excitatory" = "#E41A1C", "Inhibitory" = "#377EB8")). Labels not present in the vector default to "black". NULL = all black.

repel

Logical. Use ggrepel::geom_text_repel to avoid overlapping labels (default FALSE). If repel fails due to output-size constraints a message is printed and the panel is skipped rather than crashing.

label.size

Numeric. Label font size. Default 2.

pt.size

Numeric. Point size. Default 0.001.

add_boxplot

Logical. Append an expression violin/box plot column. Default FALSE. Requires split.by to be set.

plot_type

Character. Type of expression plot: "violin" (default), "box", or "both" (violin with a thin white box overlay).

alpha

Numeric. Fill transparency for violin and box geoms. Default 0.7.

ref_group

Character or NULL. If set, each group is compared only to this reference level. NULL (default) performs all pairwise tests.

comparisons

List of character vectors or NULL. Custom pairs to test, e.g. list(c("NCI","AD"), c("MCI","AD")). Overrides ref_group.

group_colors

Named character vector or NULL. Fill colors for each split.by level. NULL auto-assigns from Nour18.

label_format

Character. "p.signif" (default, shows */**/ns) or "p.format" (shows p = 0.023).

hide_ns

Logical. If TRUE, omit ns brackets entirely. Default FALSE (shows ns in gray).

file_name

Character or NULL. Base name (no extension) for the saved PDF. NULL (default) auto-deduces from object_name, subset_name, the gene, split.by, and row.by.

width, height

Numeric or NULL. Override the auto-calculated PDF dimensions in inches. NULL (default) auto-sizes to fit the panel grid.

timestamp

Logical. When TRUE, append a _YYYYMMDD-HHMMSS stamp to the saved file name so repeated runs are versioned instead of overwriting the previous PDF. Default FALSE.

Value

Invisibly returns the last assembled plot when output_dir = NULL; otherwise writes PDFs and returns NULL invisibly. When join_plots = TRUE, invisibly returns the combined tiled figure.

Details

When add_boxplot = TRUE a violin/box plot column is appended to the right of the UMAP grid. In "metadata" layout each row gets its own boxplot (cells from that row.by level only); in "auto" layout a single boxplot covers all cells. Pairwise Wilcoxon tests are computed with BH correction and displayed as brackets: significant comparisons in black, ns in gray.

When output_dir is provided the figure is saved as a PDF and nothing is returned. When output_dir = NULL the assembled plot is returned invisibly.

Functions

  • GenerateFeatureMaps(): Long-form alias.