Skip to contents

Compute pseudobulk (donor-level mean) expression

ComputePseudobulk.Rd

Aggregates cell-level log-normalized expression to the level of unique combinations of metadata columns (e.g. donor, or donor x cell type). The result is stored in seurat_object@misc$pseudobulk under a key derived from the sorted group.by columns so that PlotPseudoBulk can retrieve it instantly on subsequent calls.

Usage

ComputePseudobulk(
  seurat_object,
  group.by,
  genes = "variable",
  assay = "RNA",
  layer = "data",
  min_cells = 0L,
  force = FALSE,
  caffeinate = FALSE,
  verbose = TRUE
)

Arguments

seurat_object

A Seurat object.

group.by

Character vector. Metadata columns that together define one pseudobulk sample. For donor-level plots pass c("Donor.ID"). For donor x cell-type plots pass c("Donor.ID", "CellType").

genes

One of:

"variable" (default)

Use the variable features stored by FindVariableFeatures().

NULL

All genes in the assay (can be slow).

Character vector

Specific gene names.

assay

Character. Seurat assay. Default "RNA".

layer

Character. Assay layer / slot. Default "data" (log-normalized).

min_cells

Integer. Drop pseudobulk groups with fewer than this many cells. Default 0L (keep all groups).

force

Logical. When TRUE, discard the existing cache for this group.by key and recompute from scratch. Use when you see the "cache may be stale" warning. Default FALSE.

caffeinate

Logical. When TRUE, calls .nk_caffeinate() to prevent the system from sleeping during the computation. Useful for large BPCells datasets that take many minutes to aggregate. Default FALSE.

verbose

Logical. Print progress messages. Default TRUE.

Value

The seurat_object with the pseudobulk data frame stored in seurat_object@misc$pseudobulk[[cache_key]]. The data frame has one row per unique group combination and columns: group.by columns, n_cells, then one column per gene.

Details

Aggregation uses a single sparse matrix multiplication (genes x cells . cells x groups), making it efficient for BPCells / on-disk assays: the matrix is streamed through once.

When called again with the same group.by but different (or additional) genes, only the newly requested genes are computed and appended to the existing cache - already-cached genes are never recomputed.

Examples

if (FALSE) { # \dontrun{
# Per-donor pseudobulk (variable genes)
SeuratObj <- ComputePseudobulk(SeuratObj,
  group.by = "Donor.ID")

# Per-donor x per-cell-type (specific genes)
SeuratObj <- ComputePseudobulk(SeuratObj,
  group.by = c("Donor.ID", "CellType"),
  genes    = c("STAT3", "APOE", "CD3E"))
} # }