mfrmr Reports and Tables Map — mfrmr_reports_and

Quick guide to choosing the right report or table helper in mfrmr. Use this page when you know the reporting question but have not yet decided which bundle, table, or reporting helper to call.

Start with the question

"How should I document the model setup and run settings?" Use specifications_report().
"Was data filtered, dropped, or mapped in unexpected ways?" Use data_quality_report() and describe_mfrm_data().
"Did estimation converge cleanly and how formal is the precision layer?" Use estimation_iteration_report() and precision_review_report().
"Which facets are measurable, variable, or weakly separated?" Use facet_statistics_report(), measurable_summary_table(), and facets_chisq_table().
"Are score categories functioning in a usable sequence?" Use rating_scale_table(), category_structure_report(), and category_curves_report().
"Is the design linked well enough across subsets, forms, or waves?" Use subset_connectivity_report() and plot_anchor_drift().
"What should go into the manuscript text and tables?" For RSM / PCM, use reporting_checklist(), build_apa_outputs(), and build_summary_table_bundle() or export_summary_appendix(). For bounded GPCM, use the same route only where gpcm_capability_matrix() marks it as supported_with_caveat: direct table/plot helpers, summary-table appendix export, caveated build_apa_outputs(), and caveated export_mfrm_bundle() are available with a gpcm_boundary; score-side exports and design-forecasting evidence use their own caveated or blocked GPCM routes.
"Did a simulation recover the known generating parameters well enough?" Use evaluate_mfrm_recovery() for the recovery study, assess_mfrm_recovery() for the adequacy checklist, and then build_summary_table_bundle() or export_summary_appendix() for the appendix handoff.

Recommended report route

Start with specifications_report() and data_quality_report() to document the run and confirm usable data.
Continue with estimation_iteration_report() and precision_review_report() to judge convergence and inferential strength.
Use facet_statistics_report() and subset_connectivity_report() to describe spread, linkage, and measurability.
Add rating_scale_table(), category_structure_report(), and category_curves_report() to document scale functioning.
For RSM / PCM, finish with reporting_checklist() and build_apa_outputs() for manuscript-oriented output, then build_summary_table_bundle() for reusable handoff tables or export_summary_appendix() for direct appendix export. For bounded GPCM, the same report/export route is available only as a caveated sensitivity-reporting layer with gpcm_boundary; keep FACETS-style score-side review and design forecasting on their separate capability rows.

If you are unsure which helper to call, start with mfrmr_output_guide(). It returns a compact purpose-to-helper table that separates *_table, *_report, *_review, *_bundle, export_*, and compatibility routes.

Which output answers which question

specifications_report(): Documents model type, estimation method, anchors, and core run settings. Best for method sections and reproducibility records.
data_quality_report(): Summarizes retained and dropped rows, missingness, and unknown elements. Best for data cleaning narratives.
estimation_iteration_report(): Shows replayed convergence trajectories. Best for diagnosing slow or unstable estimation.
precision_review_report(): Summarizes whether SE, CI, and reliability indices are model-based, hybrid, or exploratory. Best for deciding how strongly to phrase inferential claims.
facet_statistics_report(): Bundles facet summaries, precision summaries, and variability tests. Best for facet-level reporting.
subset_connectivity_report(): Summarizes disconnected subsets and coverage bottlenecks. Best for linking and anchor strategy review.
rating_scale_table(): Gives category counts, average measures, and threshold diagnostics. Best for first-pass category evaluation.
category_structure_report(): Adds transition points and compact category warnings. Best for category-order interpretation.
category_curves_report(): Returns category-probability, cumulative-probability, expected-ogive, total-information, and category-specific information coordinates. Best for downstream graphics and report drafts.
write_mfrm_residual_file(): Writes an observation-level residual file, optionally with modeled category probabilities. Best for external case review or reproducible handoff.
write_mfrm_subset_file(): Writes connected-subset summary and node-membership files. Best for scale-linking review outside R.
reporting_checklist(): Turns analysis status into an action list with priorities and next steps. Best for closing reporting gaps.
build_apa_outputs(): Creates manuscript-draft text, notes, captions, and section maps from a shared reporting contract.
build_summary_table_bundle(): Converts supported summary() outputs into named data.frame tables with a compact index for appendix or manuscript handoff, including recovery simulation and recovery assessment outputs. It also supports bundle-level summary() / plot() for QC before export.
export_summary_appendix(): Exports those validated summary-table bundles as CSV and optional HTML appendix artifacts without requiring the broader fit-based export bundle. This is the preferred export route for recovery simulation evidence.
apa_table(): Can now take those summary-table bundles directly, so a selected component can move from summary() to a formatted handoff table without rebuilding the analysis object path.

