% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/identify_critical_links.R
\name{identify_critical_links}
\alias{identify_critical_links}
\title{Identify Critical Edges That Explain Population Differences}
\usage{
identify_critical_links(
  populations,
  alpha = 0.05,
  method = "fisher",
  adjust_method = "none",
  batch_size = 1,
  n_permutations = 1000,
  a = 1,
  seed = NULL
)
}
\arguments{
\item{populations}{A named \code{list} with at least two elements. Each
element is itself a list of square, binary, symmetric adjacency matrices
(zero diagonal, no self-loops). All graphs must share the same number of
nodes.}

\item{alpha}{Numeric significance level used both for the global test and
for the iterative edge-removal stopping rule. Default \code{0.05}.}

\item{method}{Character string selecting the marginal edge test used to
rank candidate edges. One of \code{"fisher"} (default),
\code{"chi.squared"}, or \code{"prop"}. See
\code{\link{compute_edge_pvalues}}.}

\item{adjust_method}{Character string passed to \code{\link[stats]{p.adjust}}
for multiplicity correction of the marginal p-values. Default
\code{"none"}.}

\item{batch_size}{Positive integer giving the number of edges to drop per
iteration. Larger values speed up the procedure at the cost of coarser
resolution. Default \code{1}.}

\item{n_permutations}{Positive integer giving the number of permutation
replicates used to approximate the null distribution of T. Default
\code{1000}.}

\item{a}{Positive numeric normalisation constant for the test statistic T
(see \code{\link{compute_test_statistic}}). Default \code{1}.}

\item{seed}{Optional integer seed for reproducibility of the permutation
replicates. Default \code{NULL}.}
}
\value{
A \code{list} with three components: \code{critical_edges} (a
  \code{data.frame} with columns \code{node1}, \code{node2}, \code{p_value},
  listing the edges removed until the test became non-significant, ordered
  from most to least significant; \code{NULL} if the global test was not
  significant), \code{edges_removed} (a list of length-2 integer vectors
  giving the \code{(i, j)} indices of the removed edges, in removal order),
  and \code{modified_populations} (the input \code{populations} with the
  critical edges zeroed out in every graph).
}
\description{
Iteratively identifies the edges that drive the observed difference between
two or more populations of brain networks, using the permutation-based
L1-distance ANOVA test of Fraiman and Fraiman (2018). Edges are ranked by
their marginal p-value, then removed in batches until the global test is no
longer significant. The permutation null is re-evaluated incrementally via
a prefix-sum decomposition of T, which avoids recomputing the statistic
from scratch at every step.
}
\details{
The implementation exploits the fact that T decomposes as a sum of
  per-edge contributions \eqn{\Delta_e}. Removing an edge e is equivalent
  to subtracting \eqn{\Delta_e} from T, so prefix sums of the sorted
  \eqn{\Delta_e} values give the test statistic after any number of
  removals in O(1). The permutation null is built once via a single BLAS
  matrix multiplication and reused for every iteration, reducing the
  overall complexity from O(K * B * |E| * m) (naive) to O(B * |E| * m).

  Permutation replicates are generated by uniformly permuting the group
  labels across the pooled sample of all graphs, while preserving the
  original group sizes (sampling without replacement).
}
\examples{
\donttest{
set.seed(1)
control <- generate_category_graphs(
  n_graphs = 15, n_nodes = 10, n_communities = 2,
  base_intra_prob = 0.8, base_inter_prob = 0.2, seed = 1)
patient <- generate_category_graphs(
  n_graphs = 15, n_nodes = 10, n_communities = 2,
  base_intra_prob = 0.5, base_inter_prob = 0.5, seed = 2)
populations <- list(Control = control, Patient = patient)
result <- identify_critical_links(
  populations, alpha = 0.05, method = "fisher",
  n_permutations = 200, seed = 42)
head(result$critical_edges)
}
}
\references{
Fraiman, D. and Fraiman, R. (2018) An ANOVA approach for statistical
comparisons of brain networks. \emph{Scientific Reports}, 8, 4746.
\doi{10.1038/s41598-018-21688-0}.
}
\seealso{
\code{\link{compute_test_statistic}},
  \code{\link{compute_edge_pvalues}}, \code{\link{get_critical_nodes}}.
}
