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

fit: Output from fit_mfrm().
diagnostics: Output from diagnose_mfrm().
threshold_profile: Threshold profile name (strict, standard, lenient).
thresholds: Optional named overrides for profile thresholds.
summary_options: Summary options for build_visual_summary_map().
whexact: Use exact ZSTD transformation.
branch: Output branch: "facets" adds FACETS crosswalk metadata for manual-aligned reporting; "original" keeps package-native summary output.

Value

An object of class mfrm_visual_summaries with:

warning_map: visual-level warning text vectors
summary_map: visual-level descriptive text vectors
warning_counts, summary_counts: message counts by visual key
crosswalk: FACETS-reference mapping for main visual keys
branch, style, threshold_profile: branch metadata

Details

This function returns visual-keyed text maps to support dashboard/report rendering without hard-coding narrative strings in UI code.

thresholds can override any profile field by name. Common overrides:

n_obs_min, n_person_min
misfit_ratio_warn, zstd2_ratio_warn, zstd3_ratio_warn
pca_first_eigen_warn, pca_first_prop_warn

summary_options supports:

detail: "standard" or "detailed"
max_facet_ranges: max facet-range snippets shown in visual summaries
top_misfit_n: number of top misfit entries included

Interpreting output

warning_map: rule-triggered warning text by visual key.
summary_map: descriptive narrative text by visual key.
warning_counts / summary_counts: message-count tables for QA checks.

Typical workflow

inspect defaults with mfrm_threshold_profiles()
choose threshold_profile (strict / standard / lenient)
optionally override selected fields via thresholds
pass result maps to report/dashboard rendering logic

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")
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
#> [1] "facets"
summary(vis)
#> mfrmr Visual Summary Bundle
#> 
#> Overview
#>    Branch    Style ThresholdProfile WarningVisuals SummaryVisuals
#>  original original           strict             11             11
#> 
#> Warning counts
#>                 Visual Messages
#>   residual_pca_overall        5
#>  residual_pca_by_facet        4
#>             wright_map        1
#>        category_curves        0
#>     facet_distribution        0
#>        fit_diagnostics        0
#>  fit_zstd_distribution        0
#>          misfit_levels        0
#>      observed_expected        0
#>            pathway_map        0
#>        step_thresholds        0
#> 
#> Summary counts
#>                 Visual Messages
#>   residual_pca_overall        5
#>  residual_pca_by_facet        4
#>             wright_map        4
#>        category_curves        2
#>  fit_zstd_distribution        2
#>      observed_expected        2
#>            pathway_map        2
#>        step_thresholds        2
#>     facet_distribution        1
#>        fit_diagnostics        1
#>          misfit_levels        1
#> 
#> FACETS crosswalk
#>                 Visual                        FACETS
#>             unexpected            Table 4 / Table 10
#>           fair_average                      Table 12
#>           displacement                       Table 9
#>             interrater           Inter-rater outputs
#>           facets_chisq Facet fixed/random chi-square
#>   residual_pca_overall        Residual PCA (overall)
#>  residual_pca_by_facet       Residual PCA (by facet)
#> 
#> Notes
#>  - Original branch keeps package-native warning/summary map organization.
p <- plot(vis, type = "comparison", draw = FALSE)
p2 <- plot(vis, type = "warning_counts", draw = FALSE)
if (interactive()) {
  plot(
    vis,
    type = "comparison",
    draw = TRUE,
    main = "Warning vs Summary Counts (Customized)",
    palette = c(warning = "#cb181d", summary = "#3182bd"),
    label_angle = 45
  )
}