% 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",
  measures = NULL,
  nlambda = 50L,
  seed = NULL
)
}
\arguments{
\item{x}{A \code{netobject} (from \code{\link{build_network}}) or a
\code{\link{net_edge_betweenness}} object.}

\item{y}{A \code{netobject} (from \code{\link{build_network}}) or a
\code{\link{net_edge_betweenness}} object.
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{measures}{Character vector of centrality measures to permutation-test
in addition to the edges, or \code{"all"} for every built-in measure.
Default \code{NULL} (edges only). When supplied, the result gains a
\code{$centralities} block matching the layout of
\code{tna::permutation_test(measures = )}: per state and measure it reports
the observed difference, an effect size (difference / SD of the permutation
null), and a permutation p-value, all using the same permuted networks as
the edge test. Not supported for \code{net_edge_betweenness} inputs.}

\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{source_method}{For edge-betweenness tests, the source network 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.}
\item{centralities}{Present only when \code{measures} is supplied. A list
with \code{stats} (one row per state-by-measure: \code{state},
\code{centrality}, \code{diff_true}, \code{effect_size}, \code{p_value}),
\code{diffs_true} (wide observed differences), and \code{diffs_sig}
(observed differences where \code{p < alpha}, else 0).}
}
}
\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.

If either transition network contains only one sequence, the function warns
that such a network is not recommended for permutation or other
confirmatory testing.

\code{permutation()} also accepts two \code{\link{net_edge_betweenness}}
objects. In that case it permutes the source networks, recomputes edge
betweenness for each shuffled split, and tests edge-betweenness differences.
The two edge-betweenness objects must come from the same source method and
use the same \code{invert} setting.
}
\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{bayes_compare}} for the Bayesian complement: instead of
"is this difference more extreme than chance?" it answers "how probable is
a difference, and how large?";
\code{\link{build_network}}, \code{\link{bootstrap_network}},
\code{\link{print.net_permutation}},
\code{\link{summary.net_permutation}}
}
