% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/centrality.R
\name{centrality}
\alias{centrality}
\title{Calculate Network Centrality Measures}
\usage{
centrality(
  x,
  measures = "all",
  mode = "all",
  normalized = FALSE,
  weighted = TRUE,
  directed = NULL,
  loops = TRUE,
  simplify = "sum",
  digits = NULL,
  sort_by = NULL,
  cutoff = -1,
  invert_weights = NULL,
  alpha = 1,
  damping = 0.85,
  personalized = NULL,
  transitivity_type = "local",
  isolates = "nan",
  lambda = 1,
  k = 3,
  states = NULL,
  ...
)
}
\arguments{
\item{x}{Network input (matrix, igraph, network, cograph_network, tna object)}

\item{measures}{Which measures to calculate. Default "all" calculates all
available measures. Can be a character vector of measure names:
"degree", "strength", "betweenness", "closeness", "eigenvector",
"pagerank", "authority", "hub", "eccentricity", "coreness",
"constraint", "transitivity", "harmonic", "diffusion", "leverage",
"kreach", "alpha", "power", "subgraph", "laplacian",
"load", "current_flow_closeness", "current_flow_betweenness", "voterank",
"percolation".}

\item{mode}{For directed networks: "all", "in", or "out". Affects degree,
strength, closeness, eccentricity, coreness, and harmonic centrality.}

\item{normalized}{Logical. Normalize values to 0-1 range by dividing by max.
For closeness, this is passed directly to igraph (proper normalization).}

\item{weighted}{Logical. Use edge weights if available. Default TRUE.}

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

\item{loops}{Logical. If TRUE (default), keep self-loops. Set to FALSE to
remove them before calculation.}

\item{simplify}{How to combine multiple edges between the same node pair.
Options: "sum" (default), "mean", "max", "min", or FALSE/"none" to keep
multiple edges.}

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

\item{sort_by}{Character or NULL. Column name to sort results by
(descending order). Default NULL (original node order).}

\item{cutoff}{Maximum path length to consider for betweenness and closeness.
Default -1 (no limit). Set to a positive value for faster computation
on large networks at the cost of accuracy.}

\item{invert_weights}{Logical or NULL. For path-based measures (betweenness,
closeness, harmonic, eccentricity, kreach), should weights be inverted so
that higher weights mean shorter paths? Default NULL which auto-detects:
TRUE for tna objects (transition probabilities), FALSE otherwise (matching
igraph/sna). Set explicitly to TRUE for strength/frequency weights (qgraph
style) or FALSE for distance/cost weights.}

\item{alpha}{Numeric. Exponent for weight transformation when \code{invert_weights = TRUE}.
Distance is computed as \code{1 / weight^alpha}. Default 1. Higher values
increase the influence of weight differences on path lengths.}

\item{damping}{PageRank damping factor. Default 0.85. Must be between 0 and 1.}

\item{personalized}{Named numeric vector for personalized PageRank.
Default NULL (standard PageRank). Values should sum to 1.}

\item{transitivity_type}{Type of transitivity to calculate: "local" (default),
"global", "undirected", "localundirected", "barrat" (weighted), or "weighted".}

\item{isolates}{How to handle isolate nodes in transitivity calculation:
"nan" (default) returns NaN, "zero" returns 0.}

\item{lambda}{Diffusion scaling factor for diffusion centrality. Default 1.}

\item{k}{Path length parameter for geodesic k-path centrality. Default 3.}

\item{states}{Named numeric vector of percolation states (0-1) for percolation
centrality. Each value represents how "activated" or "infected" a node is.
Default NULL (all nodes get state 1, equivalent to betweenness).}

\item{...}{Additional arguments (currently unused)}
}
\value{
A data frame with columns:
\itemize{
\item \code{node}: Node labels/names
\item One column per measure, with mode suffix for directional measures
(e.g., \code{degree_in}, \code{closeness_all})
}
}
\description{
Computes centrality measures for nodes in a network and returns a tidy
data frame. Accepts matrices, igraph objects, cograph_network, or tna objects.
}
\details{
The following centrality measures are available:
\describe{
\item{degree}{Count of edges (supports mode: in/out/all)}
\item{strength}{Weighted degree (supports mode: in/out/all)}
\item{betweenness}{Shortest path centrality}
\item{closeness}{Inverse distance centrality (supports mode: in/out/all)}
\item{eigenvector}{Influence-based centrality}
\item{pagerank}{Random walk centrality (supports damping and personalization)}
\item{authority}{HITS authority score}
\item{hub}{HITS hub score}
\item{eccentricity}{Maximum distance to other nodes (supports mode)}
\item{coreness}{K-core membership (supports mode: in/out/all)}
\item{constraint}{Burt's constraint (structural holes)}
\item{transitivity}{Local clustering coefficient (supports multiple types)}
\item{harmonic}{Harmonic centrality - handles disconnected graphs better
than closeness (supports mode: in/out/all)}
\item{diffusion}{Diffusion degree centrality - sum of scaled degrees of
node and its neighbors (supports mode: in/out/all, lambda scaling)}
\item{leverage}{Leverage centrality - measures influence over neighbors
based on relative degree differences (supports mode: in/out/all)}
\item{kreach}{Geodesic k-path centrality - count of nodes reachable
within distance k (supports mode: in/out/all, k parameter)}
\item{alpha}{Alpha/Katz centrality - influence via paths, penalized by
distance. Similar to eigenvector but includes exogenous contribution}
\item{power}{Bonacich power centrality - measures influence based on
connections to other influential nodes}
\item{subgraph}{Subgraph centrality - participation in closed loops/walks,
weighting shorter loops more heavily}
\item{laplacian}{Laplacian centrality using Qi et al. (2012) local formula.
Matches NetworkX and centiserve::laplacian()}
\item{load}{Load centrality - fraction of all shortest paths through node,
similar to betweenness but weights paths by 1/count}
\item{current_flow_closeness}{Information centrality - closeness based on
electrical current flow (requires connected graph)}
\item{current_flow_betweenness}{Random walk betweenness - betweenness based
on current flow rather than shortest paths (requires connected graph)}
\item{voterank}{VoteRank - identifies influential spreaders via iterative
voting mechanism. Returns normalized rank (1 = most influential)}
\item{percolation}{Percolation centrality - importance for spreading processes.
Uses node states (0-1) to weight paths. When all states equal, equivalent
to betweenness. Useful for epidemic/information spreading analysis.}
}
}
\examples{
# Basic usage with matrix
adj <- matrix(c(0, 1, 1, 1, 0, 1, 1, 1, 0), 3, 3)
rownames(adj) <- colnames(adj) <- c("A", "B", "C")
centrality(adj)

# Specific measures
centrality(adj, measures = c("degree", "betweenness"))

# Directed network with normalization
centrality(adj, mode = "in", normalized = TRUE)

# Sort by pagerank
centrality(adj, sort_by = "pagerank", digits = 3)

# PageRank with custom damping
centrality(adj, measures = "pagerank", damping = 0.9)

# Harmonic centrality (better for disconnected graphs)
centrality(adj, measures = "harmonic")

# Global transitivity
centrality(adj, measures = "transitivity", transitivity_type = "global")
}
