% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-advanced.R
\name{build_misfit_casebook}
\alias{build_misfit_casebook}
\title{Build a case-level misfit review bundle}
\usage{
build_misfit_casebook(
  fit,
  diagnostics = NULL,
  unexpected = NULL,
  displacement = NULL,
  administration_id = NULL,
  wave_id = NULL,
  top_n = 25
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

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

\item{unexpected}{Optional output from \code{\link[=unexpected_response_table]{unexpected_response_table()}}.}

\item{displacement}{Optional output from \code{\link[=displacement_table]{displacement_table()}}.}

\item{administration_id}{Optional scalar identifier describing the current
administration or form. It is stored in row-level provenance and summary
outputs when supplied.}

\item{wave_id}{Optional scalar identifier for the current wave or occasion.
It is stored in row-level provenance and summary outputs when supplied.}

\item{top_n}{Maximum number of rows to keep in compact summary outputs.}
}
\value{
An object of class \code{mfrm_misfit_casebook}.
}
\description{
Build a case-level misfit review bundle
}
\details{
\code{build_misfit_casebook()} is a synthesis layer over package-native screening
outputs. It does not invent a new misfit statistic. Instead, it organizes
existing evidence families into one case-level review surface:
\itemize{
\item element-level Infit / Outfit MnSq misfit from \code{diagnostics$fit}
(rows whose Infit or Outfit MnSq falls outside the 0.5-1.5 Linacre
acceptance band)
\item strict marginal cell screens from \code{diagnostics$marginal_fit$top_cells}
\item strict pairwise screens from \code{diagnostics$marginal_fit$pairwise$top_pairs}
\item unexpected responses from \code{\link[=unexpected_response_table]{unexpected_response_table()}}
\item displacement flags from \code{\link[=displacement_table]{displacement_table()}}
}

The result is an operational review bundle. It is not a formal adjudication
system, and repeated signals across evidence families should be prioritized
over any single isolated case row. In addition to raw case rows, the object
includes stable grouping views such as \code{by_person}, \code{by_facet_level},
\code{by_source_family}, and \code{by_wave} to support operational triage. The
\code{source_support} component records which evidence families are currently
supported, caveated, or deferred under the active model.
}
\section{Recommended input route}{

\enumerate{
\item Fit with \code{\link[=fit_mfrm]{fit_mfrm()}}.
\item Build diagnostics with \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}.
\item Optionally build \code{\link[=unexpected_response_table]{unexpected_response_table()}} and \code{\link[=displacement_table]{displacement_table()}}
yourself when you want custom thresholds before synthesizing the casebook.
}
}

\section{GPCM boundary}{

For bounded \code{GPCM}, the helper is available with caveat. The casebook inherits
exploratory screening semantics from the underlying residual and strict
marginal sources; it should not be read as a formal inferential case test.
}

\examples{
\donttest{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "MML", model = "RSM", quad_points = 5)
diag <- diagnose_mfrm(fit, diagnostic_mode = "both", residual_pca = "none")
casebook <- build_misfit_casebook(fit, diagnostics = diag, top_n = 10)
summary(casebook)
casebook$top_cases
}
}
\seealso{
\code{\link[=diagnose_mfrm]{diagnose_mfrm()}}, \code{\link[=unexpected_response_table]{unexpected_response_table()}},
\code{\link[=displacement_table]{displacement_table()}}, \code{\link[=plot_unexpected]{plot_unexpected()}}, \code{\link[=plot_displacement]{plot_displacement()}},
\code{\link[=plot_marginal_fit]{plot_marginal_fit()}}, \code{\link[=plot_marginal_pairwise]{plot_marginal_pairwise()}}
}
