% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/permutation_test.R
\name{permutation}
\alias{permutation}
\title{Permutation Test for Network Comparison}
\usage{
permutation(
  x,
  y = NULL,
  iter = 1000L,
  alpha = 0.05,
  paired = FALSE,
  adjust = "none",
  nlambda = 50L,
  seed = NULL
)
}
\arguments{
\item{x}{A \code{netobject} (from \code{\link{build_network}}).}

\item{y}{A \code{netobject} (from \code{\link{build_network}}).
Must use the same method and have the same nodes as \code{x}.}

\item{iter}{Integer. Number of permutation iterations (default: 1000).}

\item{alpha}{Numeric. Significance level (default: 0.05).}

\item{paired}{Logical. If \code{TRUE}, permute within pairs (requires
equal number of observations in \code{x} and \code{y}). Default: FALSE.}

\item{adjust}{Character. p-value adjustment method passed to
\code{\link[stats]{p.adjust}} (default: \code{"none"}). Common choices:
\code{"holm"}, \code{"BH"}, \code{"bonferroni"}.}

\item{nlambda}{Integer. Number of lambda values for the \code{glassopath}
regularisation path (only used when \code{method = "glasso"}).
Higher values give finer lambda resolution at the cost of speed.
Default: 50.}

\item{seed}{Integer or NULL. RNG seed for reproducibility.}
}
\value{
An object of class \code{"net_permutation"} containing:
\describe{
\item{x}{The first \code{netobject}.}
\item{y}{The second \code{netobject}.}
\item{diff}{Observed difference matrix (\code{x - y}).}
\item{diff_sig}{Observed difference where \code{p < alpha}, else 0.}
\item{p_values}{P-value matrix (adjusted if \code{adjust != "none"}).}
\item{effect_size}{Effect size matrix (observed diff / SD of permutation diffs).}
\item{summary}{Long-format data frame of edge-level results.}
\item{method}{The network estimation method.}
\item{iter}{Number of permutation iterations.}
\item{alpha}{Significance level used.}
\item{paired}{Whether paired permutation was used.}
\item{adjust}{p-value adjustment method used.}
}
}
\description{
Compares two networks estimated by \code{\link{build_network}} using a
permutation test. Works with all built-in methods (transition and
association) as well as custom registered estimators. The test shuffles
which observations belong to which group, re-estimates networks, and tests
whether observed edge-wise differences exceed chance.

For transition methods (\code{"relative"}, \code{"frequency"},
\code{"co_occurrence"}), uses a fast pre-computation strategy: per-sequence
count matrices are computed once, and each permutation iteration only
shuffles group labels and computes group-wise \code{colSums}.

For association methods (\code{"cor"}, \code{"pcor"}, \code{"glasso"},
and custom estimators), the full estimator is called on each permuted
group split.
}
\examples{
s1 <- data.frame(V1 = c("A","B","C"), V2 = c("B","C","A"))
s2 <- data.frame(V1 = c("A","C","B"), V2 = c("C","B","A"))
n1 <- build_network(s1, method = "relative")
n2 <- build_network(s2, method = "relative")
perm <- permutation(n1, n2, iter = 10)
\donttest{
set.seed(1)
d1 <- data.frame(V1 = sample(LETTERS[1:4], 20, TRUE),
                 V2 = sample(LETTERS[1:4], 20, TRUE),
                 V3 = sample(LETTERS[1:4], 20, TRUE))
d2 <- data.frame(V1 = sample(LETTERS[1:4], 20, TRUE),
                 V2 = sample(LETTERS[1:4], 20, TRUE),
                 V3 = sample(LETTERS[1:4], 20, TRUE))
net1 <- build_network(d1, method = "relative")
net2 <- build_network(d2, method = "relative")
perm <- permutation(net1, net2, iter = 100, seed = 42)
print(perm)
summary(perm)
}

}
\seealso{
\code{\link{build_network}}, \code{\link{bootstrap_network}},
\code{\link{print.net_permutation}},
\code{\link{summary.net_permutation}}
}
