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-09
)

Arguments

fit: Optional output from fit_mfrm() or run_mfrm_facets(). When omitted, the helper builds the package's "synthetic_latent_regression" overlap case.
case: Overlap case used when fit = NULL. Currently only "synthetic_latent_regression" is supported.
output_dir: Optional directory where the bundle files should be written. When NULL, the helper returns the in-memory bundle only.
prefix: File-name prefix used when writing the bundle to disk.
overwrite: If FALSE, refuse to overwrite existing files.
quad_points: Quadrature points used when fit = NULL and the overlap case is fit on the fly.
maxit: Maximum optimizer iterations used when fit = NULL. The fitted object's actual value is recorded in the returned summary and settings.
reltol: Relative convergence tolerance used when fit = NULL. Default 1e-9. The fitted object's actual value is recorded in the returned summary and settings.

Value

A named list with class mfrm_conquest_overlap_bundle.

Details

This helper prepares a narrow ConQuest comparison bundle for an RSM / PCM latent-regression MML fit and records the mfrmr-side tables to compare after an external ConQuest run. The supported overlap is intentionally narrow:

ordered-response RSM / PCM only;
binary responses only;
exactly one non-person facet, treated as the item facet;
active latent-regression MML;
exactly one numeric person covariate beyond the intercept;
complete person-by-item rectangular data.

The returned bundle standardizes the responses to {0, 1}, pivots them to a one-row-per-person wide CSV, stores the corresponding person covariates, and records the mfrmr estimates that should be compared externally. It also records the actual mfrmr optimizer controls, MML engine, terminal gradient, convergence status and severity, and inference-readiness decision. A fit that is not inference-ready remains available for descriptive numerical review. Inspect the source fit's readiness checks and supported inferential scope: lack of readiness need not mean optimizer failure, and convergence alone does not establish readiness. The comparison does not validate standard errors or confidence intervals. The generated ConQuest benchmark template fixes its parameter-change criterion at 1e-8, deviance-change criterion at 1e-10, and iteration ceiling at 2000; these controls are written into the command, summary, and settings so a default stopping rule cannot masquerade as an objective discrepancy.

The conquest_command component is a conservative starting template, not a guaranteed version-invariant automation. The conquest_output_contract component records which requested external output should feed each normalized review table. Use normalize_conquest_overlap_exports() for the parameter, regression, covariance, and case-EAP CSV files requested by the generated command. The additional matrixout history CSV retains the objective trajectory and an independent estimated-parameter dimension for release verification; it is not parsed as a free-form report. normalize_conquest_overlap_files() and normalize_conquest_overlap_tables() remain available for already-extracted custom tables. Then use review_conquest_overlap() only after the matching ConQuest run has been executed externally. The bundle and command template alone are not external validation evidence.

This is a controlled analysis bundle, not a deidentified or automatically shareable export. Response files contain person identifiers and responses; the person-data file contains identifiers and covariates; and case-EAP files contain identifiers and person-level estimates. When files are written, the helper emits a warning and writes an artifact-level privacy notice. Apply the study's data-handling policy before sharing or moving any bundle file.

Running ConQuest locally

This function writes inputs; it does not launch or install ConQuest. Open the generated .cqc file in your local ConQuest installation and use its containing directory as the working directory, so the relative CSV paths resolve. A native command-line installation can also read that command file as standard input from the same directory. Check the ConQuest console for successful estimation and the requested exports before normalizing them. ConQuest is optional and is not needed for the package's examples or tests.

ConQuest's EAP calculation uses Monte Carlo posterior integration with separate p_nodes and seed controls. The estimate command's quadrature node count does not set this posterior simulation budget. Record both controls when comparing Person scores; close calibration estimates do not imply identical EAPs. See the ConQuest command reference, set and show. This template leaves those posterior controls at the local ConQuest defaults.

Comparison targets

regression slope: compare after confirming identical covariate coding and population-model parameterization;
residual variance sigma2: compare after confirming the same latent-scale and variance parameterization;
item estimates: compare after centering because the Rasch location origin remains constraint-dependent;
case EAP estimates: compare as posterior summaries under the fitted population model.

Output

The returned object has class mfrm_conquest_overlap_bundle and includes:

summary: one-row scope summary with posterior-basis, population-model, optimizer-control, and convergence-review fields
comparison_targets: comparison rules for the exported tables
conquest_output_contract: requested ConQuest outputs and review handoff
response_long: long-format binary response data used by the bundle
response_wide: wide CSV-ready response matrix for the ConQuest template
person_data: one-row-per-person covariate table
item_map: mapping from exported response columns to original item levels
mfrmr_population: fitted population-model coefficients plus sigma2
mfrmr_item_estimates: fitted item estimates with centered values
mfrmr_case_eap: posterior EAP summaries for the fitted persons
conquest_command: conservative ConQuest command template
written_files: file inventory when output_dir is supplied
privacy_notice: artifact-level sensitive-data inventory
settings: bundle settings, including the actual mfrmr fit controls and convergence state
notes: interpretation notes

