% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-reports.R
\name{build_apa_outputs}
\alias{build_apa_outputs}
\title{Build APA text outputs from model results}
\usage{
build_apa_outputs(
  fit,
  diagnostics,
  bias_results = NULL,
  context = list(),
  whexact = FALSE
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{diagnostics}{Output from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}.}

\item{bias_results}{Optional output from \code{\link[=estimate_bias]{estimate_bias()}}.}

\item{context}{Optional named list for report context.}

\item{whexact}{Use exact ZSTD transformation.}
}
\value{
An object of class \code{mfrm_apa_outputs} with:
\itemize{
\item \code{report_text}: APA-style Method/Results draft prose
\item \code{table_figure_notes}: consolidated draft notes for tables/visuals
\item \code{table_figure_captions}: draft caption candidates without figure numbering
\item \code{section_map}: package-native section table for manuscript assembly
\item \code{contract}: structured APA reporting contract used for downstream checks
}
}
\description{
Build APA text outputs from model results
}
\details{
\code{context} is an optional named list for narrative customization.
Frequently used fields include:
\itemize{
\item \code{assessment}, \code{setting}, \code{scale_desc}
\item \code{rater_training}, \code{raters_per_response}
\item \code{rater_facet} (used for targeted reliability note text)
\item \code{line_width} (optional text wrapping width for \code{report_text}; default = 92)
}

Output text includes residual-PCA screening commentary if PCA diagnostics are
available in \code{diagnostics}.

For bounded \code{GPCM}, this helper returns a caveated partial reporting bundle
over supported diagnostics, direct tables, and plots. It also includes a
\code{gpcm_boundary} table. Treat the output as slope-aware sensitivity-reporting
text, not FACETS score-side equivalence, automatic operational scoring, or
design-forecasting evidence.

By default, \code{report_text} includes:
\itemize{
\item model/data design summary (N, facet counts, scale range)
\item optimization/convergence metrics (\code{Converged}, \code{Iterations}, \code{LogLik}, \code{AIC}, \code{BIC})
\item anchor/constraint summary (\code{noncenter_facet}, anchored levels, group anchors, dummy facets)
\item latent-regression population-model wording when \code{fit} has an active
\code{population_formula}
\item category/threshold diagnostics (including disordered-step details when present)
\item overall fit, misfit count, and top misfit levels
\item facet reliability/separation, residual PCA summary, and bias-screen counts
}
}
\section{Interpreting output}{

\itemize{
\item \code{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.
\item \code{table_figure_notes}: reusable draft note blocks for table/figure appendices.
\item \code{table_figure_captions}: draft caption candidates aligned to generated outputs.
\item active latent-regression fits add a population-model section and Table 5
notes/captions that distinguish conditional-normal coefficient reporting
from post hoc regression on EAP/MLE scores.
}

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

\section{Typical workflow}{

\enumerate{
\item Build diagnostics (and optional bias results). For \code{RSM} / \code{PCM}
reporting runs, prefer an \code{MML} fit and
\code{diagnose_mfrm(..., diagnostic_mode = "both")}.
\item Run \code{build_apa_outputs(...)}.
\item Check \code{summary(apa)} for completeness.
\item Insert \code{apa$report_text} and note/caption fields into manuscript drafts
after checking the listed cautions.
}
}

\section{Context template}{

A minimal \code{context} list can include fields such as:
\itemize{
\item \code{assessment}: name of the assessment task
\item \code{setting}: administration context
\item \code{scale_desc}: short description of the score scale
\item \code{rater_facet}: rater facet label used in narrative reliability text
}
}

\section{Input validation}{

\code{fit} must be an \code{mfrm_fit} object from \code{\link[=fit_mfrm]{fit_mfrm()}}.
\code{diagnostics} must be an \code{mfrm_diagnostics} object from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}.
\code{context} must be a list (use \code{NULL} or \code{list()} for no extra context).
If supplied, \code{bias_results} must come from \code{\link[=estimate_bias]{estimate_bias()}} or another
package-native bias helper that provides a table component.
}

\examples{
# Fast smoke run: a JML fit and a legacy diagnostic let us build the
# APA bundle and confirm `report_text` is non-empty in well under
# a second.
toy <- load_mfrmr_data("example_core")
fit_quick <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                      method = "JML", maxit = 30)
diag_quick <- diagnose_mfrm(fit_quick, residual_pca = "none",
                             diagnostic_mode = "legacy")
apa_quick <- build_apa_outputs(fit_quick, diag_quick)
nchar(apa_quick$report_text) > 0

\donttest{
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")
apa <- build_apa_outputs(
  fit,
  diag,
  context = list(
    assessment = "Toy writing task",
    setting = "Demonstration dataset",
    scale_desc = "0-2 rating scale",
    rater_facet = "Rater"
  )
)
s_apa <- summary(apa)
s_apa$overview
# Look for: `SentenceCount` non-zero in every section that the run
#   should support (Method / Results / fit / reliability / bias).
#   Zero counts mean that section's prose is empty and the
#   manuscript will need to fill it manually.
chk <- reporting_checklist(fit, diagnostics = diag)
head(chk$checklist[, c("Section", "Item", "DraftReady", "NextAction")])
# Look for: rows with `DraftReady = "yes"` are ready to paste into
#   the manuscript. `"no"` rows tell you which helper / setting
#   needs to run before that paragraph can be drafted, via
#   `NextAction`. Aim for every Visual Displays / Reliability /
#   Diagnostics row to be `"yes"` before submitting.
cat(apa$report_text)
apa$section_map[, c("SectionId", "Available")]
}

}
\seealso{
\code{\link[=build_visual_summaries]{build_visual_summaries()}}, \code{\link[=estimate_bias]{estimate_bias()}},
\code{\link[=reporting_checklist]{reporting_checklist()}}, \link{mfrmr_reporting_and_apa}
}
