% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-reports.R
\name{rater_halo_network_analysis}
\alias{rater_halo_network_analysis}
\title{Analyze rater-by-criterion halo-effect networks}
\usage{
rater_halo_network_analysis(
  fit,
  diagnostics = NULL,
  rater_facet = NULL,
  criterion_facet = NULL,
  context_facets = NULL,
  method = c("spearman", "pearson", "kendall"),
  min_pair_n = 5,
  alpha = 0.05,
  p_adjust = "bonferroni",
  min_abs_weight = 0,
  halo_weight_review = 0.5,
  halo_contrast_review = 0.1,
  min_retained_halo_edges = 1,
  positive_only = TRUE,
  include_graph = FALSE
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{diagnostics}{Optional output from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}.}

\item{rater_facet}{Name of the rater-like facet.}

\item{criterion_facet}{Name of the criterion, rubric, task, or item-like
facet used to form rater-by-criterion nodes.}

\item{context_facets}{Facets defining rows in the reshaped wide matrix.
Defaults to the person facet plus any facets other than the rater and
criterion facets.}

\item{method}{Correlation method used for rater-by-criterion node pairs.}

\item{min_pair_n}{Minimum shared contexts required to estimate a node-pair
relationship.}

\item{alpha}{Adjusted p-value threshold for retaining edges. Set to \code{1} to
retain all finite correlations after \code{min_abs_weight} filtering.}

\item{p_adjust}{Multiple-comparison adjustment passed to \code{\link[stats:p.adjust]{stats::p.adjust()}}.
The default \code{"bonferroni"} follows the conservative screening used in
Lamprianou's halo-network example.}

\item{min_abs_weight}{Minimum absolute correlation retained as a graph edge.}

\item{halo_weight_review}{Same-rater cross-criterion mean absolute
correlation at or above which a rater is marked for review.}

\item{halo_contrast_review}{Minimum difference between a rater's mean halo
edge weight and incident non-halo edge weight for a stronger review flag.}

\item{min_retained_halo_edges}{Minimum retained halo edges required before a
strong \code{"warning"} status is assigned.}

\item{positive_only}{If \code{TRUE}, negative correlations are kept in
\code{pair_metrics} but excluded from the graph edge table.}

\item{include_graph}{If \code{TRUE}, include the underlying \code{igraph} object.}
}
\value{
A bundle of class \code{mfrm_halo_network} containing:
\describe{
\item{\code{summary}}{One-row halo-network summary and halo/non-halo contrast.}
\item{\code{node_metrics}}{Rater-by-criterion node strength and centrality.}
\item{\code{edge_metrics}}{Retained graph edges.}
\item{\code{pair_metrics}}{All estimated node-pair correlations before edge
filtering.}
\item{\code{halo_summary_by_rater}}{Per-rater summaries of same-rater
criterion-pair edges, including \code{ReviewStatus} and \code{ReviewReason}.}
\item{\code{caveats}}{Interpretation notes.}
}
}
\description{
Analyze rater-by-criterion halo-effect networks
}
\details{
\code{rater_halo_network_analysis()} reshapes rating data so that each
rater-by-criterion combination is a node. Edges are correlations between
those node score vectors across shared contexts. Edges connecting two nodes
from the same rater but different criteria are labelled \code{"halo"}; all other
retained edges are labelled \code{"non_halo"}.

Per-rater \code{ReviewStatus} combines same-rater cross-criterion mean weight,
incident non-halo comparison weight, and the number of retained halo edges.
A \code{"warning"} means these criteria converge strongly enough to prioritize
follow-up; \code{"review"} means at least one screening criterion is elevated.
Neither label is a causal halo diagnosis.

The key descriptive comparison is the distribution of halo-edge weights
versus non-halo-edge weights. A larger halo-edge distribution is consistent
with a halo pattern, but this function deliberately reports it as a
screening diagnostic. The included Welch test is descriptive only because
edge weights are clustered by rater and node.
}
\examples{
\donttest{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 30)
if (requireNamespace("igraph", quietly = TRUE)) {
  halo <- rater_halo_network_analysis(fit)
  halo$summary
  head(halo$halo_summary_by_rater)
  plot(halo, type = "edge_distribution", draw = FALSE)
}
}
}
\references{
Lai, E. R., Wolfe, E. W., & Vickers, D. (2015). Differentiation of
illusory and true halo in writing scores. \emph{Educational and Psychological
Measurement, 75}(1), 102-125.

Lamprianou, I. (2025). Network Analysis for the investigation of rater
effects in language assessment: A comparison of ChatGPT vs human raters.
\emph{Research Methods in Applied Linguistics, 4}, 100205.
}
\seealso{
\code{\link[=rater_network_analysis]{rater_network_analysis()}}, \code{\link[=interrater_agreement_table]{interrater_agreement_table()}},
\code{\link[=plot.mfrm_bundle]{plot.mfrm_bundle()}}
}
