Skip to contents

Summarize an mfrm_diagnostics object in a user-friendly format

Source: R/api-methods.R
summary.mfrm_diagnostics.Rd

Summarize an mfrm_diagnostics object in a user-friendly format

Usage

# S3 method for class 'mfrm_diagnostics'
summary(
  object,
  digits = 3,
  top_n = 10,
  detail = c("brief", "full"),
  include_person = FALSE,
  ...
)

Arguments

object

Output from diagnose_mfrm().

digits

Number of digits for printed numeric values.

top_n

Number of highest-absolute-Z fit rows to keep.

detail

Console detail: "brief" (default) prints the first-screen review; "full" prints the additional structured tables.

include_person

If TRUE, person-level identifiers may be printed in fit-review tables. The default keeps identifiers out of console output; person-level rows remain available in the returned object.

...

Reserved for generic compatibility.

Value

An object of class summary.mfrm_diagnostics with:

  • overview: design-level counts and residual-PCA mode

  • decision: the same plain-language fit-readiness decision used by summary(fit), retained ahead of diagnostic screening results

  • fit_readiness, fit_readiness_components, and fit_readiness_parameters: readiness provenance inherited from the source fit and retained separately from diagnostic-screening status

  • status: concise front-door status block for quick review

  • key_warnings: highest-priority warnings to review first

  • next_actions: recommended follow-up helpers

  • diagnostic_basis: guide to legacy versus strict diagnostic targets

  • fit_standardization: guide to the df convention used for fit ZSTD

  • overall_fit: global fit block

  • precision_profile: design-weighted precision summary across the information curve at decile theta points

  • precision_review: separation / reliability / strata review for the sample- and population-basis modes (paired with precision_profile)

  • reliability: facet-level separation/reliability summary

  • facets_chisq: facets-style fixed-effect chi-square heterogeneity screen across non-person facets

  • interrater: inter-rater agreement / pairwise correlation / rater separation overview when a Rater facet is present

  • misfit_flagged: rows flagged by the Infit / Outfit mean-square band

  • fit_screening: counts of all, classified and unclassified elements for the mean-square band and each ZSTD cutoff. Either available statistic crossing a cutoff flags the element; otherwise a missing statistic leaves it unclassified. Rates require every element to be classified. Nonfinite statistics and negative mean squares are unavailable, not passing values.

  • misfit_thresholds: named numeric vector with the misfit lower / upper thresholds used to populate misfit_flagged

  • category_usage: per-category response-frequency summary used to flag empty / collapsed categories

  • top_fit: top maximum |ZSTD| rows with both statistics available

  • marginal_coverage: classified, unclassified and flagged category cells, groups and level pairs; counts of available flags do not describe missing results

  • marginal_fit: optional strict marginal-fit overview when requested

  • top_marginal_cells: largest strict marginal residual cells when requested

  • marginal_pairwise: optional strict pairwise local-dependence overview

  • top_marginal_pairs: largest strict pairwise residual summaries

  • marginal_guidance: interpretation labels for strict marginal diagnostics

  • reporting_map: manuscript-oriented guide to what is covered here versus which companion outputs should be consulted

  • flags: compact flag counts for major diagnostics

  • notes: short interpretation notes

  • digits: numeric-print precision threaded through to print.summary.mfrm_diagnostics()

Details

This method returns a compact diagnostics summary designed for quick review:

  • design overview (observations, persons, facets, categories, subsets)

  • diagnostic-basis guide for legacy versus strict fit paths

  • global fit statistics

  • approximate reliability/separation by facet

  • top facet/person fit rows by absolute ZSTD

  • counts of flagged diagnostics (unexpected, displacement, interactions)

Interpreting output

  • overview: analysis scale, subset count, and residual-PCA mode.

  • fit_readiness: the source fit's versioned readiness row. Diagnostics do not promote a blocked or review-only fit to inferential use.

  • diagnostic_basis: plain-language map of which fit path was computed and what each path means statistically.

  • overall_fit: global fit indices.

  • reliability: facet separation/reliability block, including model and real bounds when available.

  • top_fit: highest |ZSTD| elements for immediate inspection.

  • flags: compact counts for key warning domains.

  • fit_screening: available classifications and unclassified elements for each mean-square/ZSTD rule. A known threshold crossing remains flagged even if the other statistic is missing. Recreate older summaries and reports from existing diagnostics; no MFRM refit is required.

