Summarize cell-level metadata to donor / patient level

Groups cells by one or more ID columns (e.g. donor ID, sample ID) and returns a wide data frame with one row per unique ID combination.

Usage

SummarizeMetadata(
  data,
  id_columns,
  columns = NULL,
  group.by = NULL,
  numeric_func = mean,
  numeric_na_rm = TRUE,
  spread = NULL,
  pivot = FALSE
)

Arguments

data: A Seurat object or a plain data frame / tibble.
id_columns: Character vector of one or more column names that uniquely identify a donor or sample (e.g. c("Donor.ID") or c("Donor.ID", "Visit")). One output row is produced per unique combination.
columns: Character vector of column names to include in the summary. NULL (default) includes all columns except id_columns. id_columns are always retained regardless of this setting.
group.by: Optional column name to aggregate the patient-level result up to a group level. When supplied, a two-stage aggregation is performed: (1) cells are collapsed to one row per id_columns combination (current behavior), then (2) those patient-level rows are averaged by group.by, giving each patient equal weight regardless of cell count. The returned data frame has one row per group.by level and gains an n_patients column. Default NULL (single-stage).
numeric_func: Function to summarize numeric columns. Must accept a numeric vector and return a single value. Default mean. Common alternatives: median, max, function(x) sd(x, na.rm = TRUE).
numeric_na_rm: Logical. Pass na.rm = TRUE to numeric_func. Default TRUE.
spread: Character or NULL. When "sd" or "sem", adds a companion column for each numeric variable (e.g. Age_sd or Age_sem). At the patient level these are computed across cells; when group.by is also supplied they reflect the spread of patient means across patients in each group. Default NULL (no spread).
pivot: Logical. If TRUE, the result is pivoted to long format (one row per ID × variable combination). Default FALSE (wide).

Value

A data frame (wide by default). Always includes n_cells (number of cells per ID combination).

Details

Column handling:

Numeric columns: Summarized with numeric_func (default: mean).
Categorical columns - simple: When every cell in an ID group shares the same value (e.g. every cell from donor D1 has Sex = "Male"), that single value is returned as-is.
Categorical columns - complex: When cells in an ID group have multiple values (e.g. a donor has several cell types), the result is a formatted string listing all values and their cell counts in descending order: "CD4 T (n=1 420), NK (n=380), B (n=200)".

Examples

if (FALSE) { # \dontrun{
# One ID column
donor_df <- SummarizeMetadata(SeuratObj, id_columns = "Donor.ID")

# Multiple ID columns (one row per donor × visit combination)
donor_df <- SummarizeMetadata(SeuratObj,
  id_columns   = c("Donor.ID", "Visit"),
  numeric_func = median)

# Long format for easy downstream plotting
long_df <- SummarizeMetadata(SeuratObj, id_columns = "Donor.ID", pivot = TRUE)
} # }