% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-export-bundles.R
\name{build_conquest_overlap_bundle}
\alias{build_conquest_overlap_bundle}
\title{Build a scoped ConQuest-overlap bundle}
\usage{
build_conquest_overlap_bundle(
  fit = NULL,
  case = c("synthetic_latent_regression"),
  output_dir = NULL,
  prefix = "conquest_overlap",
  overwrite = FALSE,
  quad_points = 7L,
  maxit = 40L,
  reltol = 1e-06
)
}
\arguments{
\item{fit}{Optional output from \code{\link[=fit_mfrm]{fit_mfrm()}} or \code{\link[=run_mfrm_facets]{run_mfrm_facets()}}. When
omitted, the helper builds the package's
\code{"synthetic_latent_regression"} overlap case.}

\item{case}{Overlap case used when \code{fit = NULL}. Currently only
\code{"synthetic_latent_regression"} is supported.}

\item{output_dir}{Optional directory where the bundle files should be
written. When \code{NULL}, the helper returns the in-memory bundle only.}

\item{prefix}{File-name prefix used when writing the bundle to disk.}

\item{overwrite}{If \code{FALSE}, refuse to overwrite existing files.}

\item{quad_points}{Quadrature points used when \code{fit = NULL} and the
overlap case is fit on the fly.}

\item{maxit}{Maximum optimizer iterations used when \code{fit = NULL}.}

\item{reltol}{Relative convergence tolerance used when \code{fit = NULL}.}
}
\value{
A named list with class \code{mfrm_conquest_overlap_bundle}.
}
\description{
Build a scoped ConQuest-overlap bundle
}
\details{
This helper prepares a narrow ConQuest comparison bundle for an \code{RSM} / \code{PCM}
latent-regression \code{MML} fit and records the \code{mfrmr}-side tables to compare
after an external ConQuest run. The supported overlap is intentionally
narrow:
\itemize{
\item ordered-response \code{RSM} / \code{PCM} only;
\item binary responses only;
\item exactly one non-person facet, treated as the item facet;
\item active latent-regression \code{MML};
\item exactly one numeric person covariate beyond the intercept;
\item complete person-by-item rectangular data.
}

The returned bundle standardizes the responses to \verb{\{0, 1\}}, pivots them to a
one-row-per-person wide CSV, stores the corresponding person covariates, and
records the \code{mfrmr} estimates that should be compared externally.

The \code{conquest_command} component is a conservative starting template, not a
guaranteed version-invariant automation. The \code{conquest_output_contract}
component records which requested external output should feed each
normalized review table.
Use \code{\link[=normalize_conquest_overlap_files]{normalize_conquest_overlap_files()}} or
\code{\link[=normalize_conquest_overlap_tables]{normalize_conquest_overlap_tables()}} and then \code{\link[=review_conquest_overlap]{review_conquest_overlap()}} only
after the matching ConQuest run has been executed externally and the relevant
output tables have been extracted. The bundle and command template alone are
not external validation evidence.
}
\section{Comparison targets}{

\itemize{
\item regression slope: compare directly;
\item residual variance \code{sigma2}: compare directly;
\item item estimates: compare after centering because the Rasch location origin
remains constraint-dependent;
\item case EAP estimates: compare as posterior summaries under the fitted
population model.
}
}

\section{Output}{

The returned object has class \code{mfrm_conquest_overlap_bundle} and includes:
\itemize{
\item \code{summary}: one-row scope summary with posterior-basis and
population-model review fields
\item \code{comparison_targets}: comparison rules for the exported tables
\item \code{conquest_output_contract}: requested ConQuest outputs and review handoff
\item \code{response_long}: long-format binary response data used by the bundle
\item \code{response_wide}: wide CSV-ready response matrix for the ConQuest template
\item \code{person_data}: one-row-per-person covariate table
\item \code{item_map}: mapping from exported response columns to original item levels
\item \code{mfrmr_population}: fitted population-model coefficients plus \code{sigma2}
\item \code{mfrmr_item_estimates}: fitted item estimates with centered values
\item \code{mfrmr_case_eap}: posterior EAP summaries for the fitted persons
\item \code{conquest_command}: conservative ConQuest command template
\item \code{written_files}: file inventory when \code{output_dir} is supplied
\item \code{settings}: bundle settings
\item \code{notes}: interpretation notes
}
}

\examples{
\donttest{
bundle <- build_conquest_overlap_bundle(quad_points = 3, maxit = 30)
bundle$summary[, c("Case", "Facet", "Covariate", "Persons", "Items")]
summary(bundle)$conquest_command_scope
summary(bundle)$conquest_output_contract
cat(substr(bundle$conquest_command, 1, 120))
}
}
\seealso{
\code{\link[=normalize_conquest_overlap_files]{normalize_conquest_overlap_files()}},
\code{\link[=normalize_conquest_overlap_tables]{normalize_conquest_overlap_tables()}}, \code{\link[=review_conquest_overlap]{review_conquest_overlap()}},
\code{\link[=reference_case_benchmark]{reference_case_benchmark()}}, \code{\link[=build_mfrm_replay_script]{build_mfrm_replay_script()}},
\code{\link[=export_mfrm_bundle]{export_mfrm_bundle()}}
}
