% 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,
  type = c("basic", "extended", "all"),
  measures = NULL,
  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,
  diffusion_method = NULL,
  k = 3,
  states = NULL,
  decay_parameter = 0.5,
  dmnc_epsilon = 1.7,
  membership = NULL,
  katz_alpha = 0.1,
  hubbell_weight = 0.5,
  tna_network = NULL,
  psych_network = NULL,
  ...
)
}
\arguments{
\item{x}{Network input (matrix, edge-list data frame, igraph, network,
cograph_network, tna object)}

\item{type}{Character scalar selecting a curated tier of measures when
\code{measures} is not supplied. One of:
\describe{
\item{\code{"basic"}}{(default) 6 canonical measures: \code{degree},
\code{strength}, \code{closeness}, \code{betweenness},
\code{eigenvector}, \code{pagerank}.}
\item{\code{"extended"}}{Basic plus commonly-reported second-tier
measures: harmonic, coreness, eccentricity, radiality,
lin, decay, load, stress, katz, alpha, power, authority, leverage,
constraint, effective_size, bridging, transitivity, subgraph,
diffusion, laplacian, kreach, current_flow_betweenness,
current_flow_closeness.}
\item{\code{"all"}}{Every available measure.}
}
Passing \code{measures} explicitly overrides \code{type}.}

\item{measures}{Character vector of specific measure names to compute.
When \code{NULL} (default) the tier selected by \code{type} is used.
Accepts \code{"all"} as a shortcut for every measure. Any custom vector
of valid measure names is also accepted.
\strong{Core} (igraph-backed): "degree", "strength", "betweenness", "closeness",
"eigenvector", "pagerank", "authority", "hub", "eccentricity", "coreness",
"constraint", "transitivity", "harmonic", "alpha", "power", "subgraph".
\strong{Native}: "diffusion", "leverage", "kreach", "laplacian", "load",
"current_flow_closeness", "current_flow_betweenness", "voterank",
"percolation".
\strong{Distance-based}: "radiality", "lin", "decay", "residual_closeness",
"dangalchev", "generalized_closeness", "harary", "average_distance",
"barycenter", "wiener", "closeness_vitality".
\strong{Spectral/walk}: "communicability", "communicability_betweenness",
"random_walk".
\strong{Path-based}: "stress", "flow_betweenness".
\strong{Local/neighborhood}: "lobby", "entropy", "semilocal", "clusterrank",
"bottleneck", "centroid", "mnc", "dmnc", "lac", "topological_coefficient",
"bridging", "local_bridging", "effective_size", "diversity",
"cross_clique", "markov".
\strong{Influence}: "integration", "expected", "gilschmidt".
\strong{Directed-only}: "salsa", "leaderrank", "trophic_level", "pairwisedis",
"prestige_domain", "prestige_domain_proximity".
\strong{Community-aware} (require \code{membership}): "participation",
"within_module_z", "gateway", "brokerage_coordinator",
"brokerage_itinerant", "brokerage_representative",
"brokerage_gatekeeper", "brokerage_liaison" (the last 5 also require
a directed graph; see \code{\link{centrality_brokerage_coordinator}}).
\strong{Zoo (batch 2)}: "gravity", "collective_influence", "local_hindex",
"hindex_strength", "onion", "second_order", "infection", "nonbacktracking",
"spanning_tree".
\strong{Classical (batch 3, reference-validated)}: "katz" (Katz 1953),
"hubbell" (Hubbell 1965), "information" (Stephenson-Zelen 1989),
"reaching_local" (Mones et al. 2012). See \code{\link{centrality_katz}},
\code{\link{centrality_hubbell}}, \code{\link{centrality_information}},
\code{\link{centrality_pairwisedis}}, \code{\link{centrality_reaching_local}}.
\strong{Psychometric (signed-weight)}: "expected_influence_1",
"expected_influence_2" (Robinaugh, Millner & McNally 2016). Expected
influence keeps signed edge contributions, which is important when edges
can be negative (partial-correlation, glasso, signed correlation networks).}

\item{mode}{For directed networks: "all", "in", or "out". Affects measures
whose output columns carry a mode suffix, including degree, strength,
closeness, eccentricity, coreness, harmonic, diffusion, leverage, k-reach,
distance-based measures, community-aware measures, and expected influence.}

\item{normalized}{Logical. Normalize values by dividing by max. Most measures
are scaled to 0-1; signed expected-influence measures can retain negative
values under psychometric normalization. For closeness, this is passed
directly to igraph.}

\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, closeness,
and harmonic centrality.
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- and distance-based measures
(for example betweenness, closeness, harmonic, eccentricity, k-reach,
radiality, decay, stress, flow betweenness, and related variants), should
weights be inverted so that higher weights mean shorter paths? Default
NULL 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),
"weighted", or "onnela". The first six dispatch to
\code{igraph::transitivity()}; \code{"onnela"} computes the Onnela /
Holme weighted clustering coefficient on the symmetrized matrix
(\code{wcc(x + t(x))}) and matches \code{tna::centralities(., "Clustering")}
byte-for-byte. Auto-set to \code{"onnela"} when \code{tna_network = TRUE}
and the user did not pass an explicit value.}

