% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-results.R
\name{mfrm_report}
\alias{mfrm_report}
\title{Build report-ready output from \code{mfrm_results()}}
\usage{
mfrm_report(
  x,
  style = c("qc", "apa", "validation", "reviewer", "technical"),
  output = c("object", "markdown", "html", "tables")
)
}
\arguments{
\item{x}{An \code{\link[=mfrm_results]{mfrm_results()}} object.}

\item{style}{Report emphasis. \code{"qc"} is the default first-screen report.
\code{"apa"} emphasizes manuscript wording, \code{"validation"} emphasizes the
validity-argument boundary, \code{"reviewer"} emphasizes reviewer response
preparation, and \code{"technical"} emphasizes appendix/reproducibility routes.}

\item{output}{Return format: \code{"object"} for an \code{mfrm_report} object,
\code{"markdown"} for a character scalar, \code{"html"} for a temporary HTML file,
or \code{"tables"} for the report's named data-frame list.}
}
\value{
Depending on \code{output}, an \code{mfrm_report} object, a Markdown character
scalar, an \code{mfrm_report_html} object, or a named list of data frames.
}
\description{
\code{mfrm_report()} is a report-synthesis layer for an existing
\code{\link[=mfrm_results]{mfrm_results()}} object. It does not refit the model, recompute diagnostics,
or add new validity rules. Instead, it turns the comprehensive first-screen
result into a first-screen table, section plan, claim-readiness table,
report-gap table, report-index table, template-index table,
fit-criteria table, result-specific fit evidence summaries,
fit-reporting wording templates, precision/separation reporting templates,
bias/DFF reporting templates, misfit/pathway reporting templates,
linking/anchor reporting templates, ZSTD-convention table,
evidence-boundary table, next-action table, and optional Markdown or HTML
report.
}
\details{
The intended workflow is:
\enumerate{
\item Create \code{res <- mfrm_results(fit, include = ...)}.
\item Inspect \code{summary(res)$triage} and \code{summary(res)$next_actions}.
\item Create \code{report <- mfrm_report(res, style = "qc")}.
\item Read \code{summary(report)} and \code{report$first_screen} before opening detailed
report tables.
\item Use \code{report$report_index} to choose the next \code{PrimaryTable},
\code{TemplateTable}, plot route, or export route.
\item Use \code{report$template_index} before copying APA/QC/validation wording.
\item Use \code{style = "apa"}, \code{"validation"}, \code{"reviewer"}, or \code{"technical"} only
when that reporting question is needed.
}

Report rows deliberately distinguish evidence from claims. The
\code{first_screen} table is the compact entry point: it gives an overall row and
one row per major evidence area with status, readiness, main issue, next
action, and primary route. The
\code{summary.mfrm_report} method summarizes that first screen into immediate
actions, optional not-requested sections, claim-readiness counts, report
gaps, and template-boundary rows without introducing a new pass/fail
decision. The default print method follows the same short reading order and
does not print every detailed evidence table. HTML output places the same
reader guidance and report-summary tables before the full Markdown text so
the browser view starts from the first-screen route. The
\code{report_index} table is the detailed evidence-route index: it lists the
major report areas, evidence status, readiness label, review-signal count,
and the primary/template tables, evidence routes, template routes, plot
routes, export route, and \code{mfrm_results(include = ...)} preset to inspect
next. In ordinary use, open detailed tables through the \code{PrimaryTable} and
\code{TemplateTable} columns rather than scanning every element of \code{report$tables}.
The
\code{template_index} table then stacks all fit, precision, bias, misfit, and
linking wording templates into a single boundary/claim-strength index before
users drill into the area-specific template tables. The
\code{claim_readiness} table marks which report claims are ready, caveated,
unavailable, or require additional requested sections. The \code{report_gaps}
table turns those statuses into follow-up actions. The fit-specific tables
keep multiple MnSq threshold profiles, observed fit-status counts, and
engine-vs-FACETS-style ZSTD conventions visible, including the
small-df/capping boundary used for FACETS-style ZSTD review. They summarize
the stored \code{fit_measures} component from \code{mfrm_results()}; \code{mfrm_report()}
itself does not recompute diagnostics. The \code{fit_reporting_templates} table
turns those counts into cautious APA/QC/validation/reviewer wording
scaffolds while keeping MnSq, ZSTD standardization, df sensitivity, and
separation/reliability in separate sentences. All reporting-template tables
share \code{EvidenceTable}, \code{EvidenceRoute}, \code{BoundaryType}, \code{ClaimStrength}, and
\code{RecommendedUse} columns so each template can be traced back to its evidence
and claim boundary. \code{template_index} stacks those columns across all
template areas so report authors can review unsupported or caveated wording
before opening the full template text. The \code{precision_reporting_templates}
table does the same for separation, reliability, and strata using the
stored precision review and \code{diagnostics$reliability}. The
\code{bias_reporting_templates} table is
available when the source result was built with \code{include = "bias"} and keeps
facet-level screens, interaction-bias contrasts, DFF follow-up, and fairness
conclusions in separate lanes. The \code{misfit_reporting_templates} table is
available when the source result was built with \code{include = "misfit_review"}
and keeps unexpected responses, displacement, pathway-map evidence, and
case-review actions separate. The \code{linking_reporting_templates} table is
available when the source result was built with \code{include = "linking"} and
keeps anchor readiness, drift review, equating-chain review, and GPCM
support boundaries separate. For example, fit and separation are not
collapsed into a single pass/fail statement; bias screens are not treated
as final fairness conclusions; pathway/misfit rows are case-review prompts;
and drift/equating claims require multiple fitted forms or waves.
}
\examples{
\donttest{
toy <- load_mfrmr_data("example_core")
toy_small <- toy[toy$Person \%in\% unique(toy$Person)[1:6], , drop = FALSE]
fit <- fit_mfrm(toy_small, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 30)
res <- mfrm_results(fit, include = c("fit", "diagnostics", "tables"))

report <- mfrm_report(res, style = "qc")
summary(report)
report$first_screen
report$report_index[, c("Area", "Readiness", "PrimaryTable",
                        "TemplateTable", "PlotRoute")]
report$template_index[, c("Area", "Topic", "BoundaryType",
                          "ClaimStrength", "EvidenceRoute")]

# Open detailed evidence only after the index points to it.
fit_primary <- report$report_index$PrimaryTable[
  report$report_index$Area == "Fit"
][1]
report$tables[[fit_primary]]

mfrm_report(res, output = "markdown")
mfrm_report(res, output = "html")
}
}
\seealso{
\code{\link[=mfrm_results]{mfrm_results()}}, \code{\link[=export_mfrm_results]{export_mfrm_results()}},
\code{\link[=build_apa_outputs]{build_apa_outputs()}}, \code{\link[=reporting_checklist]{reporting_checklist()}},
\code{\link[=mfrmr_output_guide]{mfrmr_output_guide()}}
}
