Propagate In-Silico Perturbation Signal Through a Gene 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.

Usage

ApplyPropagation(
  seurat_obj,
  exp,
  exp_per,
  network,
  perturb_dir = perturb_dir,
  n_iters = 3,
  delta_scale = 0.2
)

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.

Value

A matrix (or dgCMatrix) containing the fully updated expression matrix representing the global cell state after the perturbation signal has propagated through the network.

Details

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, the propagated signal is penalized at each step by the delta_scale parameter, and total expression is strictly floored at 0 to prevent negative read counts. The final matrix is rounded to represent valid count data.