This function models the downstream secondary effects of an in-silico perturbation by propagating the initial expression changes through a gene-gene co-expression or regulatory network.

Usage

ApplyPropagation(
  seurat_obj,
  exp,
  exp_per,
  network,
  perturb_dir,
  n_iters = 3,
  delta_scale = 0.2,
  row_normalize = FALSE,
  apply_ceiling = FALSE,
  ceiling_multiplier = 1,
  prune_network = FALSE,
  prune_percentile = 0.95
)

Arguments

seurat_obj

A Seurat object containing the dataset.

exp

A features-by-cells matrix containing the baseline (unperturbed) observed expression data.

exp_per

A features-by-cells matrix containing the initial perturbation results (e.g., output from ApplyPerturbation).

network

A gene-by-gene matrix representing the network structure (e.g., a Topological Overlap Matrix or gene regulatory network) used to route the signal.

perturb_dir

Numeric. The direction and magnitude of the original perturbation, used to extract the sign for propagation scaling.

n_iters

Numeric/Integer. The number of iterative steps to apply the signal propagation. Default is 3.

delta_scale

Numeric. A penalization/dampening factor applied to the delta matrix at each iteration to prevent biologically unrealistic exponential explosions in expression values. Default is 0.2.

row_normalize

Logical. If TRUE, normalizes the network such that each row sums to 1. This converts the matrix multiplication from a cumulative sum into a weighted average, helping to prevent signal explosion in highly connected background genes. Default is FALSE.

apply_ceiling

Logical. If TRUE, constrains the maximum propagated expression for each gene so it does not exceed its maximum observed value in the baseline data (adjusted by the ceiling_multiplier). Default is FALSE.

ceiling_multiplier

Numeric. A scaling factor applied to the expression ceiling if apply_ceiling = TRUE. For example, 1.10 allows simulated expression to reach 10\

prune_networkLogical. If TRUE, removes weak background edges from the network prior to propagation based on a calculated percentile threshold. Highly recommended for dense networks like WGCNA TOMs. Default is FALSE.

prune_percentileNumeric. The percentile threshold (between 0 and 1) used to prune the network if prune_network = TRUE. For example, 0.95 drops the weakest 95\ A matrix (or dgCMatrix) containing the fully updated expression matrix representing the global cell state after the perturbation signal has propagated through the network. This function models the downstream secondary effects of an in-silico perturbation by propagating the initial expression changes through a gene-gene co-expression or regulatory network. The function calculates the initial difference (delta) between the perturbed and baseline expression matrices. Over n_iters iterations, this delta is multiplied by the gene-gene network matrix via dot product. This mathematical diffusion simulates how a change in a hub gene ripples out to its connected targets.To maintain stability and biological realism, the propagated signal is penalized at each step by the delta_scale parameter. Users can further stabilize the diffusion by pruning weak network edges (prune_network), row-normalizing the network (row_normalize), and enforcing a strict biological ceiling (apply_ceiling) to prevent genes from entering biologically impossible high-expression states. Finally, total expression is strictly floored at 0 to prevent negative read counts, and the final matrix is rounded to represent valid count data.