% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hypergraph.R
\name{build_hypergraph}
\alias{build_hypergraph}
\alias{print.net_hypergraph}
\alias{summary.net_hypergraph}
\title{Higher-order hypergraph from a network's clique structure}
\usage{
build_hypergraph(
  net,
  p = 1,
  method = c("clique", "vr", "rips"),
  include_pairwise = TRUE,
  max_size = 3L,
  threshold = 0,
  seed = NULL
)

\method{print}{net_hypergraph}(x, ...)

\method{summary}{net_hypergraph}(object, ...)
}
\arguments{
\item{net}{A \code{netobject}, \code{cograph_network}, \code{simplicial_complex}, or
numeric adjacency / weight matrix. Directed inputs are symmetrised by
the underlying clique enumerator.}

\item{p}{Probability in \verb{[0, 1]} that each k-clique with k >= 3 becomes a
k-hyperedge. Default \code{1} (deterministic - every found clique is
included).}

\item{method}{Hyperedge enumeration. \code{"clique"} (default) promotes
k-cliques in the binarised adjacency to k-hyperedges. A metric
Vietoris-Rips construction is \strong{not implemented}; \code{"vr"} /
\code{"rips"} are accepted by \code{match.arg} but raise an error rather than
silently aliasing \code{"clique"}.}

\item{include_pairwise}{Logical. Include 2-edges from the input network as
2-hyperedges. Default \code{TRUE}. Set \code{FALSE} for a "fully higher-order"
hypergraph containing only k-hyperedges with k >= 3.}

\item{max_size}{Integer >= 2. Maximum hyperedge size to extract. Default
\code{3L} (triangles only). \code{4L} also includes 4-cliques as 4-hyperedges, etc.}

\item{threshold}{Numeric. Edge weight cutoff used to binarise the
adjacency for clique enumeration. Default \code{0} (any non-zero weight is
an edge).}

\item{seed}{Optional integer for reproducible Bernoulli sampling when
\verb{0 < p < 1}.}

\item{x}{A \code{net_hypergraph} object (for \code{print}).}

\item{...}{Additional arguments (ignored).}

\item{object}{A \code{net_hypergraph} object (for \code{summary}).}
}
\value{
A \code{net_hypergraph} object: a list with components
\describe{
\item{\code{hyperedges}}{List of integer vectors. Each entry is a hyperedge
given as the sorted node indices it spans.}
\item{\code{incidence}}{Numeric matrix of size \code{n_nodes} x \code{n_hyperedges}.
\code{incidence[i, j] = 1} iff node i belongs to hyperedge j. Row names
are node names; column names are \code{h1}, \code{h2}, ...}
\item{\code{nodes}}{Character vector of node names.}
\item{\code{n_nodes}, \code{n_hyperedges}}{Scalar counts.}
\item{\code{size_distribution}}{Named integer vector: number of hyperedges
of each size, named \code{size_2}, \code{size_3}, ...}
\item{\code{params}}{Recorded call parameters: \code{method}, \code{p},
\code{include_pairwise}, \code{max_size}, \code{threshold}, \code{seed}.}
}

The input \code{x} invisibly.

The input \code{object} invisibly.
}
\description{
Takes a network and produces a hypergraph by promoting k-cliques (k >= 3)
to k-hyperedges. Each k-clique is independently included as a k-hyperedge
with probability \code{p}. Optionally retains the underlying pairwise edges as
2-hyperedges. Foundation for higher-order analyses.
}
\details{
The construction follows Burgio, Matamalas, Gomez & Arenas (2020) on
simplicial / hypergraph contagion. For each k-clique with k >= 3 found in
the underlying graph (via \code{\link[=build_simplicial]{build_simplicial()}}), an independent
Bernoulli(\code{p}) trial decides whether that clique becomes a k-hyperedge.
Underlying pairwise edges are always retained when
\code{include_pairwise = TRUE}, so the resulting hypergraph contains both the
original 2-edge structure and the sampled higher-order interactions.

At the limits:
\itemize{
\item \code{p = 0} with \code{include_pairwise = TRUE} reproduces the input
pairwise network as a hypergraph of size-2 edges.
\item \code{p = 1} with \code{include_pairwise = FALSE} returns a fully
higher-order hypergraph containing only the k-hyperedges (k >= 3)
found in the network's clique complex.
}
}
\examples{
set.seed(1)
n <- 8
adj <- matrix(stats::rbinom(n * n, 1, 0.5), n, n)
diag(adj) <- 0
adj <- (adj + t(adj)) > 0
rownames(adj) <- colnames(adj) <- LETTERS[seq_len(n)]
hg <- build_hypergraph(adj, p = 1, max_size = 3L)
print(hg)
summary(hg)

}
\references{
Burgio, G., Matamalas, J. T., Gomez, S., & Arenas, A. (2020). Evolution
of cooperation in the presence of higher-order interactions: from
networks to hypergraphs. \emph{Entropy} 22(7), 744.
\doi{10.3390/e22070744}
}
\seealso{
\code{\link[=build_simplicial]{build_simplicial()}} (underlying clique enumeration),
\code{\link[=build_network]{build_network()}}.
}
