% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/press_perturbation.R
\name{press_perturbation}
\alias{press_perturbation}
\title{Press-perturbation (sustained-disturbance) analysis}
\usage{
press_perturbation(
  graph_obj = NULL,
  cor_mat = NULL,
  self_regulation = NULL,
  source = NULL
)
}
\arguments{
\item{graph_obj}{A `tbl_graph` from any `build_graph_from_*()`
constructor. Ignored if `cor_mat` is supplied.}

\item{cor_mat}{Optional numeric matrix. A signed correlation /
interaction matrix with matching row/col names, used directly instead
of extracting one from `graph_obj`.}

\item{self_regulation}{Numeric scalar, or `NULL` (default). The
diagonal of `A` (intraspecific density dependence; must be negative).
When `NULL`, it is set automatically to
`-(max Re eigenvalue(off-diagonal A) + 1)`, which guarantees a stable
matrix. Supply your own (e.g. `-1`) to encode a specific assumption.}

\item{source}{Optional character vector of node `name`s. When given,
`response` returns only the net effect on every node of pressing
these source node(s).}
}
\value{
A list with:
  \itemize{
    \item `net_effect`: the \eqn{N = -A^{-1}} matrix (columns = pressed
      node, rows = responding node).
    \item `stable`: logical; `TRUE` if `A` is dynamically stable.
    \item `eigen_real_max`: largest real part of `A`'s eigenvalues
      (must be `< 0` for stability).
    \item `self_regulation`: the diagonal value actually used.
    \item `response`: if `source` was given, a data frame of the net
      response of each node to pressing the source(s); else `NULL`.
  }
}
\description{
Approximates the classic ecological *press perturbation*: it treats the
signed correlation matrix as a proxy for the community (interaction)
matrix \eqn{A}, adds negative self-regulation on the diagonal, and
inverts it to obtain the net-effect matrix
\eqn{N = -A^{-1}}. Entry \eqn{N_{ij}} is the long-run net response of
node \eqn{i} when node \eqn{j} is held under sustained pressure
(continuously elevated or suppressed). This is the closest one can get
to a "type 3" dynamical perturbation from a static correlation network.
}
\section{Assumptions and honest limits}{

This is a deliberately approximate, *qualitative* method. Correlation
is **not** causation and carries no direction, so the interaction signs
and magnitudes are proxies, not measured coefficients. The framework
also requires the community matrix to be **dynamically stable** (all
eigenvalues of `A` have negative real part); `press_perturbation()`
checks this and warns when it fails. Treat the output as a defensible
qualitative scenario ("if I keep suppressing taxon A, the community
tends to shift this way"), never as a quantitative prediction. For a
purely structural read with no stability assumption, use
[get_network_perturbation()] or [get_node_influence()].
}

\examples{
\donttest{
data(ppi_example)
obj <- build_graph_from_df(
  df              = ppi_example$ppi,
  node_annotation = ppi_example$annotation
)
pp <- press_perturbation(obj)
pp$stable
pp$net_effect[1:3, 1:3]
}
}
\references{
Bender EA, Case TJ, Gilpin ME (1984). "Perturbation experiments in
community ecology: theory and practice." \emph{Ecology} 65(1):1-13.
May RM (1972). "Will a large complex system be stable?"
\emph{Nature} 238:413-414.
Novak M et al. (2016). "Characterizing species interactions to
understand press perturbations." \emph{Annu. Rev. Ecol. Evol. Syst.}
47:409-432.
}
\seealso{
[get_network_perturbation()], [get_node_influence()].
}
