Skip to contents

CombinePerturbAssays: create a composite perturb assay by delta superposition (sparse-safe; COUNTS-only)

CombinePerturbAssays.Rd

This function combines multiple perturbation assays into a single composite assay using additive superposition of perturbation deltas relative to a shared baseline on the counts layer: $$P_{\mathrm{combined}} = B + \sum_i (P_i - B)$$

Usage

CombinePerturbAssays(
  seurat_obj,
  perturb_assays,
  baseline_assay = "RNA",
  new_assay = paste(perturb_assays, collapse = "_"),
  require_provenance = FALSE,
  strict_provenance_check = TRUE,
  run_consistency_check_if_missing = TRUE,
  strict_consistency_check = FALSE,
  eps = 0.001,
  max_frac_changed = 0.35,
  max_abs_median = 0.05,
  max_abs_mean = 0.05,
  allow_unverified = TRUE,
  allow_dense = FALSE,
  normalize_method = "LogNormalize",
  scale.factor = 10000,
  verbose = TRUE
)

Arguments

seurat_obj

A Seurat object containing baseline and perturbation assays.

perturb_assays

Character vector of perturbation assay names to combine.

baseline_assay

Character; baseline assay name (default "RNA").

new_assay

Character; name of the new composite assay.

require_provenance

Logical; if TRUE, missing provenance triggers stop/warn.

strict_provenance_check

Logical; if TRUE, stop on provenance mismatch; else warn.

run_consistency_check_if_missing

Logical; if TRUE, run heuristic checks when provenance missing.

strict_consistency_check

Logical; if TRUE, stop on suspicious heuristic results; else warn.

eps, max_frac_changed, max_abs_median, max_abs_mean

Thresholds for heuristic checks.

allow_unverified

Logical; if provenance missing and heuristic checks disabled, proceed only if TRUE.

allow_dense

Logical; if FALSE (default), stop when any requested layer returns a dense matrix (to avoid RAM blow-ups).

normalize_method

Normalization method passed to Seurat::NormalizeData() for creating the composite data layer (default "LogNormalize").

scale.factor

Scale factor passed to Seurat::NormalizeData() (default 1e4).

Value

A Seurat object with a new composite perturbation assay.

Details

Implementation note: this function avoids creating a large dense expanded matrix. It combines perturbations strictly on the baseline feature space (rows = rownames(baseline)). Features present in a perturb assay but absent from baseline are dropped with a warning.

Baseline safety logic:

  • If all input assays have provenance (via StampPerturbProvenance()), the function verifies recorded baseline_assay and baseline_layers include "counts".

  • If provenance is missing for any assay, the function emits a warning banner. Optionally, it runs heuristic numeric checks on the counts layer via .CheckPerturbBaselineConsistency() for the unstamped assays (not a proof; may be less informative than checks on normalized data).

Data layer handling: After combining counts, the function generates the composite assay's data layer by running Seurat::NormalizeData() on the new assay (e.g. LogNormalize with a configurable scale.factor).

Combine by delta-superposition (counts only):

  • comp_counts = base_counts + _i (pert_counts_i - base_counts)

Requirements:

  • baseline assay must have layer counts

  • each perturb assay must have layer counts

  • all assays must share identical cell columns

Examples

if (FALSE) { # \dontrun{
# After creating perturb assays:
seurat_obj_perturb <- ModulePerturbation(
  seurat_obj_perturb,
  mod = "CBh-M6",
  perturb_dir = 5,
  perturbation_name = "M6_up",
  graph = "RNA_nn",
  n_hubs = 10
)

seurat_obj_perturb <- ModulePerturbation(
  seurat_obj_perturb,
  mod = "CBh-M2",
  perturb_dir = -2,
  perturbation_name = "M2_down",
  graph = "RNA_nn",
  n_hubs = 10
)

# Optional: stamp provenance (recommended)
seurat_obj_perturb <- StampPerturbProvenance(
  seurat_obj_perturb,
  perturb_assay = "M6_up",
  baseline_assay = "RNA"
)

seurat_obj_perturb <- StampPerturbProvenance(
  seurat_obj_perturb,
  perturb_assay = "M2_down",
  baseline_assay = "RNA"
)

seurat_obj_perturb <- CombinePerturbAssays(
  seurat_obj_perturb,
  perturb_assays = c("M6_up", "M2_down"),
  baseline_assay = "RNA",
  new_assay = "M6up_M2down",
  require_provenance = FALSE,
  run_consistency_check_if_missing = FALSE,
  allow_unverified = TRUE
)
} # }