This function estimates spillover effects from a set of initiator genes (with optional initial effects) using a transition matrix derived from a TOM matrix, adjacency matrix, or WGCNA object. Optionally, the network matrix can be pruned to remove weak or noisy connections using either a threshold or top-k filtering strategy.
Usage
calculate_spillover(
network,
initiator_genes,
gene_effects = NULL,
alpha = 1,
row_normalize = FALSE,
prune = FALSE,
prune_args = list(value = NULL, auto = TRUE, target_sparsity = 0.05)
)Arguments
- network
An adjacency matrix, TOM matrix, or a WGCNA result object (list with `TOM`, `adjacency`, or `datExpr`).
- initiator_genes
A vector of gene names to initialize spillover from. Can represent hub genes, biomarkers, etc.
- gene_effects
Optional named numeric vector with effect sizes (e.g., logFC or median shift) for initiators. Default = 1.
- alpha
Damping parameter controlling conservation of original signal (default = 1). Set between 0 (no propagation) and 1 (full propagation).
- row_normalize
Logical. Whether to row-wise normalize the matrix before computing spillover values. (default = TRUE).
- prune
Logical. Whether to prune the network matrix before computing spillover (default = FALSE).
- prune_args
A named list of arguments passed to `prune_matrix()`, such as `value`, `auto`, and `target_sparsity`.
#' @details **Spillover Calculation and Interpretation**
This function estimates gene-level *spillover*, representing the indirect influence of upstream initiator genes as propagated through a gene similarity network (e.g., adjacency or TOM matrix). The propagation follows a dampened diffusion model:
$$ \text{spillover} = \alpha \cdot W \cdot \text{initial\_effects} + (1 - \alpha) \cdot \text{initial\_effects} $$
where: - \(W\) is the (optionally normalized) similarity or transition matrix, - \(\text{initial\_effects}\) is a vector of user-specified gene-level initiator values (default = 1), - \(\alpha\) is a damping parameter that controls how much signal is allowed to propagate versus being retained.
The output is a named numeric vector of spillover scores for each gene, reflecting the degree to which each gene was influenced by the initiators, either directly (if it is an initiator itself) or indirectly through connected neighbors in the network.
- Higher spillover values indicate greater expected influence from initiator genes. - When `row_normalize = TRUE`, each row of the matrix \(W\) is scaled to sum to 1, making the spillover interpretable as a probabilistic distribution of influence across neighbors. - When `alpha = 1`, only indirect signal is retained; lower alpha retains more direct signal.
**Interpretation Notes:** - If pruning is enabled, weak connections are removed before computing spillover. This can sharpen signal and improve interpretability but may reduce sensitivity to diffuse propagation. - Raw spillover values are continuous, but follow-up steps can apply thresholds or binarization to select genes with biologically meaningful levels of inferred influence.
This function serves as the core engine for timecourse analyses (see `spillover_timecourse()`) and downstream integration with expression and phenotype data.
See also
prune_matrix for preprocessing options to filter weak edges before spillover.
Examples
if (FALSE) { # \dontrun{
spillover <- calculate_spillover(
network = tom_matrix,
initiator_genes = hub_genes,
alpha = 0.85,
prune = TRUE,
prune_args = list(method = "threshold", auto = TRUE, target_sparsity = 0.05)
)
} # }