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.

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

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

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

Build diagnostics (and optional bias results).
Run build_apa_outputs(...).
Check summary(apa) for completeness.
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

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)
#> [1] "report_text"           "table_figure_notes"    "table_figure_captions"
#> [4] "section_map"           "contract"             
class(apa)
#> [1] "mfrm_apa_outputs" "list"            
s_apa <- summary(apa)
s_apa$overview
#>   Components NonEmptyComponents TotalCharacters TotalNonEmptyLines Sections
#> 1          3                  3            6219                 90        8
#>   AvailableSections ContentChecks ContentChecksPassed DraftContractPass
#> 1                 7             9                   8             FALSE
#>   ReadyForAPA
#> 1       FALSE
chk <- reporting_checklist(fit, diagnostics = diag)
head(chk$checklist[, c("Section", "Item", "DraftReady", "NextAction")])
#>          Section                   Item DraftReady
#> 1 Method Section    Model specification       TRUE
#> 2 Method Section       Data description       TRUE
#> 3 Method Section        Precision basis       TRUE
#> 4 Method Section            Convergence       TRUE
#> 5 Method Section  Connectivity assessed       TRUE
#> 6     Global Fit Standardized residuals       TRUE
#>                                                                                           NextAction
#> 1              Available; adapt this evidence into the manuscript draft after methodological review.
#> 2              Available; adapt this evidence into the manuscript draft after methodological review.
#> 3 Report the precision tier explicitly and keep the exploratory/hybrid caution in the APA narrative.
#> 4              Available; adapt this evidence into the manuscript draft after methodological review.
#> 5                     Document the connectivity result before making common-scale or linking claims.
#> 6    Use standardized residuals as screening diagnostics, not as standalone proof of model adequacy.
cat(apa$report_text)
#> Method.
#> 
#> Design and data.
#> The analysis focused on Toy writing task in Demonstration dataset. A many-facet Rasch model
#> (MFRM) was fit to 768 observations from 48 persons scored on a 4-category scale (1-4). The
#> design included facets for Rater (n = 4), Criterion (n = 4). The rating scale was described
#> as 0-2 rating scale.
#> 
#> Estimation settings.
#> The RSM specification was estimated using JMLE in the native R MFRM package. Precision
#> summaries were exploratory in this run. Recommended use for this precision profile: Use for
#> screening and calibration triage; confirm formal SE, CI, and reliability with an MML fit..
#> Optimization converged after 67 function evaluations (LogLik = -820.949, AIC = 1755.899,
#> BIC = 2020.595). Constraint settings: noncenter facet = Person; anchored levels = 0
#> (facets: none); group anchors = 0 (facets: none); dummy facets = none.
#> 
#> Results.
#> 
#> Scale functioning.
#> Category usage was adequate (unused categories = 0, low-count categories = 0), and
#> thresholds were ordered. Step/threshold summary: 3 step(s); estimate range = -1.33 to 1.39
#> logits; no disordered steps.
#> 
#> Facet measures.
#> Person measures ranged from -2.18 to 2.69 logits (M = 0.00, SD = 1.10). Rater measures
#> ranged from -0.33 to 0.33 logits (M = 0.00, SD = 0.31). Criterion measures ranged from
#> -0.41 to 0.25 logits (M = 0.00, SD = 0.29).
#> 
#> Fit and precision.
#> Overall fit was acceptable (infit MnSq = 0.99, outfit MnSq = 1.02). 1 of 56 elements
#> exceeded the 0.5-1.5 fit range. Largest misfit signals: Person:P023 (|metric| = 3.06);
#> Person:P018 (|metric| = 1.51); Criterion:Organization (|metric| = 1.42). Criterion
#> exploratory reliability summary = 0.88 (separation = 2.77). Person exploratory reliability
#> summary = 0.90 (separation = 3.01). Rater exploratory reliability summary = 0.90
#> (separation = 3.05). For Rater, exact agreement = 0.36, expected exact agreement = 0.37,
#> adjacent agreement = 0.83.
#> 
#> Residual structure.
#> Exploratory residual PCA (overall standardized residual matrix) showed PC1 eigenvalue =
#> 2.11 (13.2% variance), with PC2 eigenvalue = 1.83. Facet-specific exploratory residual PCA
#> showed the largest first-component signal in Rater (eigenvalue = 1.72, 43.0% variance).
#> Heuristic reference bands: EV >= 1.4 (critical minimum), >= 1.5 (caution), >= 2.0 (common),
#> >= 3.0 (strong); variance >= 5% (minor), >= 10% (caution), >= 20% (strong).
#> 
#> Reporting cautions.
#> Precision note: this run relies on exploratory precision summaries, so confidence intervals
#> and reliability summaries should not be treated as formal inferential quantities.
apa$section_map[, c("SectionId", "Available")]
#>                    SectionId Available
#> 1              method_design      TRUE
#> 2          method_estimation      TRUE
#> 3              results_scale      TRUE
#> 4           results_measures      TRUE
#> 5      results_fit_precision      TRUE
#> 6 results_residual_structure      TRUE
#> 7     results_bias_screening     FALSE
#> 8           results_cautions      TRUE