Skip to contents

UMAP grid with optional composition trend panel

PlotDimPlots.Rd

Produces a UMAP grid where columns correspond to split.by levels and rows (optionally) to row.by levels. No empty panels: samples missing from a row are omitted rather than shown as blank bordered boxes. The optional composition trend panel (show_trend = TRUE) is placed to the left and stacked with the same ggarrange row structure so row heights always align.

Usage

PlotDimPlots(
  seurat_object,
  group.by = NULL,
  split.by = NULL,
  row.by = NULL,
  number_labels = FALSE,
  show_trend = FALSE,
  show_labels = FALSE,
  label.by = NULL,
  colors = NULL,
  reduction = "umap",
  pt.size = 0.1,
  label.size = 3,
  bar.width = 0.6,
  legendnrow = 2,
  legend.side = "bottom",
  legend.direction = "horizontal",
  legendtitle = NA,
  trend_width = 1,
  split.col.levels = NULL,
  width = NULL,
  height = NULL,
  join_plots = FALSE,
  join_nrow = NULL,
  join_ncol = NULL,
  output_dir = NULL,
  object_name = "",
  subset_name = "",
  file_name = NULL,
  timestamp = FALSE,
  ...
)

PlotGridUMAP(
  seurat_object,
  group.by,
  split.by = NULL,
  row.by = NULL,
  colors = NULL,
  reduction = "umap",
  pt.size = 0.1,
  col.split = NULL,
  row.split = NULL
)

PlotTrendAndUMAP(
  seurat_object,
  group.by,
  split.by = NULL,
  row.by = NULL,
  colors = NULL,
  reduction = "umap",
  pt.size = 0.1,
  bar.width = 0.6,
  label.size = 3,
  legendnrow = 2,
  legendtitle = NA,
  trend_width = 1,
  legendmargin = NULL,
  plotwidths = NULL,
  split.col.levels = NULL,
  split.cols = NULL,
  split.rows = NULL
)

Arguments

seurat_object

A Seurat object.

group.by

Character. Metadata column for point color.

split.by

Character. Metadata column for columns (samples/conditions).

row.by

Character or NULL. Metadata column for rows.

number_labels

Logical. When TRUE, both the legend and (if show_labels = TRUE) the centroid labels use a zero-padded index (e.g., legend "01. CellType", centroid "01") instead of the actual group name - useful when there are many groups and alphanumeric ordering aids interpretation, or the names are too long to label directly on the plot. Default FALSE (legend and centroid labels show the real group name, unnumbered).

show_trend

Logical. Add a stacked composition trend panel to the left. Default FALSE.

show_labels

Logical. Overlay a label at each cluster's centroid - the group name by default, or a zero-padded index when number_labels = TRUE. Default FALSE.

label.by

Character or NULL. Column for label centroids. NULL → group.by.

colors

Named color vector. NULL auto-resolves from PrepObject or Nour_pal.

reduction

Character. Reduction name (case-insensitive).

pt.size

Numeric. Point size. Default 0.1.

label.size

Numeric. Label text size. Default 3.

bar.width

Numeric. Bar width in the trend plot. Default 0.6.

legendnrow

Integer or vector. Legend rows (when legend.direction = "horizontal"). When group.by has multiple variables, pass a vector positionally or named by variable. Default 2.

legend.side

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

legend.direction

Character. Internal layout of legend entries: "horizontal" (default, entries in rows) or "vertical" (entries stacked in one column).

legendtitle

Character or NA. Legend title.

trend_width

Numeric. Relative width of the trend panel vs. one UMAP column. Default 1.

split.col.levels

Character vector. Explicit ordering for split.by levels.

width

Numeric or NULL. Saved PDF width in inches. NULL (default) auto-sizes to fit the panel grid and the legend.

height

Numeric or NULL. Saved PDF height in inches. NULL (default) auto-sizes from the number of rows plus the legend strip.

join_plots

Logical. When group.by has more than one variable, combine the per-variable plots into a single figure / PDF instead of one file 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 save a PDF.

object_name

Character. Output file-name prefix.

subset_name

Character. Optional second prefix.

file_name

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

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.

...

Ignored (forward compatibility).

Value

A patchwork combined plot. With multiple group.by and join_plots = FALSE, a named list of plots (one per variable).

Functions

  • PlotGridUMAP(): Deprecated - use PlotDimPlots(show_trend=FALSE).

  • PlotTrendAndUMAP(): Deprecated - use PlotDimPlots(show_trend=TRUE).