Calculate timecourse spillover across multiple networks

This function iteratively computes gene-level spillover across a series of networks (e.g., WGCNA results or TOM/adjacency matrices), using a propagation model. Spillover can begin from a shared initiator list or from timepoint-specific gene sets and optionally incorporate gene-level effects such as fold changes or module membership. Propagation can be binary or continuous, and supports persistent initiators and feedback from previous spillover states. The function also supports optional pruning of dense networks using a similarity threshold or top-k strongest connections per row.

Usage

spillover_timecourse(
  network_list,
  initiator_genes,
  gene_effects = NULL,
  alpha = 1,
  row_normalize = TRUE,
  binary = FALSE,
  threshold_spillover = FALSE,
  threshold = NULL,
  calc_threshold = FALSE,
  quantile = 0.95,
  persistent_initiators = FALSE,
  use_previous_spillover = FALSE,
  prune = FALSE,
  prune_args = list(auto = FALSE, target_sparsity = 0.05),
  verbose = TRUE
)

Arguments

network_list

A named list of networks (matrices or WGCNA result objects), one per timepoint (T2 to Tn).

initiator_genes

Either a character vector of shared initiators or a list of vectors, one per timepoint (T1 to Tn-1).

gene_effects

Optional: either a named numeric vector of gene effects (e.g., logFCs) or a list of such vectors per timepoint. If not provided, defaults to 1 for initiators and 0 otherwise.

alpha

Numeric. Damping parameter controlling signal retention (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).

binary

Logical. If TRUE, converts output at each timepoint to binary using a threshold (default = TRUE).

threshold_spillover

Logical. If TRUE only spillove values above threshold will be retained (defualt = FALSE).

threshold

Numeric. Used if `binary = TRUE` or `threshold_spillover = TRUE` to define the activation cutoff (default = 0).

calc_threshold

Logical. If TRUE, uses spillover_threshold_from_degree to calculate a topology informed threshold for significant spillover.

quantile

Numeric. Value between 0 and 1 (default = 0.95). The spilllover threshold is set at this quantile of the expected background distribution.

persistent_initiators

Logical. If TRUE, initiators accumulate over time and remain active after first activation (default = FALSE).

use_previous_spillover

Logical. If TRUE, uses spillover output from the previous timepoint as the gene effects at the next timepoint (default = FALSE).

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 `method`, `value`, `auto`, and `target_sparsity`.

verbose

Logical. If TRUE, prints diagnostic and progress messages (default = TRUE).

#' @details **Overview and Interpretation**

This function generalizes the single-step spillover propagation to an entire *timecourse* of network states, allowing users to track how influence from an initial set of genes evolves across multiple biological snapshots (e.g., timepoints, conditions).

For each timepoint, spillover is calculated using the following damped propagation model:

$$ \text{spillover}_{t} = \alpha \cdot W_{t} \cdot \text{effects}_{t} + (1 - \alpha) \cdot \text{effects}_{t} $$

where: - \(W_{t}\) is the network matrix at timepoint \(t\), optionally pruned and row-normalized, - \(\text{effects}_{t}\) is a gene-level effect vector derived from initiators or the previous spillover state, - \(\alpha\) controls how much signal propagates vs. remains locally conserved.

**Options and Flexibility**

- **Initiator Genes**: The function supports either a single set of initiators or a list for per-timepoint variation. - **Persistent Initiators**: If enabled, genes that were active in any prior step remain active in subsequent ones. - **Previous Spillover as Input**: Allows dynamic feedback, where the spillover at \(t-1\) seeds the effects at \(t\). - **Thresholding**: Optional filtering of weak spillover using either a fixed numeric cutoff or a topology-aware quantile threshold from `spillover_threshold_from_degree()`. - **Binary Conversion**: If enabled, spillover values are binarized (1/0) to reflect activation status, useful for logic-based modeling or visualization. - **Pruning**: Supports automatic or manual reduction of network density to enhance signal-to-noise and speed.

**Interpretation Guidance**

- Raw spillover scores reflect the accumulated influence of initiators on each gene at each timepoint. - These scores can be used to identify genes that consistently accumulate signal, detect pathway shifts, or correlate with phenotypic changes. - Thresholding or binarization is helpful when inferring discrete activation or tracing modules step-by-step. - Use `spillover_threshold_from_degree()` for principled cutoffs based on network structure, especially in row-normalized matrices.

This function is particularly well-suited for longitudinal studies (e.g., developmental timecourses, intervention responses), where spillover-based diffusion reveals shifting patterns of gene influence across the network's evolving topology.

Value

A named list of spillover vectors (named numeric vectors) for each timepoint in the input list.

See also

calculate_spillover, prune_matrix