Review a ConQuest comparison within the documented mfrmr overlap scope

Review a ConQuest comparison within the documented mfrmr overlap scope

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",
  conquest_location_shift = NULL
)

Arguments

bundle

Output from build_conquest_overlap_bundle().

conquest_population

Normalized ConQuest population-parameter table as a data.frame, or output from normalize_conquest_overlap_exports(), normalize_conquest_overlap_files(), or normalize_conquest_overlap_tables().

conquest_item_estimates

Normalized ConQuest item-estimate table as a data.frame. Leave NULL when conquest_population is an object from one of the ConQuest normalization helpers.

conquest_case_eap

Normalized ConQuest case-level EAP table as a data.frame. Leave NULL when conquest_population is an object from one of the ConQuest normalization helpers.

conquest_population_term

Column in conquest_population that stores parameter names. "auto" tries conservative aliases such as Parameter and Term.

conquest_population_estimate

Column in conquest_population that stores parameter estimates. "auto" tries aliases such as Estimate and Est.

conquest_item_id

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

conquest_item_estimate

Column in conquest_item_estimates that stores the item estimate. "auto" tries Estimate and Est. Other columns must be specified explicitly and converted to difficulty logits before review.

item_id_source

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

conquest_case_person

Column in conquest_case_eap that stores person IDs. "auto" tries conservative aliases such as Person, PID, and Sequence ID.

conquest_case_estimate

Column in conquest_case_eap that stores case EAP estimates. "auto" tries conservative aliases such as Estimate, EAP_1, and EAP.

conquest_location_shift

Known additive location offset, ConQuest minus mfrmr. Use 0 only after confirming a common origin. NULL uses zero when the supplied generated report confirms the common ITEMS constraint; otherwise aligned EAP/intercept comparisons are unavailable. This argument does not change scale units or reverse the item sign.

Value

A named list with class mfrm_conquest_overlap_review.

Details

This helper compares normalized ConQuest output tables against the exact- overlap bundle produced by build_conquest_overlap_bundle(). It is intentionally conservative:

• it does not parse raw ConQuest text output automatically;

• its primary route expects output from normalize_conquest_overlap_exports(), which reads the four native comparison CSV files requested by the generated command; the additional matrixout-history CSV is retained for a separate objective/free-dimension verification; custom extracted tables may use normalize_conquest_overlap_files() or normalize_conquest_overlap_tables();

• 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 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:

1. export a bundle for the documented comparison scope with build_conquest_overlap_bundle();

2. run the narrow matching case in ConQuest;

3. normalize the four comparison CSV files with normalize_conquest_overlap_exports(), supplying the generated review text as report_file for stopping/model metadata;

4. pass those tables here to inspect direct differences, centered item agreement, and case-level EAP agreement.

Output

The returned object has class mfrm_conquest_overlap_review and includes:

• overall: one-row comparison summary with missing/duplicate/non-numeric attention-item counts and worst-row labels

• population_comparison: parameter-by-parameter comparison table

• item_comparison: centered item-estimate comparison table

• case_comparison: case-level EAP comparison table

• attention_items: missing, malformed, or unmatched elements

• settings: review settings

• notes: interpretation notes

Interpretation

• Read 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.

• Population slopes and sigma2 are intended for direct comparison.

• Both item tables are centered using the same matched finite items. MfrmrCentered is this comparison coordinate; CenteredEstimate retains the native bundle's original full-set coordinate. ItemCenteringRows records the reference-set size. At least two items are needed; otherwise centered differences and summary metrics are unavailable. Missing items remain flagged, and partial-set agreement does not imply full-set agreement. Recompute older reviews from the saved bundle and external tables to apply this common reference set; printing an old review does not change its values.

• Case estimates are posterior EAP summaries under the fitted population model. Difference retains the raw external-minus-native value; AlignedDifference subtracts the declared location shift. CaseMae and CaseMaxAbsDifference use aligned differences and are unavailable when the origin is unknown. CaseRawMae and CaseRawMaxAbsDifference remain descriptive. Do not infer a common origin from partial centered items.

• Population summary errors cover slopes and variance; the intercept has separate InterceptCompared and InterceptAlignedDifference fields.

• ExternalEstimationStatus is unknown without a supplied report. criterion_met does not certify precision; ExternalPrecisionStatus remains not_assessed. Failed stopping and surplus external IDs are attention items. Recreate old reviews to apply these rules.

• The overall table reports both mean and maximum absolute differences for compared population, centered item, and case rows. The PopulationMaxAbsParameter, ItemCenteredMaxAbsItem, and CaseMaxAbsPerson columns identify the row where each maximum absolute difference occurs.

• Missing or non-numeric rows in attention_items indicate that the external tables do not align cleanly with the exported overlap bundle. Non-finite estimates also use the existing NonNumericInConQuest status and are excluded from comparison metrics.

• This review does not compare MnSq, ZSTD, threshold crossings or full parameter covariance. Native MML row residuals evaluated at EAP are not ConQuest parameter-fit statistics: those aggregate through the response design and average over posterior distributions. Adjacent step parameters are not ConQuest cumulative-probability (Thurstonian) thresholds. See the ConQuest technical manual.

See also

build_conquest_overlap_bundle(), normalize_conquest_overlap_files(), normalize_conquest_overlap_tables(), reference_case_benchmark()

Examples

if (FALSE) { # \dontrun{
bundle <- build_conquest_overlap_bundle()
normalized <- normalize_conquest_overlap_exports(
  bundle,
  parameter_file = "conquest_overlap_conquest_parameters.csv",
  regression_file = "conquest_overlap_conquest_reg_coefficients.csv",
  covariance_file = "conquest_overlap_conquest_covariance.csv",
  case_file = "conquest_overlap_conquest_cases_eap.csv",
  report_file = "conquest_overlap_conquest_parameters_review.txt"
)
review <- review_conquest_overlap(bundle, normalized)
summary(review)$summary
} # }