% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-export-bundles.R
\name{review_conquest_overlap}
\alias{review_conquest_overlap}
\title{Review an exact-overlap ConQuest comparison against an \code{mfrmr} overlap bundle}
\usage{
review_conquest_overlap(
  bundle,
  conquest_population = NULL,
  conquest_item_estimates = NULL,
  conquest_case_eap = NULL,
  conquest_population_term = "auto",
  conquest_population_estimate = "auto",
  conquest_item_id = "auto",
  conquest_item_estimate = "auto",
  item_id_source = c("auto", "response_var", "level"),
  conquest_case_person = "auto",
  conquest_case_estimate = "auto"
)
}
\arguments{
\item{bundle}{Output from \code{\link[=build_conquest_overlap_bundle]{build_conquest_overlap_bundle()}}.}

\item{conquest_population}{Normalized ConQuest population-parameter table as a
data.frame, or output from \code{\link[=normalize_conquest_overlap_tables]{normalize_conquest_overlap_tables()}}.}

\item{conquest_item_estimates}{Normalized ConQuest item-estimate table as a
data.frame. Leave \code{NULL} when \code{conquest_population} is an object from
\code{\link[=normalize_conquest_overlap_tables]{normalize_conquest_overlap_tables()}}.}

\item{conquest_case_eap}{Normalized ConQuest case-level EAP table as a
data.frame. Leave \code{NULL} when \code{conquest_population} is an object from
\code{\link[=normalize_conquest_overlap_tables]{normalize_conquest_overlap_tables()}}.}

\item{conquest_population_term}{Column in \code{conquest_population} that stores
parameter names. \code{"auto"} tries conservative aliases such as \code{Parameter}
and \code{Term}.}

\item{conquest_population_estimate}{Column in \code{conquest_population} that
stores parameter estimates. \code{"auto"} tries aliases such as \code{Estimate} and
\code{Est}.}

\item{conquest_item_id}{Column in \code{conquest_item_estimates} that stores the
item identifier. This may be the exported response variable (for example
\code{I001}) or the original item/facet level. \code{"auto"} tries aliases such as
\code{ResponseVar}, \code{ItemID}, \code{Item}, and \code{Label}.}

\item{conquest_item_estimate}{Column in \code{conquest_item_estimates} that stores
the item estimate. \code{"auto"} tries aliases such as \code{Estimate}, \code{Est}, and
\code{Facility}.}

\item{item_id_source}{How \code{conquest_item_id} should be matched. \code{"auto"}
chooses the larger overlap between exported response variables and original
item levels, with ties resolved toward exported response variables.}

\item{conquest_case_person}{Column in \code{conquest_case_eap} that stores person
IDs. \code{"auto"} tries conservative aliases such as \code{Person}, \code{PID}, and
\verb{Sequence ID}.}

\item{conquest_case_estimate}{Column in \code{conquest_case_eap} that stores case
EAP estimates. \code{"auto"} tries conservative aliases such as \code{Estimate},
\code{EAP_1}, and \code{EAP}.}
}
\value{
A named list with class \code{mfrm_conquest_overlap_review}.
}
\description{
Review an exact-overlap ConQuest comparison against an \code{mfrmr} overlap bundle
}
\details{
This helper compares normalized ConQuest output tables against the exact-
overlap bundle produced by \code{\link[=build_conquest_overlap_bundle]{build_conquest_overlap_bundle()}}. It is
intentionally conservative:
\itemize{
\item it does \strong{not} parse raw ConQuest text output automatically;
\item it expects already normalized data frames or output from
\code{\link[=normalize_conquest_overlap_tables]{normalize_conquest_overlap_tables()}};
\item and it reports numerical differences and missing elements without claiming
that any fixed tolerance implies software equivalence.
}

This is the package's external-table review path. It is distinct from
\code{reference_case_benchmark(cases = "synthetic_conquest_overlap_dry_run")},
which only round-trips package-native tables through the same normalization
and review contract without executing ConQuest.

The intended workflow is:
\enumerate{
\item export an exact-overlap bundle with \code{\link[=build_conquest_overlap_bundle]{build_conquest_overlap_bundle()}};
\item run the narrow matching case in ConQuest;
\item normalize the resulting ConQuest outputs into data frames;
\item pass those tables here to inspect direct differences, centered item
agreement, and case-level EAP agreement.
}
}
\section{Output}{

The returned object has class \code{mfrm_conquest_overlap_review} and includes:
\itemize{
\item \code{overall}: one-row comparison summary with missing/duplicate/non-numeric
attention-item counts and worst-row labels
\item \code{population_comparison}: parameter-by-parameter comparison table
\item \code{item_comparison}: centered item-estimate comparison table
\item \code{case_comparison}: case-level EAP comparison table
\item \code{attention_items}: missing, malformed, or unmatched elements
\item \code{settings}: review settings
\item \code{notes}: interpretation notes
}
}

\section{Interpretation}{

\itemize{
\item Read \code{summary(review)$review_scope} first to confirm that the result is a
supplied-table review, not raw ConQuest text parsing or a software-
equivalence claim.
\item Population slopes and \code{sigma2} are intended for direct comparison.
\item Item estimates should be interpreted after centering.
\item Case estimates should be interpreted as posterior EAP summaries under the
fitted population model.
\item The \code{overall} table reports both mean and maximum absolute differences for
compared population, centered item, and case rows. The
\code{PopulationMaxAbsParameter}, \code{ItemCenteredMaxAbsItem}, and
\code{CaseMaxAbsPerson} columns identify the row where each maximum absolute
difference occurs.
\item Missing or non-numeric rows in \code{attention_items} indicate that the external
tables do not yet align cleanly with the exported overlap bundle.
}
}

\examples{
\donttest{
bundle <- build_conquest_overlap_bundle()
raw_pop <- data.frame(
  Term = bundle$mfrmr_population$Parameter,
  Est = bundle$mfrmr_population$Estimate
)
raw_item <- data.frame(
  Item = bundle$mfrmr_item_estimates$ResponseVar,
  Est = bundle$mfrmr_item_estimates$Estimate
)
raw_case <- data.frame(
  PID = bundle$mfrmr_case_eap$Person,
  EAP = bundle$mfrmr_case_eap$Estimate
)
normalized <- normalize_conquest_overlap_tables(
  conquest_population = raw_pop,
  conquest_item_estimates = raw_item,
  conquest_case_eap = raw_case,
  conquest_population_term = "Term",
  conquest_population_estimate = "Est",
  conquest_item_id = "Item",
  conquest_item_estimate = "Est",
  conquest_case_person = "PID",
  conquest_case_estimate = "EAP"
)
review <- review_conquest_overlap(bundle, normalized)
summary(review)$summary
}
}
\seealso{
\code{\link[=build_conquest_overlap_bundle]{build_conquest_overlap_bundle()}},
\code{\link[=normalize_conquest_overlap_files]{normalize_conquest_overlap_files()}}, \code{\link[=normalize_conquest_overlap_tables]{normalize_conquest_overlap_tables()}},
\code{\link[=reference_case_benchmark]{reference_case_benchmark()}}
}
