% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_node_influence.R
\name{get_node_influence}
\alias{get_node_influence}
\title{Propagate a virtual perturbation from source node(s) across the network}
\usage{
get_node_influence(
  graph_obj,
  source,
  delta = 1,
  alpha = 0.5,
  signed = TRUE,
  drop_source = TRUE
)
}
\arguments{
\item{graph_obj}{A `tbl_graph` from any `build_graph_from_*()`
constructor.}

\item{source}{Character vector of node `name`s to perturb.}

\item{delta}{Numeric (default `1`). Magnitude of the injected
perturbation placed on each source node.}

\item{alpha}{Numeric in `(0, 1)` (default `0.5`). Diffusion decay; the
function automatically caps it just below `1 / spectral-radius(W)` so
the series converges.}

\item{signed}{Logical (default `TRUE`). Use the signed `correlation`
edge attribute (so anticorrelated neighbours receive negative
influence). `FALSE` uses `|weight|` only.}

\item{drop_source}{Logical (default `TRUE`). Zero out the source
node(s)' own influence in the returned column so the ranking reflects
downstream spread only.}
}
\value{
The input `tbl_graph` with one new node column, `Influence`
  (signed when `signed = TRUE`). Larger magnitude = more strongly
  affected. Map it straight onto a figure with
  `ggNetView(..., fill.by = "Influence")`.
}
\description{
Injects a virtual perturbation at one or more `source` nodes and lets
it spread along the (optionally signed) weighted edges, returning how
strongly every other node is affected. This is the abundance-influence
("type 2") virtual-perturbation analysis: it treats edge weights as
interaction strengths and asks "if I nudge species A, how far and how
strongly does the ripple reach?".
}
\details{
Propagation uses a Katz / random-walk-with-restart diffusion,
\eqn{influence = (I - \alpha W)^{-1} s}, where `W` is the
column-normalised (signed) adjacency, `s` places `delta` on the source
node(s), and `alpha` is the decay. This always converges (`alpha` is
capped below the inverse spectral radius) and is well-defined even on
disconnected graphs.
}
\section{Important interpretation note}{

Correlation / co-occurrence networks encode **association, not
causation**, and give no edge direction. The score returned here is a
*structural influence estimate* -- a weighted measure of how reachable
each node is from the source -- and should be read as a qualitative
ranking, **not** as a quantitative ecological-dynamics prediction. For
a perturbation read with a (still approximate) mechanistic flavour, see
[press_perturbation()].
}

\examples{
\donttest{
data(ppi_example)
obj <- build_graph_from_df(
  df              = ppi_example$ppi,
  node_annotation = ppi_example$annotation
)
src <- get_graph_nodes(obj)$name[1]
obj2 <- get_node_influence(obj, source = src)
obj2 \%>\%
  tidygraph::activate(nodes) \%>\%
  tidygraph::as_tibble() \%>\%
  dplyr::arrange(dplyr::desc(abs(Influence))) \%>\%
  utils::head(5)
}
}
\seealso{
[get_network_perturbation()] for structural attacks;
  [press_perturbation()] for the press-perturbation approximation.
}
