% 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"),
  seed = NULL
)

csig(
  x,
  communities,
  n_random = 100,
  method = c("configuration", "gnm"),
  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{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{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{
The test works by:
\enumerate{
\item Computing the modularity of the provided community structure
\item Generating \code{n_random} random networks using the specified null model
\item For each random network, detecting communities with Louvain and
computing modularity
\item Comparing the observed modularity to this null distribution
}

A significant result (low p-value) indicates that the community structure
is stronger than expected by chance for networks with similar properties.
}
\examples{
\dontrun{
if (requireNamespace("igraph", quietly = TRUE)) {
  g <- igraph::make_graph("Zachary")
  comm <- community_louvain(g)

  # Test significance
  sig <- cluster_significance(g, comm, n_random = 100, seed = 123)
  print(sig)

  # Configuration model (stricter test)
  sig2 <- cluster_significance(g, comm, method = "configuration")
}
}
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}}
}
