Propagate In-Silico Perturbation Signal Through a Gene Network

Propagates a log-space perturbation delta through a gene-gene co-expression or regulatory network without count-space floor constraints, ensuring symmetric behavior between up- and down-regulation perturbations.

Usage

ApplyPropagation(
  log_obs_mod,
  delta_log,
  network,
  n_iters = 3,
  delta_scale = 0.2,
  row_normalize = FALSE,
  prune_network = FALSE,
  prune_percentile = 0.95
)

Arguments

log_obs_mod: A genes-by-cells log-normalized expression matrix for the module (or network) genes at baseline. Typically a row subset of the full log-normalized observed expression matrix.
delta_log: A genes-by-cells log-space delta matrix for the same genes. Only the directly-perturbed (hub) gene rows are non-zero at input; the propagation step fills in downstream gene rows.
network: A gene-by-gene matrix (e.g., TOM or regulatory adjacency) defining how signal routes between genes.
n_iters: Number of iterative propagation steps. Default is 3.
delta_scale: Dampening factor applied at each iteration to prevent signal explosion. Default is 0.2.
row_normalize: Logical. If TRUE, each row of the network is scaled to sum to 1 before propagation (weighted-average diffusion rather than summation). Default is FALSE.
prune_network: Logical. If TRUE, zero out edges below the prune_percentile threshold before propagation. Default is FALSE.
prune_percentile: Numeric in $(0,1)$. Percentile threshold for edge pruning when prune_network = TRUE. Default is 0.95.

Value

A genes-by-cells matrix of log-normalized simulated expression for the module genes.

Details

This function propagates perturbation signal in log-normalized expression space, treating the directly-perturbed (hub) genes as a persistent signal source rather than a one-time impulse. This models a constitutive perturbation (e.g. a stable CRISPR KO/OE or a sustained stimulus), in which the hub genes are held at their new expression level indefinitely while downstream genes respond iteratively. Hub genes are identified as the rows of delta_log that are non-zero at input.

At each iteration the delta matrix is multiplied by the network and damped, then hub gene rows are reset to their initial value: $$\delta^{(t)} = W \cdot \delta^{(t-1)} \times \texttt{delta\_scale}, \quad \text{then} \quad \delta^{(t)}_{\mathcal{H}} \leftarrow \delta^{(0)}_{\mathcal{H}}$$ where $W$ is the (optionally row-normalized) network matrix and $\mathcal{H}$ is the set of hub gene rows. Without this reset, hub genes would be overwritten by the network multiplication like any other gene, and their signal would weaken with each iteration rather than persist. The intermediate log-simulated expression for the module genes is $$\texttt{log\_sim} = \texttt{log\_obs\_mod} + \delta^{(n\_iters)}$$ and the result is floored at zero before returning, since log-normalized expression cannot be negative.

Signal amplification warning: when row_normalize = FALSE (default), the per-iteration effective multiplier for the non-hub (downstream) genes is $\bar{r} \times \texttt{delta\_scale}$, where $\bar{r}$ is the mean row sum of the network restricted to non-hub rows. If this product exceeds 1 the downstream signal amplifies rather than dampens across iterations, which can produce very large deltas that are subsequently clipped by the floor. A warning is issued when this condition holds so that the user can consider reducing delta\_scale or enabling row\_normalize = TRUE. Hub rows are excluded from this check because they are pinned every iteration and cannot amplify.