Skip to contents

Faceted bar chart summarizing metadata distributions across patients

PlotMetaSummary.Rd

Deduplicates cell-level metadata to donor / patient level and plots a multi-panel bar chart: one column per metadata variable, one row per level of an optional row-splitting variable (e.g. Sex). Bars are stacked by fill_variable and each segment is optionally annotated with its count.

Usage

PlotMetaSummary(
  data,
  id_column = NULL,
  variables,
  fill_variable = NULL,
  row_variable = NULL,
  column_variable = NULL,
  exclude = NULL,
  percent = FALSE,
  count_unit = c("auto", "donors", "cells"),
  show_counts = TRUE,
  min_count_to_label = 1L,
  label_size = 3,
  alpha = 0.85,
  colors = NULL,
  y_label = NULL,
  output_dir = NULL,
  object_name = "",
  file_name = NULL,
  return_data = FALSE,
  return_flextable = FALSE,
  numeric_stat = c("mean_sd", "median_iqr"),
  cat_display = c("n_pct", "pct_n", "fraction", "n"),
  separate_tables = FALSE,
  stats.method = c("nonparametric", "parametric", "auto", "none"),
  pdf.width = NULL,
  pdf.height = NULL,
  timestamp = FALSE
)

Arguments

data

A Seurat object or a plain data frame.

id_column

Character. The column that uniquely identifies a donor or patient (e.g. "Donor.ID"). Set to NULL to count cells directly without deduplication.

variables

Character vector. Metadata columns to display as column facets on the x-axis (e.g. c("Braak", "APOE.Genotype", "CERAD.score")).

fill_variable

Character. Metadata column used to color-fill the stacked bars (e.g. "Dementia.AD"). When NULL, bars are shown in a single neutral color with no legend.

row_variable

Character. Metadata column used to create row facets (e.g. "Sex"). NULL = no row splitting.

column_variable

Character or NULL. Metadata column used to create column facets within each panel. When supplied, one plot is produced per entry in variables (multi-page PDF), and each plot is faceted by this variable. NULL = no column faceting (default).

exclude

Named list of values to exclude before plotting. Each name is a column name and each value is a character vector of levels to drop. Example: list(Cognitive.Status = "Reference").

percent

Logical. If TRUE, convert counts to percentages before plotting. When fill_variable is set, each bar sums to 100\ NULL, bars show the percentage of the panel total. Segment labels automatically switch to "X%" format. Default FALSE.

count_unit

One of "auto" (default), "donors", or "cells". "auto" counts donors when id_column is provided and more than one unique donor exists per group; otherwise counts cells.

show_counts

Logical. Annotate each bar segment with its count. Default TRUE.

min_count_to_label

Integer. Suppress the count label on segments with fewer than this many observations. Default 1.

label_size

Numeric. Text size for count labels (passed to geom_text). Default 3.

alpha

Numeric. Fill transparency for bars (0-1). Default 0.85.

colors

Named character vector of colors for fill_variable levels. NULL auto-resolves from PrepObject (if a Seurat object is passed) or SelectColors().

y_label

Character or NULL. Override the y-axis label. NULL derives it from count_unit.

output_dir

Character or NULL. Directory to save a PDF. NULL returns the plot without saving; for a Seurat object it first walks up to the output_dir stored by PrepObject (unless AutoSavePlots = FALSE).

object_name

Character. Prefix for the auto-generated file name. Falls back to the object_name stored by PrepObject.

file_name

Character or NULL. Base name (no extension) for the saved PDF. NULL (default) auto-deduces from object_name, fill_variable, and variables.

return_data

Logical. Also return the deduplicated donor-level data frame. Default FALSE.

return_flextable

Logical. Also return a list of formatted flextable objects: $donor_table (wide donor-level data), $crosstab (n per category level per fill_variable group), and $numeric_table (mean ± SD per numeric variable per fill_variable group, with each donor weighted equally). Requires the flextable package. Default FALSE.

stats.method

Character. Statistical test to add as a p.value column in the flextable outputs (requires return_flextable = TRUE and fill_variable).

"nonparametric" (default)

Fisher's exact for categorical, Wilcoxon / Kruskal-Wallis for numeric.

"parametric"

Chi-squared for categorical, t-test / ANOVA for numeric.

"auto"

Parametric when Shapiro-Wilk passes (numeric) or expected counts >= 5 (categorical); otherwise non-parametric.

"none"

No statistics added.

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

When only the plot is requested (default), a ggplot2 object. When return_data or return_flextable are TRUE, a named list with elements $plot, optionally $data, and optionally $flextable.

Examples

if (FALSE) { # \dontrun{
# Basic usage
PlotMetaSummary(SeuratObj,
  id_column     = "Donor.ID",
  variables     = c("Braak", "APOE.Genotype", "CERAD.score"),
  fill_variable = "Dementia.AD",
  row_variable  = "Sex",
  exclude       = list(Cognitive.Status = "Reference"))

# Also return the donor table and a cross-tab flextable
out <- PlotMetaSummary(SeuratObj,
  id_column        = "Donor.ID",
  variables        = c("Braak", "CERAD.score"),
  fill_variable    = "Dementia.AD",
  return_data      = TRUE,
  return_flextable = TRUE)
out$plot
out$data
out$flextable$crosstab
} # }