% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-advanced.R
\name{build_weighting_review}
\alias{build_weighting_review}
\title{Build a weighting-policy review between Rasch-family and bounded GPCM fits}
\usage{
build_weighting_review(
  rasch_fit,
  gpcm_fit,
  theta_range = c(-6, 6),
  theta_points = 101L,
  top_n = 10L
)
}
\arguments{
\item{rasch_fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}} using \code{model = "RSM"} or \code{"PCM"}.}

\item{gpcm_fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}} using bounded \code{model = "GPCM"}.}

\item{theta_range}{Numeric vector of length 2 passed to \code{\link[=compute_information]{compute_information()}}
for the information-redistribution comparison.}

\item{theta_points}{Integer number of theta grid points passed to
\code{\link[=compute_information]{compute_information()}}.}

\item{top_n}{Maximum number of rows to keep in compact summary outputs.}
}
\value{
An object of class \code{mfrm_weighting_review}.
}
\description{
Build a weighting-policy review between Rasch-family and bounded GPCM fits
}
\details{
\code{build_weighting_review()} is an operational model-choice review helper. It
is designed for the common question:
\itemize{
\item what changes when a Rasch-family equal-weighting model is replaced with a
bounded \code{GPCM} that allows discrimination-based reweighting?
}

The helper does not estimate a new model. Instead, it synthesizes four
package-native evidence sources:
\itemize{
\item \code{\link[=compare_mfrm]{compare_mfrm()}} for same-data model comparison
\item the non-person facet measures from each fit
\item the bounded \code{GPCM} slope table
\item \code{\link[=compute_information]{compute_information()}} for design-weighted information redistribution
}

The result is intended for substantive review, not for automatic model
selection. In particular, a better-fitting \code{GPCM} should not by itself be
interpreted as a reason to discard an equal-weighting Rasch-family route.
}
\section{Recommended input route}{

\enumerate{
\item Fit an equal-weighting reference model with \code{model = "RSM"} or \code{"PCM"}.
\item Fit a bounded \code{GPCM} on the same prepared response data.
\item Run \code{build_weighting_review(rasch_fit, gpcm_fit)}.
\item Read \code{summary(review)} before deciding whether the discrimination-based
reweighting is substantively acceptable.
}
}

\section{What the returned tables mean}{

\itemize{
\item \code{model_comparison}: same-data model-comparison bundle from \code{\link[=compare_mfrm]{compare_mfrm()}}.
\item \code{facet_shift}: how non-person facet estimates move under bounded \code{GPCM}.
\item \code{slope_profile}: which \code{slope_facet} levels are upweighted or downweighted.
\item \code{information_redistribution}: within-facet information-share changes
between the Rasch-family fit and bounded \code{GPCM}.
\item \code{top_reweighted_levels}: compact triage table for the strongest
slope-facet-level redistribution signals.
}
}

\section{GPCM boundary}{

This helper is available only for the current bounded \code{GPCM} branch. It
requires the package's existing \code{slope_facet == step_facet} contract and
should be read as an operational weighting-policy review, not as a formal
validity adjudication.
}

\examples{
\donttest{
toy <- load_mfrmr_data("example_core")
rasch_fit <- fit_mfrm(
  toy,
  "Person",
  c("Rater", "Criterion"),
  "Score",
  method = "MML",
  model = "RSM",
  quad_points = 9
)
gpcm_fit <- fit_mfrm(
  toy,
  "Person",
  c("Rater", "Criterion"),
  "Score",
  method = "MML",
  model = "GPCM",
  step_facet = "Criterion",
  slope_facet = "Criterion",
  quad_points = 9
)
review <- build_weighting_review(rasch_fit, gpcm_fit, theta_points = 41)
summary(review)
review$top_reweighted_levels
}
}
\seealso{
\code{\link[=compare_mfrm]{compare_mfrm()}}, \code{\link[=compute_information]{compute_information()}}, \code{\link[=gpcm_capability_matrix]{gpcm_capability_matrix()}}
}
