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 documented 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.
Use precision_review_report() to determine whether formal inference is supported for the fitted result.
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

# \donttest{
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
#>                 Class Components
#> 1 mfrm_specifications          6
#>                                                                      ComponentNames
#> 1 header, data_spec, facet_labels, output_spec, convergence_control, anchor_summary
#>   PreviewComponent PreviewRows
#> 1        data_spec          10

prec <- precision_review_report(fit, diagnostics = diag)
summary(prec)$checks
#>                      Check Status
#> 1           Precision tier   pass
#> 2    Optimizer convergence   pass
#> 3     ModelSE availability   pass
#> 4 Fit-adjusted SE ordering   pass
#> 5     Reliability ordering   pass
#> 6 Facet precision coverage   pass
#> 7         SE source labels   pass
#>                                                                                 Detail
#> 1                              This run uses the package's model-based precision path.
#> 2                                Optimizer diagnostics support inference-ready status.
#> 3                             Finite ModelSE values were available for 100.0% of rows.
#> 4            Fit-adjusted SE values were not smaller than their paired ModelSE values.
#> 5         Conservative reliability values were not larger than the model-based values.
#> 6 Each facet had sample/population summaries for both model and fit-adjusted SE modes.
#> 7                        Person and non-person SE labels match the MML precision path.

checklist <- reporting_checklist(fit, diagnostics = diag)
subset(checklist$checklist, Section == "Visual Displays", c("Item", "NextAction"))
#>                                   Item
#> 25                          Wright map
#> 26                QC / facet dashboard
#> 27                Residual PCA visuals
#> 28 Connectivity / design-matrix visual
#> 29  Inter-rater / displacement visuals
#> 30             Strict marginal visuals
#> 31                  Bias / DIF visuals
#> 32      Precision / information curves
#> 33                Fit/category visuals
#>                                                                                                                       NextAction
#> 25                                      Include a Wright map when the manuscript benefits from a shared-scale targeting display.
#> 26                     Use the dashboard as a first-pass triage view, then move to the specific follow-up plot behind each flag.
#> 27                                         Run residual PCA if you want scree/loadings visuals for residual-structure follow-up.
#> 28                                                       Use the design-matrix view to support linkage and comparability claims.
#> 29                                       Use displacement and inter-rater views to localize QC issues after dashboard screening.
#> 30 Treat strict marginal plots as exploratory corroboration screens, then corroborate with design review and legacy diagnostics.
#> 31                                                        Run bias or DIF screening before discussing interaction-level visuals.
#> 32                                Use information curves to describe precision across theta when that is the reporting question.
#> 33                                        Use category curves and fit visuals as local descriptive follow-up after QC screening.

apa <- build_apa_outputs(fit, diagnostics = diag)
apa$section_map[, c("Heading", "Available")]
#>                              Heading Available
#> 1                    Design and data      TRUE
#> 2                Estimation settings      TRUE
#> 3                  Scale functioning      TRUE
#> 4                     Facet measures      TRUE
#> 5 Latent-regression population model     FALSE
#> 6                  Fit and precision      TRUE
#> 7                 Residual structure      TRUE
#> 8                     Bias screening     FALSE
#> 9                 Reporting cautions      TRUE
bundle <- build_summary_table_bundle(checklist)
bundle$table_index
#>                Table Rows Cols                        Role
#> 1           overview    1    6          checklist_overview
#> 2    section_summary    7    8            section_coverage
#> 3 facets_positioning    6    4 facets_relationship_wording
#> 4   priority_summary    4    3       priority_distribution
#> 5       action_items    7    7               draft_actions
#> 6           settings    5    2          checklist_settings
#>                                                                                                Description
#> 1                                    Overall checklist coverage across sections and draft-readiness flags.
#> 2                                                                   Coverage summary by reporting section.
#> 3 Report-ready wording that separates mfrmr estimation from FACETS-style handoff or external-table review.
#> 4                                                                High/medium/low/ready counts by severity.
#> 5                                                              Top unresolved manuscript-drafting actions.
#> 6                                                 Checklist settings used to build the reporting contract.
# }