Combine perturbation assays created by the mixed-layer workflow

Experimental replacement for CombinePerturbAssays(). This function is designed for perturbation assays in which direct targets (hub genes or user-selected genes) are changed in the counts layer and secondary genes are changed by network propagation in the log-normalized data layer.

Usage

CombinePerturbAssays(
  seurat_obj,
  perturb_assays,
  baseline_assay = "RNA",
  new_assay = paste0(paste(perturb_assays, collapse = "_"), "_combined"),
  scale.factor = 10000,
  direct_tolerance = 0,
  check_provenance = TRUE,
  require_provenance = FALSE,
  strict_provenance_check = TRUE,
  floor_counts = TRUE,
  floor_data = TRUE,
  allow_dense = FALSE,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

seurat_obj: A Seurat object containing the baseline and perturbation assays.
perturb_assays: Character vector naming the perturbation assays.
baseline_assay: Name of the assay from which the perturbations were generated. Default is "RNA".
new_assay: Name for the combined assay.
scale.factor: Scale factor used by the perturbation workflow's log-normalization. Default is 1e4.
direct_tolerance: Non-negative numeric tolerance used to infer direct genes from count-space deltas. A gene is direct for an assay when any cell has abs(perturbed_count - baseline_count) > direct_tolerance.
check_provenance: Logical; inspect assay@misc$COMPACT metadata written by StampPerturbProvenance() and verify that every available stamp names baseline_assay and includes the "counts" layer. Missing stamps warn but do not stop unless require_provenance = TRUE. Default is TRUE.
require_provenance: Logical; require complete provenance metadata for every perturbation assay. Default is FALSE, allowing older or unstamped assays to be combined after a warning.
strict_provenance_check: Logical; stop when an available provenance stamp conflicts with baseline_assay or does not include "counts". If FALSE, issue a warning and continue. Default is TRUE.
floor_counts: Logical; floor negative combined counts at zero. This can be needed when several knock-down deltas affect the same gene. Default is TRUE.
floor_data: Logical; floor negative combined log-expression at zero, matching ApplyPropagation(). Default is TRUE.
allow_dense: Logical; permit dense input matrices. Default is FALSE to protect against accidental memory expansion.
overwrite: Logical; replace an existing assay named new_assay. Default is FALSE.
verbose: Logical; emit progress messages.

Value

The Seurat object with the new combined assay.

Details

Direct and propagated effects are deliberately combined differently:

Count-space deltas are added to the baseline counts.
The combined counts are log-normalized with the baseline library sizes, reproducing the primary/direct component in data space.
For each input assay, its data-space delta is added only for genes that were not directly changed in that assay. These are the secondary effects produced by propagation.

In symbols, for input assay $i$, baseline counts $B$, reconstructed baseline log-expression $L$, perturbed counts $P_i$, perturbed data $D_i$, and direct-gene set $H_i$ inferred from $P_i-B$: $$C = max(0, B + sum_i(P_i-B))$$ $$E = max(0, logNorm(C; colSums(B)) + sum_i 1[g not in H_i](D_i-L))$$

This component-wise exclusion is important. If a gene is a direct target in one assay but a secondary target in another, its secondary effect from the other assay is retained.

The function is intentionally kept under a new name so the existing CombinePerturbAssays() implementation remains available for comparison.

Examples

if (FALSE) { # \dontrun{
object <- CombinePerturbAssays(
  object,
  perturb_assays = c("M6_up", "M2_down"),
  baseline_assay = "RNA",
  new_assay = "M6up_M2down_"
)
} # }