Typical workflow

  1. Run diagnostics with diagnose_mfrm(), using diagnostic_mode = "both" for RSM / PCM when you want legacy continuity plus strict marginal screening.

  2. Review summary(diag) for major warnings and inspect diagnostic_basis before comparing legacy and strict outputs.

  3. Follow up with dedicated tables/plots for flagged domains.

See also

diagnose_mfrm(), summary.mfrm_fit()

Examples

library(mfrmr)

# Saved synthetic MML/RSM analysis of example_operational.
# For your own data, fit a model first; see ?fit_mfrm.
example_fit <- readRDS(system.file("examples", "operational-mml.rds", package = "mfrmr"))
fit <- example_fit$fit

# Check model fit and the support for standard errors and intervals
diagnostics <- example_fit$diagnostics
diagnostic_summary <- summary(diagnostics)
diagnostic_summary$decision
#>               Interpretation FormalInference FitReadiness
#> 1 Ready for formal inference             Yes        ready
#>                                                                                                                                                                                                                                 Why
#> 1 All stored fit-readiness components passed. These checks assess numerical readiness and the requested precision method under the specified model; they do not establish model adequacy or finite-sample coverage for this design.
#>                                                                                            NextAction
#> 1 Inspect `diagnostic_basis` before comparing legacy residual evidence with strict marginal evidence.

diagnostic_summary$key_warnings # Issues to investigate, if present
#> [1] "Unexpected responses flagged: 1."                                                                                                  
#> [2] "Flagged displacement levels: 1."                                                                                                   
#> [3] "MnSq screening flagged 18 element(s) outside the configured 0.5-1.5 band."                                                         
#> [4] "Person-level fit warnings: 18 row(s); identifiers suppressed. Use `include_person = TRUE` only under appropriate privacy controls."
#> [5] "Strict marginal fit flagged 1 group-level summaries."                                                                              
diagnostic_summary$top_fit      # Most unusual residual-based fit statistics
#> # A tibble: 10 × 13
#>    Facet     Level   Infit Outfit InfitZSTD OutfitZSTD DF_Infit DF_Outfit
#>    <chr>     <fct>   <dbl>  <dbl>     <dbl>      <dbl>    <dbl>     <dbl>
#>  1 Person    P022    0.126  0.123     -2.86      -2.88     8.20      8.17
#>  2 Person    P026    0.126  0.117     -2.78      -2.84     7.75      7.71
#>  3 Criterion Content 0.730  0.743     -2.27      -2.09   119.      113.  
#>  4 Person    P035    0.239  0.237     -2.24      -2.25     8.90      8.91
#>  5 Person    P016    2.66   2.53       2.19       2.06     5.95      5.85
#>  6 Person    P008    0.251  0.250     -2.16      -2.17     8.79      8.79
#>  7 Person    P025    2.22   2.18       2.09       2.03     8.94      8.92
#>  8 Rater     R05     0.648  0.640     -1.98      -1.97    51.5      48.5 
#>  9 Person    P012    2.01   2.17       1.72       1.91     7.85      7.78
#> 10 Person    P017    0.265  0.285     -1.90      -1.79     7.42      7.33
#> # ℹ 5 more variables: InfitZSTD_FACETS <dbl>, OutfitZSTD_FACETS <dbl>,
#> #   DF_Infit_FACETS <dbl>, DF_Outfit_FACETS <dbl>, AbsZ <dbl>

# Distinguish residual-based checks from marginal model checks
diagnostic_summary$diagnostic_basis[, c("DiagnosticPath", "Status", "Basis")]
#> # A tibble: 4 × 3
#>   DiagnosticPath                   Status        Basis                          
#>   <chr>                            <chr>         <chr>                          
#> 1 legacy_residual_fit              computed      plugin_residuals_and_eap_tables
#> 2 strict_marginal_fit              computed      latent_integrated_first_order_…
#> 3 strict_pairwise_local_dependence computed      latent_integrated_second_order…
#> 4 posterior_predictive_follow_up   not_available posterior_predictive_replicati…