% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-advanced.R
\name{build_model_choice_review}
\alias{build_model_choice_review}
\title{Build a model-choice review across RSM, PCM, and bounded GPCM fits}
\usage{
build_model_choice_review(
  ...,
  labels = NULL,
  run_weighting_review = NULL,
  theta_range = c(-6, 6),
  theta_points = 61L,
  top_n = 10L,
  warn_constraints = TRUE
)
}
\arguments{
\item{...}{Two or more fitted \code{mfrm_fit} objects from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{labels}{Optional labels for the supplied fits. If omitted, names from
\code{...} are used when available; otherwise labels are generated from
model/method combinations.}

\item{run_weighting_review}{Logical. If \code{TRUE} and the supplied fits include
at least one \code{RSM}/\code{PCM} reference plus one bounded \code{GPCM} fit, also run
\code{\link[=build_weighting_review]{build_weighting_review()}} for the first such pair.}

\item{theta_range, theta_points, top_n}{Passed to \code{\link[=build_weighting_review]{build_weighting_review()}} when
\code{run_weighting_review = TRUE}.}

\item{warn_constraints}{Passed to \code{\link[=compare_mfrm]{compare_mfrm()}}.}
}
\value{
An object of class \code{mfrm_model_choice_review}.
}
\description{
Build a model-choice review across RSM, PCM, and bounded GPCM fits
}
\details{
\code{build_model_choice_review()} is a user-facing synthesis helper. It does not
estimate new models. It bundles:
\itemize{
\item \code{\link[=compare_mfrm]{compare_mfrm()}} for AIC/BIC/log-likelihood comparison;
\item model-role guidance for \code{RSM}, \code{PCM}, and bounded \code{GPCM};
\item downstream-route availability for APA output, score-side export, linking,
recovery, fair averages, bias screening, and summary-appendix handoff;
\item report wording templates that avoid treating better bounded-\code{GPCM} fit as
an automatic operational-scoring decision;
\item \code{\link[=gpcm_capability_matrix]{gpcm_capability_matrix()}} when bounded \code{GPCM} is present;
\item optionally, \code{\link[=build_weighting_review]{build_weighting_review()}} for the first Rasch-family reference
versus bounded-\code{GPCM} pair.
}

The word "bounded" is intentional: the package implements a bounded GPCM
route, not every possible generalized partial-credit many-facet extension.
The current route uses positive slopes, requires \code{slope_facet == step_facet},
identifies slopes on the log scale with geometric mean 1, and keeps several
downstream score-side/reporting helpers outside the validated boundary.
}
\examples{
\donttest{
toy <- load_mfrmr_data("example_core")
fit_rsm <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                    method = "MML", model = "RSM", quad_points = 7)
fit_pcm <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                    method = "MML", model = "PCM", step_facet = "Criterion",
                    quad_points = 7)
review <- build_model_choice_review(RSM = fit_rsm, PCM = fit_pcm)
summary(review)
}
}
\seealso{
\code{\link[=compare_mfrm]{compare_mfrm()}}, \code{\link[=build_weighting_review]{build_weighting_review()}},
\code{\link[=gpcm_capability_matrix]{gpcm_capability_matrix()}}, \code{\link[=compute_information]{compute_information()}}
}
