% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-reference-benchmark.R
\name{reference_case_benchmark}
\alias{reference_case_benchmark}
\title{Benchmark packaged reference cases}
\usage{
reference_case_benchmark(
  cases = c("synthetic_truth", "synthetic_latent_regression", "synthetic_bias_contract",
    "study1_itercal_pair", "study2_itercal_pair", "combined_itercal_pair"),
  method = "MML",
  model = "RSM",
  quad_points = 7,
  maxit = 40,
  reltol = 1e-06,
  mml_engine = c("direct", "em", "hybrid")
)
}
\arguments{
\item{cases}{Reference cases to run. Defaults to the standard
\code{RSM}-compatible reference suite. Specialized \code{GPCM} and
ConQuest-overlap package-side cases can be requested explicitly.}

\item{method}{Estimation method passed to \code{\link[=fit_mfrm]{fit_mfrm()}}. Defaults to \code{"MML"}.}

\item{model}{Model family passed to \code{\link[=fit_mfrm]{fit_mfrm()}}. Defaults to \code{"RSM"}.}

\item{quad_points}{Quadrature points for \code{method = "MML"}.}

\item{maxit}{Maximum optimizer iterations passed to \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{reltol}{Convergence tolerance passed to \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{mml_engine}{MML optimization engine passed to \code{\link[=fit_mfrm]{fit_mfrm()}}. Applies
only when \code{method = "MML"}.}
}
\value{
An object of class \code{mfrm_reference_benchmark}.
}
\description{
Benchmark packaged reference cases
}
\details{
This function checks \code{mfrmr} against the package's curated reference case
families:
\itemize{
\item \code{synthetic_truth}: checks whether recovered facet measures align with the
known generating values from the package's synthetic design.
\item \code{synthetic_latent_regression}: checks whether the first-version
latent-regression \code{MML} branch recovers known population coefficients,
residual latent variance, criterion ordering, and posterior-shift
direction from a synthetic overlap case.
\item \code{synthetic_latent_regression_omit}: checks whether the population-model
complete-case omission policy is reflected in the fitted metadata,
response-row review, active person estimates, and replay provenance.
\item \code{synthetic_conquest_overlap_dry_run}: builds the narrow ConQuest-overlap
bundle for the latent-regression synthetic case, round-trips package tables
through the normalization/review helpers, and confirms the package-side
workflow without claiming that ConQuest itself was executed.
\item \code{synthetic_gpcm}: checks whether the bounded \code{GPCM} branch recovers
known criterion-specific slopes, row-centered step parameters, and
criterion ordering from a synthetic overlap case. This case
currently requires \code{model = "GPCM"} and is intended for \code{method = "MML"}.
\item \code{synthetic_bias_contract}: checks whether package bias tables and
pairwise local comparisons satisfy the identities documented in the bias
help workflow.
\item \verb{*_itercal_pair}: compares a baseline packaged dataset with its iterative
recalibration counterpart to review fit stability, facet-measure
alignment, and linking coverage together.
}

The resulting object is intended as a reference-case check for package
behavior. It does not by itself establish
external validity against FACETS, ConQuest, or published calibration
studies, and it does not assume any familiarity with external table
numbering or printer layouts.
When specialized latent-regression omission or ConQuest-overlap package-side
cases are requested, \code{summary(bench)} prints preview rows from
\code{population_policy_checks} and \code{conquest_overlap_checks} alongside the
reference notes so the package-versus-external validation boundary remains
visible.
}
\section{Interpreting output}{

\itemize{
\item \code{overview}: one-row reference-case summary.
\item \code{case_summary}: pass/warn/fail triage by reference case.
\item \code{fit_runs}: fitted-run metadata (fit, precision tier, convergence, and
latent-regression population-model/posterior-basis fields, including
categorical-coding details when present).
\item \code{design_checks}: exact design recovery checks for each dataset.
\item \code{recovery_checks}: known-truth recovery metrics for the synthetic cases,
including the latent-regression reference case.
\item \code{bias_checks}: source-backed bias/local-measure identity checks.
\item \code{pair_checks}: paired-dataset stability screens for the iterated cases.
\item \code{linking_checks}: common-element reviews for paired calibration datasets.
\item \code{conquest_overlap_checks}: package-side checks for the
ConQuest-overlap bundle/normalization/review workflow; this remains a
package-side check until actual ConQuest output tables are supplied.
\item \code{population_policy_checks}: complete-case omission checks for population
model benchmark fixtures.
\item \code{source_profile}: source-backed rules used by the reference checks.
}
}

\examples{
\donttest{
bench <- reference_case_benchmark(
  cases = "synthetic_truth",
  method = "JML",
  maxit = 30
)
summary(bench)
}
}
