mfrmr Compatibility Layer Map — mfrmr_compatibility

Guide to the legacy-compatible wrappers and text/file exports in mfrmr. Use this page when you need continuity with older compatibility-oriented workflows, fixed-width reports, or graph/score file style outputs.

This compatibility layer currently applies mainly to diagnostics-based RSM / PCM workflows. Bounded GPCM fits also support graph-only compatibility-style exports, while scorefile and diagnostics-driven compatibility outputs remain limited to RSM / PCM. Treat this layer as a presentation/contract surface, not as a claim of FACETS or ConQuest numerical equivalence.

SPSS is treated differently from FACETS and ConQuest: mfrmr currently supports table/data-frame/CSV handoff for SPSS-oriented reporting workflows, but it does not generate SPSS syntax, write native SPSS system files, execute SPSS estimators, or claim SPSS numerical equivalence.

When to use this layer

You are reproducing an older workflow that expects one-shot wrappers.
You need fixed-width text blocks for console, logs, or archival handoff.
You need graphfile or scorefile style outputs for downstream legacy tools.
You are checking column coverage and metric consistency against a FACETS-style output contract.

When not to use this layer

For standard estimation, use fit_mfrm() plus diagnose_mfrm().
For report bundles, use mfrmr_reports_and_tables.
For manuscript text, use build_apa_outputs() and reporting_checklist().
For visual follow-up, use mfrmr_visual_diagnostics.

Compatibility map

facets_positioning_guide(): User-facing wording for the package's relationship to FACETS. Use before describing compatibility outputs in a report or migration note.
run_mfrm_facets(): One-shot legacy-compatible wrapper that fits, diagnoses, and returns key tables in one object.
mfrmRFacets(): Alias for run_mfrm_facets() kept for continuity.
build_fixed_reports(): Fixed-width interaction and pairwise text blocks. Best when a text-only compatibility artifact is required.
facets_output_file_bundle(): Graphfile/scorefile style CSV and fixed-width exports for legacy pipelines.
write_mfrm_residual_file(): Package-native observation-level residual CSV/TSV export for reviewer, spreadsheet, or external QC handoff.
write_mfrm_subset_file(): Package-native connected-subset summary and node-membership CSV/TSV export for linking review handoff.
facets_output_contract_review(): Column and metric review against the FACETS-style output-contract specification. Use only when an explicit output-contract review is part of the task; it checks the package output contract and does not imply external FACETS equivalence.

Preferred replacements

Instead of run_mfrm_facets(), prefer: fit_mfrm() -> diagnose_mfrm() -> reporting_checklist().
Instead of build_fixed_reports(), prefer: bias_interaction_report() -> build_apa_outputs().
Instead of facets_output_file_bundle(), prefer: category_curves_report() or category_structure_report() plus export_mfrm_bundle().
For residual or subset handoff, prefer write_mfrm_residual_file() and write_mfrm_subset_file() over reusing graph/score compatibility exports.
Instead of facets_output_contract_review() for routine QA, prefer: reference_case_review() for package-native completeness review or reference_case_benchmark() for packaged benchmark cases.

Practical migration rules

Start FACETS-facing reports with facets_positioning_guide() when readers might otherwise assume FACETS numerical reproduction.
Keep compatibility wrappers only where a downstream consumer truly needs the old layout or fixed-width format.
For new scripts, start from package-native bundles and add compatibility outputs only at the export boundary.
Treat compatibility outputs as presentation contracts, not as the primary analysis objects.
Use compatibility_alias_table() when you need to check which aliases are still retained and which package-native names should be used in new code.
Use reporting_checklist(fit)$software_scope to review the current FACETS, ConQuest, and SPSS relationship wording for a fitted analysis.

Retained table-field names

row_review is the data-quality table field used to document row filtering. FACETS-style column and metric contract results are exposed as column_review and metric_checks.
Prediction outputs expose row-preparation and person-omission traceability as row_review and population_review.
hierarchical_review, shrinkage_review, and nesting_review are manifest or model-comparison traceability fields. They are not callable helper names; user-facing helper names use review/check terminology.

Typical workflow

Legacy handoff: run_mfrm_facets() -> build_fixed_reports() -> facets_output_file_bundle() plus write_mfrm_residual_file() / write_mfrm_subset_file() only when those standalone files are needed.
Mixed workflow: RSM / PCM: fit_mfrm() -> diagnose_mfrm() -> build_apa_outputs() -> compatibility export only if required. bounded GPCM: fit_mfrm() -> diagnose_mfrm() -> reporting_checklist() -> graph-only compatibility export only when a legacy handoff truly requires it.
FACETS output-contract review: fit_mfrm() -> diagnose_mfrm() -> facets_output_contract_review().

Companion guides

For FACETS coverage and boundary wording, see facets_positioning_guide() and facets_feature_coverage().
For standard reports/tables, see mfrmr_reports_and_tables.
For manuscript-draft reporting, see mfrmr_reporting_and_apa.
For visual diagnostics, see mfrmr_visual_diagnostics.
For linking and DFF workflows, see mfrmr_linking_and_dff.
For end-to-end routes, see mfrmr_workflow_methods.

Examples

# \donttest{
toy <- load_mfrmr_data("example_core")
toy_small <- toy[toy$Person %in% unique(toy$Person)[1:12], , drop = FALSE]

run <- run_mfrm_facets(
  data = toy_small,
  person = "Person",
  facets = c("Rater", "Criterion"),
  score = "Score",
  maxit = 30
)
summary(run)
#> FACETS-style Workflow Summary
#>   Model: RSM | Method: JML
#>   N: 192 | Persons: 12 | Facets: 2 | Categories: 4
#>   LogLik: -203.282 | AIC: 446.564 | BIC: 511.714
#>   Optimizer returned code 0: Yes | Formal inference: Ready | Iterations: 66
#> 
#> Column mapping
#>     Key            Value
#>  Person           Person
#>   Score            Score
#>  Facets Rater, Criterion
#>  Weight                 
#> 
#> Detailed objects:
#>  - summary(out$fit)
#>  - summary(out$diagnostics)
compatibility_alias_table("functions")
#>         Alias   PreferredName  Surface      Lifecycle
#> 1 mfrmRFacets run_mfrm_facets function retained_alias
#> 2 analyze_dif     analyze_dff function retained_alias
#>                         RetainedFor           RemovalPlan
#> 1            older workflow scripts No scheduled removal.
#> 2 earlier DIF-oriented package code No scheduled removal.
#>                                                                                     Notes
#> 1                      Compatibility wrapper for the legacy-compatible one-shot workflow.
#> 2 DFF naming is preferred for many-facet workflows; the older DIF name is still accepted.

fixed <- build_fixed_reports(
  estimate_bias(
    run$fit,
    run$diagnostics,
    facet_a = "Rater",
    facet_b = "Criterion",
    max_iter = 1
  ),
  branch = "original"
)
names(fixed)
#> [1] "bias_fixed"        "pairwise_fixed"    "pairwise_table"   
#> [4] "branch"            "style"             "interaction_label"
#> [7] "target_facet"     
# }