Examples

# \donttest{
bundle <- build_conquest_overlap_bundle(
  quad_points = 31, maxit = 2000, reltol = 1e-10
)
bundle$summary[, c("Case", "Facet", "Covariate", "Persons", "Items")]
#>                          Case     Facet Covariate Persons Items
#> 1 synthetic_latent_regression Criterion         X      60     6
summary(bundle)$mfrmr_fit_status
#>                           Item     Value
#> 1              MML engine used    direct
#> 2           Maximum iterations      2000
#> 3           Relative tolerance     1e-10
#> 4                  Convergence Converged
#> 5                     Severity      Pass
#> 6 Terminal gradient (sup-norm)  6.16e-05
#> 7              Inference ready        No
summary(bundle)$conquest_command_scope
#>                                   Area                        Status
#> 1            ConQuest command template                 template only
#> 2               Command-comment syntax comment-free executable input
#> 3 Official command-reference alignment           explicit CSV widths
#> 4                  Overlap model scope           narrow overlap only
#> 5         External output requirements                     requested
#> 6            External comparison scope                   not claimed
#>                                                                 Evidence
#> 1                                                bundle$conquest_command
#> 2       no prose or C-style comment markers precede the datafile command
#> 3                                    pidwidth and keepswidth are present
#> 4                      binary Criterion facet with numeric covariate `X`
#> 5    parameters, reg_coefficients, covariance, and cases EAP CSV outputs
#> 6 requires external ConQuest execution and extracted output-table review
#>                                                                                         Interpretation
#> 1     Use the command text as a starting point for a local ConQuest run, not as an executed benchmark.
#> 2       The executable command contains commands only; explanatory prose remains in the bundle README.
#> 3                    CSV input with PID/keeps variables needs explicit widths in the command template.
#> 4                  The bundle does not generalize to full many-facet or polytomous ConQuest workflows.
#> 5    Review and combine external parameter, beta, sigma, and case outputs before review normalization.
#> 6 External comparison remains scoped until external outputs are reviewed and tolerances are justified.
summary(bundle)$conquest_output_contract
#>                                      ExternalFile
#> 1        conquest_overlap_conquest_parameters.csv
#> 2  conquest_overlap_conquest_reg_coefficients.csv
#> 3        conquest_overlap_conquest_covariance.csv
#> 4         conquest_overlap_conquest_cases_eap.csv
#> 5           conquest_overlap_conquest_history.csv
#> 6 conquest_overlap_conquest_parameters_review.txt
#>                                            ConQuestCommand
#> 1                         export parameters ! filetype=csv
#> 2                   export reg_coefficients ! filetype=csv
#> 3                         export covariance ! filetype=csv
#> 4 show cases ! estimates=eap, filetype=csv, regressors=yes
#> 5                     write mfrmrCQ_history ! filetype=csv
#> 6          show parameters ! tables=1:2:3:4, estimates=eap
#>                                                                                                              ReviewHandoff
#> 1                                                 Pass to normalize_conquest_overlap_exports() as the item-parameter file.
#> 2                                                     Pass to normalize_conquest_overlap_exports() as the regression file.
#> 3                                                     Pass to normalize_conquest_overlap_exports() as the covariance file.
#> 4                                                       Pass to normalize_conquest_overlap_exports() as the case-EAP file.
#> 5 Retain for the objective/free-dimension verification; this is the estimate matrixout history, not a parsed report table.
#> 6                                        Human-readable review only; do not treat this text file as a parsed review table.
#>                                                                                   DataHandling
#> 1                                     Review item labels and analysis metadata before sharing.
#> 2                                Review covariate labels and analysis metadata before sharing.
#> 3                              Review covariance results and analysis metadata before sharing.
#> 4 Contains person identifiers and person-level EAP estimates; restricted handling is required.
#> 5                Review model labels, iteration history, and analysis metadata before sharing.
#> 6                                Review parameter labels and analysis metadata before sharing.
#>   RequiredForReview
#> 1              TRUE
#> 2              TRUE
#> 3              TRUE
#> 4              TRUE
#> 5              TRUE
#> 6             FALSE
cat(substr(bundle$conquest_command, 1, 120))
#> datafile conquest_overlap_wide.csv ! filetype=csv, columnlabels=yes, pid=Person, pidwidth=32, responses=I001 to I006, ke
# }