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:

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

# 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:

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:

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:

Publication-readiness boundary

The APA route is strongest when it is used as a structured drafting and review workflow. 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 a conservative drafting template. 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. The result is a potentially identifying analysis archive, not a deidentified sharing package:

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,
  acknowledge_sensitive = 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 the latent-regression population model

Latent-regression fits provide reportable results 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

Keep latent-regression claims within 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.