% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_network_perturbation.R
\name{get_network_perturbation}
\alias{get_network_perturbation}
\title{Structural perturbation ("virtual attack") of a network}
\usage{
get_network_perturbation(
  graph_obj,
  strategy = c("random", "targeted", "module", "manual"),
  centrality = c("degree", "strength", "betweenness", "closeness", "eigenvector", "ivi"),
  target = NULL,
  module_col = "Modularity",
  fractions = seq(0.05, 1, by = 0.05),
  decreasing = TRUE,
  bootstrap = 100,
  seed = 123,
  plot = TRUE
)
}
\arguments{
\item{graph_obj}{A `tbl_graph` from any `build_graph_from_*()`
constructor.}

\item{strategy}{Character. One of `"random"`, `"targeted"`,
`"module"`, `"manual"`.}

\item{centrality}{Character. Used when `strategy = "targeted"`.
One of `"degree"`, `"strength"`, `"betweenness"`, `"closeness"`,
`"eigenvector"`, `"ivi"`. `"strength"` uses the `weight` edge
attribute; `"ivi"` requires the `influential` package.}

\item{target}{Character vector. The module label(s) (when
`strategy = "module"`) or node `name`s (when `strategy = "manual"`)
to remove.}

\item{module_col}{Character (default `"Modularity"`). Node column
holding module labels, used when `strategy = "module"`.}

\item{fractions}{Numeric vector in `(0, 1]`. Removal fractions for
`"random"` / `"targeted"`. Default `seq(0.05, 1, by = 0.05)`.}

\item{decreasing}{Logical (default `TRUE`). For `"targeted"`, remove
the most-central nodes first (`TRUE`) or least-central first
(`FALSE`).}

\item{bootstrap}{Integer (default `100`). Number of random repetitions
for `strategy = "random"`.}

\item{seed}{Integer (default `123`). Seed for the random strategy, so
results are reproducible.}

\item{plot}{Logical (default `TRUE`). Attach a ready-made attack-curve
ggplot of `LCC_fraction` (only for `"random"` / `"targeted"`).}
}
\value{
A list with:
  \itemize{
    \item `curve`: long data frame (`strategy`, `fraction`, `metric`,
      `value`, and for random `value_sd` / `value_se`).
    \item `robustness_index`: data frame with the Schneider R-index
      (area under the `LCC_fraction` curve) per strategy.
    \item `plot`: ggplot of the LCC attack curve, or `NULL`.
  }
}
\description{
Repeatedly removes nodes from a network -- at random, by targeted
attack on a centrality, or by knocking out a named module / node set --
recomputes a panel of connectivity-sensitive topology metrics after
each removal, and returns the resulting *perturbation curve* together
with a single-number robustness index (Schneider R). This is the
structural ("type 1") virtual-perturbation analysis: it asks how the
network falls apart as nodes are progressively lost.
}
\details{
The random strategy is the multi-metric generalisation of the
node-removal robustness already computed inside
[get_network_topology()]; the targeted / module / manual strategies
answer "which nodes (or whole modules) hold the network together?".
}
\section{Strategies}{

\describe{
  \item{`"random"`}{Remove a random subset at each fraction, repeated
    `bootstrap` times; mean / sd / se are reported. Seeded for
    reproducibility.}
  \item{`"targeted"`}{Rank nodes by `centrality` and remove them in
    order (most-central first by default). The classic intentional
    attack -- usually far more damaging than random failure.}
  \item{`"module"`}{Knock out every node whose `module_col` label is
    in `target`; reported as a before/after comparison.}
  \item{`"manual"`}{Knock out the exact node `name`s given in
    `target`; reported as a before/after comparison.}
}
}

\section{Metrics tracked after each removal}{

\describe{
  \item{`LCC_fraction`}{Size of the largest connected component as a
    fraction of the *original* node count (the main attack curve).}
  \item{`N_components`}{Number of connected components.}
  \item{`Natural_connectivity`}{`log(mean(exp(eigenvalues(A))))`; a
    spectral robustness measure that varies smoothly and does not
    jump discretely the way component counts do.}
  \item{`Efficiency`}{Mean of `1 / shortest-path-distance`.}
  \item{`Mean_degree`, `Density`, `Transitivity_global`,
    `Modularity`}{Standard summaries recomputed on the survivor
    subgraph.}
}
}

\examples{
\donttest{
data(ppi_example)
obj <- build_graph_from_df(
  df              = ppi_example$ppi,
  node_annotation = ppi_example$annotation
)
res <- get_network_perturbation(obj, strategy = "targeted",
                                centrality = "degree")
head(res$curve)
res$robustness_index
}
}
\references{
Albert R, Jeong H, Barabasi AL (2000). "Error and attack tolerance of
complex networks." \emph{Nature} 406:378-382.
Schneider CM et al. (2011). "Mitigation of malicious attacks on
networks." \emph{PNAS} 108(10):3838-3841.
}
\seealso{
[get_node_influence()] for abundance-influence propagation;
  [press_perturbation()] for the press-perturbation approximation;
  [get_network_topology()] for static network-level metrics.
}
