Skip to contents

Upstream Regulator Analysis via decoupleR + CollecTRI

RunURA.Rd

Infers transcription factor activity from pseudobulk gene expression using decoupleR and the CollecTRI TF-target database. Optionally tests for differential TF activity between one or more condition pairs (limma when \(\geq 3\) donors per side; t-test otherwise).

Usage

RunURA(
  seurat_object,
  group.by = NULL,
  donor.by = NULL,
  split.by = NULL,
  contrast.by = NULL,
  contrast = NULL,
  group.levels = NULL,
  assay = "RNA",
  layer = "data",
  use_pseudobulk = TRUE,
  force = FALSE,
  network = NULL,
  method = "ulm",
  organism = "human",
  n_top = 25L,
  min_cells = 10L,
  output_dir = NULL,
  object_name = "",
  subset_name = "",
  plot = TRUE,
  caffeinate = FALSE,
  max_cells = NULL
)

Arguments

seurat_object

A Seurat object.

group.by

Character or NULL. Metadata column that defines the primary grouping (e.g. "CellType", "Cluster"). NULL treats all cells as one group.

donor.by

Character or NULL. Replicates column (e.g. "Donor.ID"). Enables limma-based differential testing when \(\geq 3\) donors per contrast arm. NULL falls back to t-test.

split.by

Character or NULL. Additional stratification column (e.g. "Sex"). Included in the pseudobulk grouping, generates group × split columns in the activity matrix, and facets the bubble plot.

contrast.by

Character or NULL. Condition column for DE (e.g. "Diagnosis").

contrast

A single c("test", "ref") pair or a list of such pairs, e.g. list(c("AD","Control"), c("MCI","Control")). Required when contrast.by is set.

group.levels

Character vector or NULL. Restrict to specific levels of group.by. NULL = all levels.

assay

Character. Seurat assay. Default "RNA".

layer

Character. Assay layer. Default "data".

use_pseudobulk

Logical. When TRUE (default) TF activity is inferred from pseudobulk expression averages — statistically rigorous for DE testing. When FALSE, decoupleR runs directly on the full single-cell matrix (all cells × genes) and activity scores are then averaged per group; simpler, works without donor.by, but pseudoreplication means DE results should be interpreted with caution.

force

Logical. When TRUE, recomputes pseudobulk even if a cached result is already stored in seurat_object@misc$pseudobulk. Default FALSE.

network

A data.frame with columns source, target, mor. Fetched from CollecTRI when NULL.

method

One of "ulm" (default), "viper", "mlm".

organism

"human" (default) or "mouse".

n_top

Top N TFs to include in plots. Default 25L.

min_cells

Minimum cells per pseudobulk group. Default 10L.

output_dir

Directory for PDFs. NULL = no files saved.

object_name

Character. Label prefix for output file names.

subset_name

Character. Optional subset label appended to output file names.

plot

Logical. Save plots. Default TRUE.

caffeinate

Logical. Prevent the machine from sleeping during the run (macOS only; uses caffeinate -i). Default FALSE.

max_cells

Integer or NULL. When use_pseudobulk = FALSE and the object has more cells than this value, a stratified random sample of max_cells cells is drawn before running decoupleR. Preserves group proportions. NULL (default) uses all cells.

Value

Invisibly, a list:

activity

TF × group mean-activity matrix.

scores

Long-format decoupleR output (all pseudobulk samples).

de

Differential table, or NULL. Columns: TF, cell_type, split_level, mean_a, mean_b, activity_diff, t, p.value, p.adj, contrast.

network

TF-target network used.