% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hypergraph_measures.R
\name{hypergraph_measures}
\alias{hypergraph_measures}
\alias{print.hypergraph_measures}
\title{Structural measures for a hypergraph}
\usage{
hypergraph_measures(hg)

\method{print}{hypergraph_measures}(x, ...)
}
\arguments{
\item{hg}{A \code{net_hypergraph} (from \code{\link[=build_hypergraph]{build_hypergraph()}} or
\code{\link[=bipartite_groups]{bipartite_groups()}}).}

\item{x}{A \code{hypergraph_measures} object.}

\item{...}{Additional arguments (ignored).}
}
\value{
An object of class \code{hypergraph_measures} (a named list) with
components:

\describe{
\item{\strong{Node-level (length \code{n_nodes})}}{}
\item{\code{hyperdegree}}{Number of hyperedges containing each node.}
\item{\code{node_strength}}{Total participation: for node \eqn{i},
\eqn{\sum_{e \ni i} |e|}. A node in many large hyperedges has
high strength.}
\item{\code{max_edge_size}}{Size of the largest hyperedge containing
each node.}
\item{\code{co_degree}}{\code{n_nodes} x \code{n_nodes} matrix:
\verb{co_degree[i, j] = |\{e : i, j in e\}|} (number of hyperedges
co-containing nodes \eqn{i} and \eqn{j}). Diagonal is zero.}
\item{\strong{Hyperedge-level (length \code{n_hyperedges} or m x m)}}{}
\item{\code{edge_sizes}}{Hyperedge sizes \eqn{|e|}.}
\item{\code{edge_pairwise_overlap}}{\code{m} x \code{m} matrix:
\verb{|e_i intersect e_j|}. Diagonal is zero.}
\item{\code{overlap_coefficient}}{\code{m} x \code{m}:
\verb{|e_i and e_j| / min(|e_i|, |e_j|)}. Measures how much the
smaller hyperedge is contained in the larger.}
\item{\code{jaccard}}{\code{m} x \code{m}: symmetric overlap index
\verb{|e_i and e_j| / |e_i union e_j|}.}
\item{\strong{Global (scalars)}}{}
\item{\code{density}}{For \code{k}-uniform hypergraphs: \code{m / choose(n, k)}.
For mixed sizes: \verb{sum(|e|) / (n * m)} (mean fraction of nodes
per hyperedge).}
\item{\code{avg_edge_size}}{Mean of \code{edge_sizes}.}
\item{\code{size_distribution}}{Tabulation of hyperedge sizes (passed
through from \code{hg}).}
\item{\code{intersection_profile}}{Distribution of pairwise hyperedge
intersection sizes - useful for spotting whether hyperedges
overlap mostly trivially or share substantial cores
(Do et al. 2020).}
\item{\code{pairwise_participation}}{Fraction of node pairs co-appearing
in at least one hyperedge.}
\item{\code{n_nodes}, \code{n_hyperedges}}{Convenience scalars.}
}

The input \code{x} invisibly.
}
\description{
Computes a comprehensive structural-statistics suite for a
\link[=build_hypergraph]{net_hypergraph}: node-level, hyperedge-level, and
global measures. All measures are derived in a few BLAS calls on the
incidence matrix.
}
\details{
All measures are computed via standard matrix operations on the binary
incidence \eqn{B = (b_{ij})} where \eqn{b_{ij} = 1} iff node \eqn{i}
is in hyperedge \eqn{j}:
\itemize{
\item \code{hyperdegree = rowSums(B)},
\code{edge_sizes = colSums(B)}
\item \code{co_degree = tcrossprod(B)} (with zero diagonal)
\item \code{edge_pairwise_overlap = crossprod(B)} (with zero diagonal)
\item \code{overlap_coefficient[i, j] = overlap[i, j] / min(edge_sizes[i], edge_sizes[j])}
\item \code{jaccard[i, j] = overlap[i, j] / (edge_sizes[i] + edge_sizes[j] - overlap[i, j])}
}

Empty hypergraph (\code{n_hyperedges == 0}) returns trivial zeros and
empty matrices.
}
\examples{
df <- data.frame(
  player  = c("A", "B", "C", "A", "B", "D", "C", "D"),
  session = c("S1", "S1", "S1", "S2", "S2", "S3", "S3", "S3")
)
hg <- bipartite_groups(df, "player", "session")
m  <- hypergraph_measures(hg)
print(m)
m$hyperdegree         # how many sessions each player joined
m$co_degree           # pairwise co-membership counts
m$jaccard             # symmetric overlap between sessions

}
\references{
Lee, G., Choe, M., & Shin, K. (2024). A survey on hypergraph
representation, learning and mining. \emph{Data Mining & Knowledge
Discovery} 37, 1-39.

Do, M. T., Yoon, S., Hooi, B., & Shin, K. (2020). Structural patterns
and generative models of real-world hypergraphs. arXiv:2006.07060.
}
\seealso{
\code{\link[=build_hypergraph]{build_hypergraph()}}, \code{\link[=bipartite_groups]{bipartite_groups()}},
\code{\link[=clique_expansion]{clique_expansion()}}.
}
