Build an auto-filled MFRM reporting checklist

Usage

reporting_checklist(
  fit,
  diagnostics = NULL,
  bias_results = NULL,
  hierarchical_structure = NULL,
  include_references = TRUE
)

# S3 method for class 'mfrm_reporting_checklist'
summary(object, top_n = 10, ...)

Arguments

fit: Output from fit_mfrm().
diagnostics: Optional output from diagnose_mfrm(). When NULL, diagnostics are computed with residual_pca = "none".
bias_results: Optional output from estimate_bias() or a named list of such outputs.
hierarchical_structure: Optional output from analyze_hierarchical_structure() for matching retained rating rows. The reviewed facets may be a subset of the fitted facets. After checking the data identity, the "Hierarchical structure review" item is marked DraftReady = TRUE; Detail names the reviewed columns, row count, nested / crossed pairs and ICC availability. This indicates available material within that scope, not a complete design assessment.
include_references: If TRUE, include a compact reference table in the returned bundle.
object: Output from reporting_checklist().
top_n: Maximum number of draft-action rows shown in the compact action table.
...: Reserved for generic compatibility.

Value

A named list with checklist tables. Class: mfrm_reporting_checklist.

For summary(): An object of class summary.mfrm_reporting_checklist with:

overview: run-level counts of available and draft-ready items
section_summary: section-level checklist coverage
software_scope: external-software relationship summary
facets_positioning: report-ready FACETS relationship wording
visual_scope: available plots and data for custom rendering, including the main InterpretationCheck caveat for each type of plot
priority_summary: counts by priority/severity
action_items: highest-priority rows that still need draft work
settings: checklist settings rendered as a compact table
notes: interpretation notes

Details

This helper builds a package-native reporting checklist. It does not try to judge substantive reporting quality; instead, it checks whether the fitted object and related diagnostics contain the evidence typically reported in MFRM write-ups.

Checklist items are grouped into seven core sections:

Method section
Global fit
Facet-level statistics
Element-level statistics
Rating scale diagnostics
Bias/interaction analysis
Visual displays

When a fit uses the latent-regression population-model branch, the checklist also adds a Population Model section covering coefficient reporting, categorical model-matrix coding, complete-case omissions, posterior-basis wording, and ConQuest scope wording.

The output is designed for manuscript preparation, reproducibility records, and reproducible reporting workflows.

summary() method: Summarize a reporting-checklist bundle for manuscript work

What this checklist means

reporting_checklist() is a manuscript-preparation guide. It tells you which reporting elements are already present in the current analysis objects and which still need to be generated or documented. The primary draft-status column is DraftReady; ReadyForAPA is retained as a backward-compatible alias.

What this checklist does not justify

It is not a single run-level pass/fail decision for publication.
DraftReady = TRUE / ReadyForAPA = TRUE does not certify formal inferential adequacy.
Missing bias rows may simply mean bias_results were not supplied.
Study questions, recruitment, rater training, the assignment process, missingness reasons, ethics, and substantive interpretation require the author's study record. Available output does not verify those facts. The "Manuscript coverage map" in vignette("mfrmr-reporting-and-apa", package = "mfrmr") pairs reporting topics with numerical evidence and information to supply manually.

Interpreting output

checklist: one row per reporting item with Available = TRUE/FALSE. DraftReady = TRUE means the item can be drafted into a report with the package's documented caveats. ReadyForAPA is a backward-compatible alias of the same flag; neither field certifies formal inferential adequacy.
fit_readiness, fit_readiness_components, and fit_readiness_parameters: the fitted model's recorded numerical checks and restrictions on inference, overall and by component or parameter. Checklist completeness does not change these records.
section_summary: available items by section.
The Global Fit section includes a "Fit/separation reporting boundary" row that points to precision_review_report(), fit_measures_table(), and facets_fit_review() before users phrase fit, ZSTD, separation, or reliability claims.
software_scope: external-software relationship summary for mfrmr, FACETS, ConQuest, and SPSS-style tabular handoffs.
facets_positioning: report-ready wording that states mfrmr is not a FACETS numerical clone and separates native estimation from FACETS-style handoff or external-table review.
visual_scope: available plots and their interpretation limits. It distinguishes 2D figures from category-surface data for custom rendering; data availability does not mean an interactive 3D renderer is provided. InterpretationCheck gives the main caveat for each type of plot.
references: abbreviated background citations and topics when requested, not a complete bibliography. Verify full records for the methods used; use citation("mfrmr") for the installed software's citation.

Recommended next step

Review the rows with Available = FALSE or DraftReady = FALSE, then add the missing diagnostics, bias results, or narrative context before calling build_apa_outputs() for draft text generation. For RSM / PCM reporting runs where the MML population assumptions are defensible, the most complete package-native route is an MML fit plus diagnose_mfrm(..., diagnostic_mode = "both") so the checklist can see the legacy and strict marginal screens together. A JML route remains available when its estimand and incidental-parameter limitations better match the analysis purpose.

How this differs from operational review

reporting_checklist() is the manuscript/reporting branch of the package. Use it when the question is "what is still missing from the report?" rather than "which observations or links need follow-up?" For operational review:

Use build_misfit_casebook() after diagnose_mfrm() when you need ranked misfit cases and grouping views for local follow-up.
Use build_linking_review() after anchor/drift/chain helpers when you need operational linking triage rather than manuscript-oriented reporting tables.

Typical workflow

Fit with fit_mfrm(). For RSM / PCM reporting runs, prefer method = "MML".
Compute diagnostics with diagnose_mfrm(). For RSM / PCM, prefer diagnostic_mode = "both".
Run reporting_checklist() to see which reporting elements are already available from the current analysis objects.
If the issue is operational rather than manuscript-facing, branch to build_misfit_casebook() or build_linking_review() instead of treating reporting_checklist() as the single review hub.

Saved-result reuse

Supplied screening results must describe this fitted analysis. Results from another fit or older results without identity metadata are refused. See mfrmr_compatibility_layer to recreate them from the saved fit and matching diagnostics without refitting the model. Structural reviews are checked against the reviewed data, not the model's estimates. Row order and unused columns do not affect this match. Reviews of additional input rows or unrecorded grouping columns remain standalone analyses; they cannot establish availability for this fit's checklist.

Examples

# Supplementary workflow: run explicitly to keep routine checks brief.
# example("reporting_checklist", run.dontrun = TRUE)
if (FALSE) { # \dontrun{
library(mfrmr)

# Saved synthetic MML/RSM analysis of example_operational.
# For your own data, fit a model first; see ?fit_mfrm.
example_fit <- readRDS(system.file("examples", "operational-mml.rds", package = "mfrmr"))
fit <- example_fit$fit

# Use the diagnostics saved with this fit
diagnostics <- example_fit$diagnostics

# Which reporting items still need evidence or explanation?
checklist <- reporting_checklist(fit, diagnostics = diagnostics)
checklist$section_summary

# Review the missing items and their suggested next actions
subset(checklist$checklist, !DraftReady,
       c("Section", "Item", "DraftReady", "NextAction"))
# DraftReady is TRUE/FALSE; TRUE means draft material is available with caveats
# Choose follow-up analyses for your question, not merely to make every row TRUE
} # }
# Long-running workflow; run explicitly when needed.
# example("summary.mfrm_reporting_checklist", run.dontrun = TRUE)
if (FALSE) { # \dontrun{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "MML", quad_points = 7, maxit = 30)
diag <- diagnose_mfrm(fit, residual_pca = "both", diagnostic_mode = "both")
chk <- reporting_checklist(fit, diagnostics = diag)
summary(chk)
} # }