\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.
Only used when \code{diffusion_method = "kandhway_kuri"}.}

\item{diffusion_method}{Character or NULL. Selects the diffusion-centrality
formula. \code{"kandhway_kuri"} (Kandhway & Kuri, 2014) computes the
1-hop binary-degree neighborhood sum
\eqn{\lambda d_v + \lambda \sum_{u \in N(v)} d_u}. \code{"power_series"}
computes the matrix power series \eqn{\mathrm{rowSums}(P + P^2 + \ldots + P^n)}
on the (optionally diagonal-zeroed) weighted matrix and matches
\code{tna::centralities(., measures = "Diffusion")} when
\code{loops = FALSE}. Default NULL auto-detects: \code{"power_series"}
for tna objects (transition probabilities), \code{"kandhway_kuri"}
otherwise.}

\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{decay_parameter}{Numeric. Decay parameter for decay and generalized
closeness centrality. Default 0.5. Must be between 0 and 1.}

\item{dmnc_epsilon}{Numeric. Epsilon exponent for DMNC (Density of Maximum
Neighborhood Component). Default 1.7 as recommended by Lin et al. (2008).
centiserve uses 1.67 (four-community assumption). Must be between 1 and 2.}

\item{membership}{Integer vector of community assignments (one per node) for
community-aware measures: participation, within_module_z, gateway, and the
Gould-Fernandez brokerage roles. Default NULL. Required when requesting
these measures.}

\item{katz_alpha}{Attenuation factor for Katz centrality. Must satisfy
\eqn{\alpha < 1 / \rho(A)}. Default 0.1 (matches centiserve and NetworkX
conventions). Only used when \code{"katz"} is in \code{measures}.}

\item{hubbell_weight}{Weight factor \eqn{w} for Hubbell centrality. Must
satisfy \eqn{w \cdot \rho(W) \le 1} for solvability. Default 0.5. Only
used when \code{"hubbell"} is in \code{measures}.}

\item{tna_network}{Logical or NULL. Umbrella switch that forces tna-style
conventions across all measures. \code{NULL} (default) auto-detects
from the input class — TRUE iff \code{x} is a \code{tna} or related
sequence-network object. \code{TRUE} forces tna conventions even on
raw matrices: \code{invert_weights = TRUE}, \code{loops = FALSE},
\code{diffusion_method = "power_series"}, \code{transitivity_type
  = "onnela"}. \code{FALSE} suppresses all tna defaults even for tna
inputs, giving the cograph defaults verbatim. Precedence: any arg
the user passes explicitly always wins over \code{tna_network}.}