Practical interpretation rules

Use bundle summaries first, then drill down into component tables.
Treat precision_review_report() as the gatekeeper for formal inference.
Treat category and bias outputs as complementary layers rather than substitutes for overall fit review.
Treat zero-count score categories as scale-functioning caveats. Boundary zero-count categories can be retained with explicit rating_min / rating_max; intermediate zero-count categories require keep_original = TRUE and make adjacent thresholds weakly identified. summary(describe_mfrm_data(...)) exposes these in Notes, printed Caveats, and $caveats; summary(fit) carries full structured caveats into printed Caveats and $caveats, with Key warnings as a short triage subset. Summary-table exports use score_category_caveats and analysis_caveats.
Use reporting_checklist() before build_apa_outputs() when a report still needs missing diagnostics or clearer caveats.

Typical workflow

Run documentation: fit_mfrm() -> specifications_report() -> data_quality_report().
Precision and facet review: diagnose_mfrm() -> precision_review_report() -> facet_statistics_report().
Scale review: rating_scale_table() -> category_structure_report() -> category_curves_report().
Manuscript handoff (RSM / PCM): reporting_checklist() -> build_apa_outputs() -> build_summary_table_bundle() -> summary() / plot() -> apa_table() or export_summary_appendix() / export_mfrm_bundle()(include = "summary_tables").
Bounded GPCM handoff: reporting_checklist() -> direct summaries/plots -> build_apa_outputs() or build_summary_table_bundle() -> export_summary_appendix() or caveated export_mfrm_bundle(), with gpcm_boundary retained in report/export objects.
Recovery simulation handoff: evaluate_mfrm_recovery() -> plot() / assess_mfrm_recovery() -> build_summary_table_bundle() -> export_summary_appendix().

Companion guides

For visual follow-up, see mfrmr_visual_diagnostics.
For one-shot analysis routes, see mfrmr_workflow_methods.
For manuscript assembly, see mfrmr_reporting_and_apa.
For linking and DFF review, see mfrmr_linking_and_dff.
For legacy-compatible wrappers and exports, see mfrmr_compatibility_layer.

Examples

if (FALSE) { # \dontrun{
toy <- load_mfrmr_data("example_core")
toy_small <- toy[toy$Person %in% unique(toy$Person)[1:12], , drop = FALSE]
fit <- fit_mfrm(
  toy_small,
  person = "Person",
  facets = c("Rater", "Criterion"),
  score = "Score",
  method = "MML",
  quad_points = 7,
  maxit = 30
)
diag <- diagnose_mfrm(fit, residual_pca = "none", diagnostic_mode = "both")

spec <- specifications_report(fit)
summary(spec)$overview

prec <- precision_review_report(fit, diagnostics = diag)
summary(prec)$checks

checklist <- reporting_checklist(fit, diagnostics = diag)
subset(checklist$checklist, Section == "Visual Displays", c("Item", "NextAction"))

apa <- build_apa_outputs(fit, diagnostics = diag)
apa$section_map[, c("Heading", "Available")]
bundle <- build_summary_table_bundle(checklist)
bundle$table_index
} # }