% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot_critical_edges.R
\name{plot_critical_edges}
\alias{plot_critical_edges}
\title{Visualize Central Graphs and Critical Edges}
\usage{
plot_critical_edges(
  populations,
  critical_links,
  communities = NULL,
  layout = NULL,
  central_graphs = NULL,
  reference = 1L,
  threshold = 0.5,
  edge_scale = 6,
  critical_color = "red",
  critical_width = 3,
  background_color = "grey80",
  background_width = 1,
  vertex_size = 12,
  vertex_label = TRUE,
  panel_titles = NULL,
  mfrow = NULL,
  ...
)
}
\arguments{
\item{populations}{A named \code{list} of populations of adjacency matrices,
as accepted by \code{\link{identify_critical_links}}. Used to compute the
per-population central graphs unless \code{central_graphs} is supplied.}

\item{critical_links}{The object returned by
\code{\link{identify_critical_links}}. Its \code{critical_edges} component
provides the edges to highlight in the final panel.}

\item{communities}{Optional integer (or factor) vector of length
\code{n_nodes} giving the community membership of every node. Used to
color vertices consistently across panels. Default \code{NULL} (all
vertices share the default \pkg{igraph} color).}

\item{layout}{Optional layout for the graphs. Either an
\code{n_nodes x 2} numeric matrix of vertex coordinates (recommended, so
that all panels share the same node positions) or an \pkg{igraph} layout
function such as \code{\link[igraph]{layout_with_fr}}. Default
\code{\link[igraph]{layout_in_circle}}.}

\item{central_graphs}{Optional list of pre-computed central graphs (one per
population). If \code{NULL}, they are computed via
\code{\link{compute_central_graph}}.}

\item{reference}{Either an integer index or a name selecting which
population's central graph is used as the background of the
critical-edges panel. Default \code{1L} (the first population).}

\item{threshold}{Numeric in \code{[0, 1]}. The reference central graph is
binarised by \code{> threshold} for the critical-edges panel. Default
\code{0.5}.}

\item{edge_scale}{Numeric multiplier applied to the central-graph edge
weights to set \code{edge.width} in the per-population panels. Default
\code{6}.}

\item{critical_color, critical_width}{Color and line width used to draw
critical edges. Defaults \code{"red"} and \code{3}.}

\item{background_color, background_width}{Color and line width used to draw
non-critical edges in the critical panel. Defaults \code{"grey80"} and
\code{1}.}

\item{vertex_size}{Vertex size passed to \code{\link[igraph]{plot.igraph}}.
Default \code{12}.}

\item{vertex_label}{Logical. If \code{TRUE} (default) vertex indices are
shown; otherwise vertex labels are suppressed.}

\item{panel_titles}{Optional character vector of length
\code{length(populations) + 1} with custom panel titles. Default uses
\code{paste(names(populations), "Central Graph")} followed by
\code{"Critical edges"}.}

\item{mfrow}{Optional integer vector of length 2 giving the
\code{c(nrow, ncol)} arrangement passed to \code{\link[graphics]{par}}.
By default a near-square grid is chosen automatically (e.g.\ a
\code{2 x 2} grid for two populations, matching the standard
Control / Patient / Critical layout).}

\item{...}{Additional arguments forwarded to
\code{\link[igraph]{plot.igraph}}. Note that \code{edge.width},
\code{vertex.color}, \code{vertex.size}, \code{vertex.label} and
\code{layout} are managed by this function and should not be passed via
\code{...}.}
}
\value{
Invisibly returns \code{NULL}; called for its side effect of
  producing the multi-panel plot.
}
\description{
Produces a multi-panel figure summarising the output of
\code{\link{identify_critical_links}}: one panel per population showing the
weighted central graph, plus a final panel that highlights the critical
edges on a chosen reference central graph. This is the canonical
visualization of the \pkg{BrainNetTest} workflow and replaces the manual
\pkg{igraph} plumbing required to build the same figure.
}
\details{
The first \code{length(populations)} panels show the weighted
  central graph of each population, with edge widths proportional to the
  central-graph weights. The final panel binarises the chosen reference
  central graph at \code{threshold} and overlays the critical edges
  returned by \code{identify_critical_links()} in
  \code{critical_color}. Critical edges that are absent from the binarised
  reference graph are added so that they remain visible.

  The graphics state (\code{par(mfrow, mar, oma)}) is restored on exit.
}
\examples{
\donttest{
set.seed(123)
community_sizes <- c(4, 2, 3, 3, 5)
control <- generate_category_graphs(
  n_graphs = 50, n_nodes = 17, n_communities = 5,
  community_sizes = community_sizes,
  base_intra_prob = rep(0.70, 5), base_inter_prob = 0.05,
  intra_prob_variation = 0.02, inter_prob_variation = 0.01)
patient <- generate_category_graphs(
  n_graphs = 50, n_nodes = 17, n_communities = 5,
  community_sizes = community_sizes,
  base_intra_prob = c(0.40, 0.70, 0.70, 0.70, 0.70),
  base_inter_prob = 0.05,
  intra_prob_variation = 0.02, inter_prob_variation = 0.01)
populations <- list(Control = control, Patient = patient)
result <- identify_critical_links(populations, alpha = 0.05,
  method = "fisher", n_permutations = 200, seed = 1)
communities <- rep(seq_along(community_sizes), times = community_sizes)
plot_critical_edges(populations, result, communities = communities)
}
}
\seealso{
\code{\link{identify_critical_links}},
  \code{\link{compute_central_graph}},
  \code{\link{get_critical_nodes}}.
}
