% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vulnerability.R
\name{vulnerability}
\alias{vulnerability}
\title{Node Vulnerability}
\usage{
vulnerability(
  x,
  directed = NULL,
  normalized = TRUE,
  weighted = FALSE,
  invert_weights = TRUE,
  alpha = 1,
  digits = NULL,
  ...
)
}
\arguments{
\item{x}{Network input: matrix, igraph, network, cograph_network, or tna
object.}

\item{directed}{Logical or NULL. If NULL (default), auto-detect from matrix
symmetry. Set TRUE to force directed, FALSE to force undirected.}

\item{normalized}{Logical. If TRUE (default), return the proportional drop.
If FALSE, return the raw efficiency difference.}

\item{weighted}{Logical. If TRUE, honor edge weights when computing
shortest paths (Dijkstra); distance is \code{1/weight^alpha} per the
usual qgraph/tna convention when \code{invert_weights = TRUE}. If FALSE
(default, matches prior behavior), all edges are treated as unit length.}

\item{invert_weights}{Logical. If TRUE (default) and weights are present,
invert weights to distances via \code{1/weight^alpha} so that higher
weight = shorter path (matches \code{centrality()}'s default). Ignored
when \code{weighted = FALSE}.}

\item{alpha}{Weight-to-distance exponent (default 1).}

\item{digits}{Integer or NULL. Round scores to this many decimal places.
Default NULL (no rounding).}

\item{...}{Additional arguments passed to \code{\link{to_igraph}}.}
}
\value{
A data frame of class \code{"cograph_vulnerability"} with columns:
\describe{
\item{node}{Node labels.}
\item{vulnerability}{Vulnerability scores, sorted descending.}
}
The original input network and normalization mode are stored as
attributes.
}
\description{
Computes the vulnerability of each node, defined as the relative drop in
global efficiency when that node is removed from the network.
}
\details{
\deqn{V(i) = \frac{E_{global} - E_{global \setminus i}}{E_{global}}}

where \eqn{E_{global}} is the global efficiency of the full network and
\eqn{E_{global \setminus i}} is the global efficiency after removing node i
and all its edges.

Global efficiency is defined as:

\deqn{E_{global} = \frac{1}{n(n-1)} \sum_{i \neq j} \frac{1}{d(i,j)}}

Nodes with high vulnerability are critical to the network's communication
efficiency. Removing them causes the greatest drop in global efficiency.

\strong{Performance note:} This function computes all-pairs shortest paths
once for the full graph and once per node removal, giving O(n) calls to
the shortest-path algorithm. A warning is issued for networks with more
than 500 nodes.
}
\examples{
# Star network: hub is most vulnerable
star <- matrix(c(0,1,1,1, 1,0,0,0, 1,0,0,0, 1,0,0,0), 4, 4)
rownames(star) <- colnames(star) <- c("hub", "a", "b", "c")
cograph::vulnerability(star)

# Complete graph: all nodes equally vulnerable
k4 <- matrix(1, 4, 4); diag(k4) <- 0
rownames(k4) <- colnames(k4) <- c("A", "B", "C", "D")
cograph::vulnerability(k4)
}
\references{
Latora, V. & Marchiori, M. (2007). A measure of centrality based on
network efficiency. \emph{New Journal of Physics}, 9(6), 188.
\doi{10.1088/1367-2630/9/6/188}
}
\seealso{
\code{\link{network_global_efficiency}}, \code{\link{robustness}},
\code{\link{centrality}}
}
