mfrmr Reporting and APA

Minimal setup

library(mfrmr)

toy <- load_mfrmr_data("example_core")

# The vignette uses compact quadrature so optional local execution stays fast.
# For final manuscript reporting, refit with the package default or a higher
# quadrature setting and record that setting in the analysis log.
fit <- fit_mfrm(
  toy,
  person = "Person",
  facets = c("Rater", "Criterion"),
  score = "Score",
  method = "MML",
  model = "RSM",
  quad_points = 7
)

diag <- diagnose_mfrm(fit, residual_pca = "none")

1. Start with the revision guide

Use reporting_checklist() first when the question is “what is still missing?” rather than “how do I phrase the results?”

chk <- reporting_checklist(fit, diagnostics = diag)

head(
  chk$checklist[, c("Section", "Item", "DraftReady", "Priority", "NextAction")],
  10
)

Interpretation:

• DraftReady flags whether the current objects already support a section for drafting with the package’s documented caveats.
• Priority shows what to resolve first.
• NextAction is the shortest package-native instruction for closing the gap.

2. Check the precision layer before strong claims

mfrmr intentionally distinguishes model_based, hybrid, and exploratory precision tiers.

prec <- precision_review_report(fit, diagnostics = diag)

prec$profile
prec$checks

Interpretation:

• Use stronger inferential phrasing only when the reported tier is model_based.
• Treat hybrid and exploratory outputs more conservatively, especially for SE-, CI-, and reliability-heavy prose.

3. Build structured manuscript outputs

build_apa_outputs() is the writing engine. It returns report text plus a section map, note map, and caption map that all share the same internal contract.

apa <- build_apa_outputs(
  fit,
  diagnostics = diag,
  context = list(
    assessment = "Writing assessment",
    setting = "Local scoring study",
    scale_desc = "0-4 rubric scale",
    rater_facet = "Rater"
  )
)

cat(apa$report_text)

apa$section_map[, c("SectionId", "Heading", "Available")]

Interpretation:

• report_text is the compact narrative output.
• section_map is the machine-readable map of what text blocks are available.
• The same contract also feeds captions and notes, which reduces wording drift.

4. Build tables from the same contract

Use apa_table() when you want reproducible handoff tables without rebuilding captions or notes by hand.

tbl_summary <- apa_table(fit, which = "summary")
tbl_reliability <- apa_table(fit, which = "reliability", diagnostics = diag)

tbl_summary$caption
tbl_reliability$note

The actual table data are stored in tbl_summary$table and tbl_reliability$table.

5. Add figure-ready visual data

For reporting workflows, build_visual_summaries() is the bridge between statistical results and figure-ready plot data.

vis <- build_visual_summaries(
  fit,
  diagnostics = diag,
  threshold_profile = "standard"
)

names(vis)
names(vis$warning_map)

6. Reporting route when interaction screening matters

When bias or local interaction screens matter, keep the wording conservative. The package treats these outputs as screening-oriented unless the current precision and design evidence justify stronger claims.

bias_df <- load_mfrmr_data("example_bias")

fit_bias <- fit_mfrm(
  bias_df,
  person = "Person",
  facets = c("Rater", "Criterion"),
  score = "Score",
  method = "MML",
  model = "RSM",
  quad_points = 7
)

diag_bias <- diagnose_mfrm(fit_bias, residual_pca = "none")
bias <- estimate_bias(fit_bias, diag_bias, facet_a = "Rater", facet_b = "Criterion")
apa_bias <- build_apa_outputs(fit_bias, diagnostics = diag_bias, bias_results = bias)

apa_bias$section_map[, c("SectionId", "Available", "Heading")]

Recommended sequence

For a compact manuscript-oriented route:

1. fit_mfrm()
2. diagnose_mfrm()
3. precision_review_report()
4. reporting_checklist()
5. build_apa_outputs()
6. apa_table()
7. build_visual_summaries()

Related help

• help("mfrmr_reporting_and_apa", package = "mfrmr")
• help("mfrmr_reports_and_tables", package = "mfrmr")
• help("reporting_checklist", package = "mfrmr")
• help("build_apa_outputs", package = "mfrmr")