build_apa_outputs: Build APA text outputs from model results

In mfrmr: Estimation and Diagnostics for Many-Facet Measurement Models

Build APA text outputs from model results

Description

Build APA text outputs from model results

Usage

build_apa_outputs(
  fit,
  diagnostics,
  bias_results = NULL,
  context = list(),
  whexact = FALSE
)

Arguments

fit	Output from fit_mfrm().
diagnostics	Output from diagnose_mfrm().
bias_results	Optional output from estimate_bias().
context	Optional named list for report context.
whexact	Use exact ZSTD transformation.

Details

context is an optional named list for narrative customization. Frequently used fields include:

• assessment, setting, scale_desc

• rater_training, raters_per_response

• rater_facet (used for targeted reliability note text)

• line_width (optional text wrapping width for report_text; default = 92)

Output text includes residual-PCA screening commentary if PCA diagnostics are available in diagnostics.

By default, report_text includes:

• model/data design summary (N, facet counts, scale range)

• optimization/convergence metrics (Converged, Iterations, LogLik, AIC, BIC)

• anchor/constraint summary (noncenter_facet, anchored levels, group anchors, dummy facets)

• category/threshold diagnostics (including disordered-step details when present)

• overall fit, misfit count, and top misfit levels

• facet reliability/separation, residual PCA summary, and bias-screen counts

Value

An object of class mfrm_apa_outputs with:

• report_text: APA-style Method/Results draft prose

• table_figure_notes: consolidated draft notes for tables/visuals

• table_figure_captions: draft caption candidates without figure numbering

• section_map: package-native section table for manuscript assembly

• contract: structured APA reporting contract used for downstream checks

Interpreting output

• report_text: manuscript-draft narrative covering Method (model specification, estimation, convergence) and Results (global fit, facet separation/reliability, misfit triage, category diagnostics, residual-PCA screening, bias screening). Written in third-person past tense following APA 7th edition conventions, but still intended for human review.

• table_figure_notes: reusable draft note blocks for table/figure appendices.

• table_figure_captions: draft caption candidates aligned to generated outputs.

When bias results or PCA diagnostics are not supplied, those sections are omitted from the narrative rather than producing placeholder text.

Typical workflow

1. Build diagnostics (and optional bias results).

2. Run build_apa_outputs(...).

3. Check summary(apa) for completeness.

4. Insert apa$report_text and note/caption fields into manuscript drafts after checking the listed cautions.

Context template

A minimal context list can include fields such as:

• assessment: name of the assessment task

• setting: administration context

• scale_desc: short description of the score scale

• rater_facet: rater facet label used in narrative reliability text

See Also

build_visual_summaries(), estimate_bias(), reporting_checklist(), mfrmr_reporting_and_apa

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "both")
apa <- build_apa_outputs(
  fit,
  diag,
  context = list(
    assessment = "Toy writing task",
    setting = "Demonstration dataset",
    scale_desc = "0-2 rating scale",
    rater_facet = "Rater"
  )
)
names(apa)
class(apa)
s_apa <- summary(apa)
s_apa$overview
chk <- reporting_checklist(fit, diagnostics = diag)
head(chk$checklist[, c("Section", "Item", "DraftReady", "NextAction")])
cat(apa$report_text)
apa$section_map[, c("SectionId", "Available")]

mfrmr documentation built on March 31, 2026, 1:06 a.m.