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

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

### Standards basis—and what the template cannot certify

The helpers are APA-oriented drafting aids, informed by the Publication Manual of the American Psychological Association (7th ed.) and the quantitative Journal Article Reporting Standards (JARS-Quant; Appelbaum et al., 2018). MFRM-specific prompts are also tied to the measurement references returned by `reporting_checklist(..., include_references = TRUE)`, including Eckes, Myford and Wolfe, Linacre, Wright and Masters, and Muraki for GPCM.

This is not a certification of APA or JARS compliance. A fitted measurement object cannot supply or verify hypotheses and their confirmatory/exploratory status, recruitment and participant characteristics, ethics, sample-size rationale, the missing-data mechanism and exclusions, multiplicity or deviations from plan, or complete data/code availability statements. Complete those study-level fields manually. Also review effect sizes and uncertainty, statistic-specific rounding (especially p values and confidence intervals), and the target journal’s typography after exporting `apa_table()`.

Reference: Appelbaum, M., Cooper, H., Kline, R. B., Mayo-Wilson, E., Nezu, A. M., & Rao, S. M. (2018). Journal article reporting standards for quantitative research in psychology. American Psychologist, 73(1), 3–25. https://doi.org/10.1037/amp0000191

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`. The `digits` argument applies uniform rounding to all numeric columns; it is deliberately not a statistic-aware APA formatter.

## 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. Fit all candidates on the same q>=31 grid before automatic ranking; below q=31 the raw criteria remain screening/review-only, and a close decision still requires a prespecified denser common-grid check.

    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.

## Recommended sequence

For a compact manuscript-oriented route:

1. `fit_mfrm()`
2. `diagnose_mfrm()`
3. `precision_review_report()`
4. `reporting_checklist()`
5. `build_apa_outputs()`
6. `apa_table()`
7. `build_visual_summaries()`
8. `compare_mfrm()` -> `build_model_choice_review()` when candidate-model comparisons are part of the manuscript

## Related help

- `help("mfrmr_reporting_and_apa", package = "mfrmr")`
- `help("mfrmr_reports_and_tables", package = "mfrmr")`
- `help("reporting_checklist", package = "mfrmr")`
- `help("build_apa_outputs", package = "mfrmr")`