% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hypergraph_centrality.R
\name{hypergraph_centrality}
\alias{hypergraph_centrality}
\title{Hypergraph eigenvector centralities}
\usage{
hypergraph_centrality(
  hg,
  type = c("clique", "Z", "H"),
  max_iter = 1000L,
  tol = 1e-08,
  normalize = TRUE
)
}
\arguments{
\item{hg}{A \code{net_hypergraph} (from \code{\link[=build_hypergraph]{build_hypergraph()}} or
\code{\link[=bipartite_groups]{bipartite_groups()}}).}

\item{type}{Character vector, any subset of \code{c("clique", "Z", "H")}.
Default computes all three.}

\item{max_iter}{Maximum number of power-iteration steps. Default
\code{1000}.}

\item{tol}{Convergence tolerance on the L1 change between successive
iterates. Default \code{1e-8}.}

\item{normalize}{Logical. If \code{TRUE} (default), each returned
centrality vector is L2-normalized to unit norm (compatible with
\code{igraph::eigen_centrality()}'s scale for type \code{"clique"}).}
}
\value{
A named list; one component per requested \code{type}. Each
component is a named numeric vector of length \code{hg$n_nodes}.
}
\description{
Computes one or more eigenvector-style centralities on a
\link[=build_hypergraph]{net_hypergraph}: \emph{clique-motif} (CEC),
\emph{Z-eigenvector} (ZEC), and \emph{H-eigenvector} (HEC). Each variant
captures influence differently - CEC flattens group structure via
clique expansion, while ZEC and HEC propagate through the
higher-order groups directly.
}
\details{
\strong{Clique-motif eigenvector centrality (CEC)}: forms the
clique-expanded pairwise graph \eqn{W} where
\eqn{W_{ij} = |\{e : i, j \in e\}|} and returns the leading
eigenvector of \eqn{W}. Equivalent to running
\code{igraph::eigen_centrality()} on \code{\link[=clique_expansion]{clique_expansion()}} output.

\strong{Z-eigenvector centrality (ZEC)}: solves the linear
eigen-equation on the hyperedge tensor,
\deqn{\lambda\, x_i \;=\; \sum_{e \ni i}\; \prod_{j \in e,\; j \neq i} x_j,}
via power iteration. Works for hypergraphs with mixed edge sizes.

\strong{H-eigenvector centrality (HEC)}: solves the power-k-1
eigen-equation,
\deqn{\lambda\, x_i^{k-1} \;=\; \sum_{e \ni i}\; \prod_{j \in e,\; j \neq i} x_j.}
For uniform hypergraphs (all hyperedges of size \eqn{k}), this is
equivalent to normalizing the ZEC update by the geometric-mean
exponent \eqn{1/(k-1)}. For mixed sizes, the effective exponent is
taken from the largest hyperedge; expect slightly different rankings
from ZEC in the mixed case.
}
\note{
The \code{"clique"} (CEC) variant is validated against
\code{igraph::eigen_centrality} (cosine ~ 1). The \code{"Z"} and \code{"H"} variants are
\strong{(experimental)} - validated only against a clean-room list-based
tensor power iteration (same operator, different loop structure); no
R package exposes tensor eigenvectors as a primitive for independent
comparison.
}
\examples{
df <- data.frame(
  player  = c("A", "B", "C", "A", "B", "D", "C", "D", "E"),
  session = c("S1", "S1", "S1", "S2", "S2", "S3", "S3", "S3", "S3")
)
hg <- bipartite_groups(df, "player", "session")
cent <- hypergraph_centrality(hg)
# Compare rankings across the three variants
do.call(cbind, cent)

}
\references{
Benson, A. R. (2019). Three hypergraph eigenvector centralities.
\emph{SIAM Journal on Mathematics of Data Science} 1(2), 293-312.
arXiv:1807.09644.
}
\seealso{
\code{\link[=build_hypergraph]{build_hypergraph()}}, \code{\link[=clique_expansion]{clique_expansion()}},
\code{\link[=hypergraph_measures]{hypergraph_measures()}}.
}
