% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-advanced.R
\name{build_linking_review}
\alias{build_linking_review}
\title{Build a linking-review synthesis object}
\usage{
build_linking_review(
  anchor_review = NULL,
  drift = NULL,
  chain = NULL,
  top_n = 10
)
}
\arguments{
\item{anchor_review}{Optional output from \code{\link[=review_mfrm_anchors]{review_mfrm_anchors()}}.}

\item{drift}{Optional output from \code{\link[=detect_anchor_drift]{detect_anchor_drift()}}.}

\item{chain}{Optional output from \code{\link[=build_equating_chain]{build_equating_chain()}}.}

\item{top_n}{Maximum number of linking-risk rows to highlight in summary
outputs. The full object keeps the full risk tables.}
}
\value{
An object of class \code{mfrm_linking_review}.
}
\description{
Build a linking-review synthesis object
}
\details{
\code{build_linking_review()} does not recompute anchor, drift, or chain
statistics. It is a synthesis layer that organizes package-native evidence
into one operational review surface with:
\itemize{
\item a front-door status block,
\item ranked linking risks,
\item explicit next actions,
\item plot routing metadata,
\item a reporting/export handoff map.
}

The helper keeps the current conservative interpretation policy:
anchor drift and screened links are operational review tools, not automatic
proofs of scale equivalence or score comparability.
}
\section{Recommended input route}{

Use existing package-native outputs in this order:
\enumerate{
\item \code{\link[=review_mfrm_anchors]{review_mfrm_anchors()}} for pre-fit anchor adequacy.
\item \code{\link[=detect_anchor_drift]{detect_anchor_drift()}} for direct wave-to-reference drift screening.
\item \code{\link[=build_equating_chain]{build_equating_chain()}} for adjacent screened-link review across waves.
}
}

\section{Interpreting output}{

\itemize{
\item \code{overview}: which evidence sources were supplied and the current review status.
\item \code{top_linking_risks}: primary operational triage table.
\item \code{group_view_index}: stable wave/link/facet/source-family grouping routes.
\item \code{plot_map}: which existing plotting helper should be used next.
\item \code{reporting_map}: what is covered here versus which manuscript-oriented
helper should be used separately.
}
}

\section{GPCM boundary}{

This helper is currently intended for the validated \code{RSM} / \code{PCM} linking
workflow. If the supplied drift/chain sources resolve to bounded \code{GPCM},
the helper stops with a package-level message rather than silently implying
support.
}

\examples{
\donttest{
d1 <- load_mfrmr_data("study1")
d2 <- load_mfrmr_data("study2")
fit1 <- fit_mfrm(d1, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", maxit = 30)
fit2 <- fit_mfrm(d2, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", maxit = 30)
anchor_review_obj <- review_mfrm_anchors(d1, "Person", c("Rater", "Criterion"), "Score")
drift <- detect_anchor_drift(list(Wave1 = fit1, Wave2 = fit2))
chain <- build_equating_chain(list(Wave1 = fit1, Wave2 = fit2))
review <- build_linking_review(anchor_review = anchor_review_obj, drift = drift, chain = chain)
summary(review)
review$top_linking_risks
review$group_view_index
}
}
\seealso{
\code{\link[=review_mfrm_anchors]{review_mfrm_anchors()}}, \code{\link[=detect_anchor_drift]{detect_anchor_drift()}},
\code{\link[=build_equating_chain]{build_equating_chain()}}, \code{\link[=plot_anchor_drift]{plot_anchor_drift()}}, \link{mfrmr_linking_and_dff}
}