\item{psych_network}{Logical or NULL. Switch for signed psychometric
network conventions. \code{NULL} (default) auto-detects TRUE when a
signed weighted network is evaluated with expected-influence measures.
When \code{TRUE}, normalized expected influence is divided by the maximum
absolute expected-influence value, preserving sign and bounding the result from
-1 to 1.
\code{FALSE} keeps the generic cograph normalization convention.}

\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, edge-list data frames, 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.}
\item{radiality}{Radiality centrality (centiserve). Sum of (diam + 1 - d)
normalized by n-1.}
\item{lin}{Lin's centrality. Reachable nodes squared divided by sum of
distances.}
\item{decay}{Decay centrality. Sum of delta^d for parameter delta.}
\item{residual_closeness}{Residual closeness. Sum of 1/2^d.}
\item{dangalchev}{Dangalchev closeness (alias for residual closeness).}
\item{generalized_closeness}{Generalized closeness. Sum of alpha^d.}
\item{harary}{Harary centrality. Sum of 1/d^2 for all reachable pairs.}
\item{average_distance}{Average distance (centiserve). Sum of distances /
(n+1).}
\item{barycenter}{Barycenter centrality. 1 / sum of distances.}
\item{wiener}{Wiener index. Total sum of shortest path distances from node.}
\item{closeness_vitality}{Closeness vitality. Drop in Wiener index when
node removed.}
\item{communicability}{Total communicability. Row sums of matrix exponential.}
\item{communicability_betweenness}{Communicability betweenness. Fraction of
communicability through each node.}
\item{random_walk}{Random walk centrality. Inverse sum of random walk
distances (requires connected graph).}
\item{stress}{Stress centrality. Number of shortest paths through node.}
\item{flow_betweenness}{Flow betweenness. Max-flow based betweenness.}
\item{lobby}{Lobby index (h-index of neighborhood).}
\item{entropy}{Graph entropy centrality. Entropy change on node removal.}
\item{semilocal}{Semi-local centrality. Triple-nested neighborhood sum.}
\item{clusterrank}{ClusterRank. Clustering coefficient times neighbor
degree sum.}
\item{bottleneck}{Bottleneck centrality. Count of shortest path trees where
node is critical.}
\item{centroid}{Centroid value. Minimum f(v,i) across all nodes.}
\item{mnc}{Maximum Neighborhood Component size.}
\item{dmnc}{Density of Maximum Neighborhood Component.}
\item{topological_coefficient}{Topological coefficient. Shared neighbor
ratio.}
\item{bridging}{Bridging centrality. Betweenness times bridging
coefficient.}
\item{local_bridging}{Local bridging. (1/degree) times bridging
coefficient.}
\item{effective_size}{Burt's effective size. Degree minus redundancy.}
\item{diversity}{Diversity centrality. Shannon entropy of edge weight
distribution.}
\item{cross_clique}{Cross-clique connectivity. Count of cliques containing
node.}
\item{markov}{Markov centrality. Inverse mean first passage time
(requires connected graph).}
\item{integration}{Integration centrality. Distance-based influence.}
\item{expected}{Expected centrality. Sum of neighbor degrees.}
\item{gilschmidt}{Gil-Schmidt power index. Sum of 1/d normalized by n-1.}
\item{salsa}{SALSA authority scores (directed graphs only).}
\item{leaderrank}{LeaderRank. PageRank with ground node
(directed graphs only).}
\item{participation}{Participation coefficient. Diversity of inter-community
connections (requires \code{membership}).}
\item{within_module_z}{Within-module degree z-score. Intra-community
connectivity (requires \code{membership}).}
\item{gateway}{Gateway coefficient. Inter-community brokerage weighted by
centrality (requires \code{membership}).}
}
}
\examples{
# Built-in edge-list data
data(student_interactions)
centrality(student_interactions)

# Matrix input also works
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")
}
