build_visual_summaries: Build warning and narrative summaries for visual outputs

In mfrmr: Estimation and Diagnostics for Many-Facet Measurement Models

Build warning and narrative summaries for visual outputs

Description

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.

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

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

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

1. inspect defaults with mfrm_threshold_profiles()

2. choose threshold_profile (strict / standard / lenient)

3. optionally override selected fields via thresholds

4. pass result maps to report/dashboard rendering logic

See Also

mfrm_threshold_profiles(), build_apa_outputs()

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
summary(vis)
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
  )
}

mfrmr documentation built on March 31, 2026, 1:06 a.m.