% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cluster-metrics.R
\name{cluster_significance}
\alias{cluster_significance}
\alias{csig}
\title{Test Significance of Community Structure}
\usage{
cluster_significance(
  x,
  communities,
  n_random = 100,
  method = c("configuration", "gnm"),
  null = c("detect", "fixed"),
  seed = NULL
)

csig(
  x,
  communities,
  n_random = 100,
  method = c("configuration", "gnm"),
  null = c("detect", "fixed"),
  seed = NULL
)
}
\arguments{
\item{x}{Network input: adjacency matrix, igraph object, or cograph_network.}

\item{communities}{A communities object (from \code{\link{communities}} or
igraph) or a membership vector (integer vector where \code{communities[i]}
is the community of node i).}

\item{n_random}{Number of random networks to generate for the null
distribution. Default 100.}

\item{method}{Null model type:
\describe{
\item{"configuration"}{Preserves degree sequence (default). More
stringent test.}
\item{"gnm"}{Erdos-Renyi model with same number of edges. Tests against
random baseline.}
}}

\item{null}{Which null question to answer. Default \code{"detect"}:
\describe{
\item{"detect"}{Null is the modularity of the \emph{best partition
found by community detection} on each null graph. Answers "is the
observed partition stronger than what community detection would
recover on similar random graphs?" — the historical behavior.}
\item{"fixed"}{Null is the modularity of the supplied
\code{communities} membership \emph{evaluated on each null graph}.
Answers "does the supplied partition itself explain more structure
than it would on similar random graphs?" — the conservative test.}
}}

\item{seed}{Random seed for reproducibility. Default NULL.}
}
\value{
A \code{cograph_cluster_significance} object with:
\describe{
\item{observed_modularity}{Modularity of the input communities}
\item{null_mean}{Mean modularity of random networks}
\item{null_sd}{Standard deviation of null modularity}
\item{z_score}{Standardized score: (observed - null_mean) / null_sd}
\item{p_value}{One-sided p-value (probability of observing equal or
higher modularity by chance)}
\item{null_values}{Vector of modularity values from null distribution}
\item{method}{Null model method used}
\item{null}{Which null question was asked ("detect" or "fixed")}
\item{n_random}{Number of random networks generated}
}

See \code{\link{cluster_significance}}.
}
\description{
Compares observed modularity against a null model distribution to assess
whether the detected community structure is statistically significant.
}
\details{
Two null models are supported. The default, \code{null = "detect"},
generates \code{n_random} random networks, runs community detection
(Louvain, with fast-greedy fallback) on each, and records the resulting
modularity. Low p-value means the observed partition beats what
detection would return on similar random graphs. \code{null = "fixed"}
instead evaluates the user-supplied membership on each null graph, so
low p-value means the partition itself is stronger than it would be on
similar random graphs — a tighter question that isolates the
partition's quality from any detector's behavior.

A significant result (low p-value) indicates that the community structure
is stronger than expected by chance for networks with similar properties.
}
\examples{
\dontshow{if (requireNamespace("igraph", quietly = TRUE)) withAutoprint(\{ # examplesIf}
g <- igraph::make_graph("Zachary")
comm <- community_louvain(g)
sig <- cluster_significance(g, comm, n_random = 20, seed = 123)
print(sig)
\dontshow{\}) # examplesIf}
if (requireNamespace("igraph", quietly = TRUE)) {
  g <- igraph::make_graph("Zachary")
  comm <- community_louvain(g)
  csig(g, comm, n_random = 20, seed = 1)
}
}
\references{
Reichardt, J., & Bornholdt, S. (2006).
Statistical mechanics of community detection.
\emph{Physical Review E}, 74, 016110.
}
\seealso{
\code{\link{communities}}, \code{\link{cluster_quality}}
}
