mfrmr Reporting and APA

This vignette shows the package-native route from a fitted many-facet Rasch model to manuscript-oriented prose, tables, figure notes, and revision checks.

The reporting stack in mfrmr is organized around four objects:

  • fit: the fitted model from fit_mfrm()
  • diag: diagnostics from diagnose_mfrm()
  • chk: the revision guide from reporting_checklist()
  • apa: structured manuscript outputs from build_apa_outputs()

For a broader workflow view, see vignette("mfrmr-workflow", package = "mfrmr"). For a plot-first route, see vignette("mfrmr-visual-diagnostics", package = "mfrmr").

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
prec$fit_separation_basis

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.
  • Read fit_separation_basis as a boundary table: MnSq fit, ZSTD standardization, Rasch/FACETS-style separation, and package QC thresholds have different source bases and should not be collapsed into a single validation pass/fail claim.

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 output 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.

Publication-readiness boundary

The APA route is strongest when it is used as a structured drafting and review surface. It is not a one-click manuscript generator. Before moving text into a journal article, inspect the following objects together:

res <- mfrm_results(fit, include = "publication")
report <- mfrm_report(res, style = "apa")

report$first_screen
report$claim_readiness
report$report_gaps
head(report$template_index[, c(
  "Area", "Topic", "BoundaryType", "ClaimStrength", "RecommendedUse"
)])

For a high-stakes manuscript, treat build_apa_outputs() and mfrm_report(style = "apa") as conservative scaffolding. Stronger journal claims still require a defensible study design, cited measurement rationale, adequate precision evidence, linked or balanced design evidence where relevant, and substantive interpretation written in the language of the target journal. Do not report DraftReady, ReadyForAPA, or ClaimStrength as if they were formal acceptance decisions; use them to decide what wording is currently safe and which caveats must remain visible.

When the target is a local HTML/CSV/replay bundle rather than an interactive review object, use export_mfrm_bundle() directly from the fitted object:

bundle <- export_mfrm_bundle(
  fit,
  diagnostics = diag,
  output_dir = "mfrmr-report-bundle",
  prefix = "analysis01",
  include = c(
    "core_tables", "checklist", "dashboard", "apa",
    "summary_tables", "manifest", "script", "html"
  ),
  overwrite = TRUE
)

bundle$written_files[bundle$written_files$Format == "html", ]

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")]

7. Keep model comparison as a reporting review

When candidate models are fitted, separate same-data comparison from the scoring interpretation. compare_mfrm() provides the fit-statistic table; build_model_choice_review() attaches model roles, downstream route boundaries, and cautious wording. Convert the review to a summary-table bundle when the comparison needs to appear in an appendix or exported report.

cmp <- compare_mfrm(RSM = fit_rsm, PCM = fit_pcm, GPCM = fit_gpcm)
review <- build_model_choice_review(
  RSM = fit_rsm,
  PCM = fit_pcm,
  GPCM = fit_gpcm,
  run_weighting_review = TRUE
)
model_choice_tables <- build_summary_table_bundle(
  review,
  appendix_preset = "recommended"
)

cmp[, c("Model", "LogLik", "AIC", "BIC", "ICComparable")]
model_choice_tables$table_index

For bounded GPCM, report the fit as a slope-aware sensitivity model unless the score interpretation explicitly justifies discrimination-based reweighting. Do not use AIC/BIC alone as an operational-scoring decision.

8. Report latent regression as a population-model branch

Latent-regression fits expose their reportable surface through the fit summary: population_overview, population_coefficients, population_coding, and caveats. Coefficients are conditional-normal population-model parameters, not post-hoc regressions on EAP or MLE scores.

s_pop <- summary(fit_pop)
s_pop$population_overview
s_pop$population_coefficients
s_pop$population_coding
s_pop$caveats

In this release, keep latent-regression claims to the documented one-dimensional MML RSM / PCM route. Report the population formula, coding/contrast handling, population policy, and any omitted-person or omitted-row counts; do not imply multidimensional latent regression, Wald-test inference, or posterior predictive checking from these tables alone.