% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-reports.R
\name{build_visual_summaries}
\alias{build_visual_summaries}
\title{Build warning and narrative summaries for visual outputs}
\usage{
build_visual_summaries(
  fit,
  diagnostics,
  threshold_profile = "standard",
  thresholds = NULL,
  summary_options = NULL,
  whexact = FALSE,
  branch = c("original", "facets")
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

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

\item{threshold_profile}{Threshold profile name (\code{strict}, \code{standard}, \code{lenient}).}

\item{thresholds}{Optional named overrides for profile thresholds.}

\item{summary_options}{Summary options for \code{build_visual_summary_map()}.}

\item{whexact}{Use exact ZSTD transformation.}

\item{branch}{Output branch:
\code{"facets"} adds FACETS crosswalk metadata for manual-aligned reporting;
\code{"original"} keeps package-native summary output.}
}
\value{
An object of class \code{mfrm_visual_summaries} with:
\itemize{
\item \code{warning_map}: visual-level warning text vectors
\item \code{summary_map}: visual-level descriptive text vectors
\item \code{warning_counts}, \code{summary_counts}: message counts by visual key
\item \code{plot_payloads}: reusable draw-free \code{mfrm_plot_data} objects for
\code{comparison}, \code{warning_counts}, \code{summary_counts}, and optionally
\code{category_probability_surface}
\item \code{public_plot_routes}: public helper / draw-free route map for follow-up
\item \code{crosswalk}: FACETS-reference mapping for main visual keys
\item \code{branch}, \code{style}, \code{threshold_profile}: branch metadata
}
}
\description{
Build warning and narrative summaries for visual outputs
}
\details{
This function returns visual-keyed text maps
to support dashboard/report rendering without hard-coding narrative strings
in UI code.

\code{thresholds} can override any profile field by name. Common overrides:
\itemize{
\item \code{n_obs_min}, \code{n_person_min}
\item \code{misfit_ratio_warn}, \code{zstd2_ratio_warn}, \code{zstd3_ratio_warn}
\item \code{pca_first_eigen_warn}, \code{pca_first_prop_warn}
}

\code{summary_options} supports:
\itemize{
\item \code{detail}: \code{"standard"} or \code{"detailed"}
\item \code{max_facet_ranges}: max facet-range snippets shown in visual summaries
\item \code{top_misfit_n}: number of top misfit entries included
}

For bounded \code{GPCM}, this helper returns caveated warning/summary maps over
supported diagnostics, direct tables, and plots. The returned object includes
\code{gpcm_boundary} so score-side, design-forecasting, DFF, and linking routes
remain visibly separate capability rows.
}
\section{Interpreting output}{

\itemize{
\item \code{warning_map}: rule-triggered warning text by visual key.
\item \code{summary_map}: descriptive narrative text by visual key.
\item strict marginal keys appear when \code{diagnose_mfrm(..., diagnostic_mode = "both")}
supplies latent-integrated first-order and pairwise screening summaries.
\item \code{warning_counts} / \code{summary_counts}: message-count tables for QA checks.
\item \code{plot_payloads}: ready-to-reuse \code{mfrm_plot_data} objects for the bundle's
own comparison/count plots and, when step estimates are available, the
exploratory \code{category_probability_surface} data from
\code{plot(fit, type = "ccc_surface", draw = FALSE)}. The surface data carry
\code{category_support}, \code{interpretation_guide}, and \code{reporting_policy} tables
for zero-frequency category and reporting-boundary checks.
\item \code{public_plot_routes}: draw-free helper routes for the dedicated public plot
functions behind each visual family.
}
}

\section{Typical workflow}{

\enumerate{
\item inspect defaults with \code{\link[=mfrm_threshold_profiles]{mfrm_threshold_profiles()}}
\item choose \code{threshold_profile} (\code{strict} / \code{standard} / \code{lenient})
\item optionally override selected fields via \code{thresholds}
\item pass result maps to report/dashboard rendering logic
}
}

\examples{
\donttest{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(
  toy, "Person", c("Rater", "Criterion"), "Score",
  method = "MML", model = "RSM", quad_points = 7, maxit = 30
)
diag <- diagnose_mfrm(fit, residual_pca = "both", diagnostic_mode = "both")
vis <- build_visual_summaries(fit, diag, threshold_profile = "strict")
vis2 <- build_visual_summaries(
  fit,
  diag,
  threshold_profile = "standard",
  thresholds = c(misfit_ratio_warn = 0.20, pca_first_eigen_warn = 2.0),
  summary_options = list(detail = "detailed", top_misfit_n = 5)
)
vis_facets <- build_visual_summaries(fit, diag, branch = "facets")
vis_facets$branch
summary(vis)
p <- plot(vis, type = "comparison", draw = FALSE)
p2 <- plot(vis, type = "warning_counts", draw = FALSE)
vis$plot_payloads$comparison$data$plot
vis$public_plot_routes[, c("Visual", "PlotHelper", "DrawFreeRoute")]
if (interactive()) {
  plot(
    vis,
    type = "comparison",
    draw = TRUE,
    main = "Warning vs Summary Counts (Customized)",
    palette = c(warning = "#cb181d", summary = "#3182bd"),
    label_angle = 45
  )
}
}
}
\seealso{
\code{\link[=mfrm_threshold_profiles]{mfrm_threshold_profiles()}}, \code{\link[=build_apa_outputs]{build_apa_outputs()}},
\code{\link[=plot_marginal_fit]{plot_marginal_fit()}}, \code{\link[=plot_marginal_pairwise]{plot_marginal_pairwise()}}
}
