Build a rating-scale diagnostics report

Build a rating-scale diagnostics report

Usage

rating_scale_table(
  fit,
  diagnostics = NULL,
  whexact = FALSE,
  drop_unused = FALSE
)

Arguments

fit

Output from fit_mfrm().

diagnostics

Optional output from diagnose_mfrm().

whexact

Use exact ZSTD transformation for category fit.

drop_unused

If TRUE, remove categories with zero count.

Value

A named list with:

• category_table: category-level counts, expected counts, fit, and ZSTD

• threshold_table: model step/threshold estimates

• summary: one-row summary (usage and threshold monotonicity)

Details

This helper provides category usage/fit statistics and threshold summaries for reviewing score-category functioning. The category usage portion is a global observed-score screen. In PCM fits with a step_facet, threshold diagnostics should be interpreted within each StepFacet rather than as one pooled whole-scale verdict.

Typical checks:

• sparse category usage (Count, ExpectedCount)

• category fit (Infit, Outfit, ZStd)

• threshold ordering within each StepFacet (threshold_table$Estimate, GapFromPrev)

Interpreting output

Start with summary:

• UsedCategories close to total Categories suggests that most score categories are represented in the observed data.

• very small MinCategoryCount indicates potential instability.

• ThresholdMonotonic = FALSE indicates disordered thresholds within at least one threshold set. In PCM fits, inspect threshold_table by StepFacet before drawing scale-wide conclusions.

Then inspect:

• category_table for global category-level misfit/sparsity.

• threshold_table for adjacent-step gaps and ordering within each StepFacet.

Typical workflow

1. Fit model: fit_mfrm().

2. Build diagnostics: diagnose_mfrm().

3. Run rating_scale_table() and review summary().

4. Use plot() to visualize category profile quickly.

Further guidance

For a plot-selection guide and a longer walkthrough, see mfrmr_visual_diagnostics and vignette("mfrmr-visual-diagnostics", package = "mfrmr").

Output columns

The category_table data.frame contains:

Category

Score category value.

Count, Percent

Observed count and percentage of total.

AvgPersonMeasure

Mean person measure for respondents in this category.

Infit, Outfit

Category-level fit statistics.

InfitZSTD, OutfitZSTD

Standardized fit values.

ExpectedCount, DiffCount

Expected count and observed-expected difference.

LowCount

Logical; TRUE if count is below minimum threshold.

InfitFlag, OutfitFlag, ZSTDFlag

Fit-based warning flags.

The threshold_table data.frame contains:

Step

Step label (e.g., "1-2", "2-3").

Estimate

Estimated threshold/step difficulty (logits).

StepFacet

Threshold family identifier when the fit uses facet-specific threshold sets.

GapFromPrev

Difference from the previous threshold within the same StepFacet when thresholds are facet-specific. Gaps below 1.4 logits may indicate category underuse; gaps above 5.0 may indicate wide unused regions (Linacre, 2002).

ThresholdMonotonic

Logical flag repeated within each threshold set. For PCM fits, read this within StepFacet, not as a pooled item-bank verdict.

See also

diagnose_mfrm(), measurable_summary_table(), plot.mfrm_fit(), mfrmr_visual_diagnostics

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
t8 <- rating_scale_table(fit)
summary(t8)
#> mfrmr Rating Scale Summary 
#>   Class: mfrm_rating_scale
#>   Components (3): category_table, threshold_table, summary
#> 
#> Category/threshold summary
#>  Categories UsedCategories MinCategoryCount MaxCategoryCount MeanCategoryInfit
#>           4              4              136              252             1.212
#>  MeanCategoryOutfit ThresholdMonotonic
#>               1.148               TRUE
#> 
#> Category rows: category_table
#>  Category Count AvgPersonMeasure ExpectedAverage Infit Outfit MeanResidual
#>         1   139           -0.985           1.864 1.807  1.602       -0.864
#>         2   241           -0.376           2.262 0.614  0.781       -0.262
#>         3   252            0.328           2.734 0.556  0.618        0.266
#>         4   136            1.069           3.145 1.871  1.590        0.855
#>  DF_Infit DF_Outfit Percent InfitZSTD OutfitZSTD ExpectedCount ExpectedPercent
#>    70.923       139  18.099     3.949      4.294       139.007            18.1
#>   137.987       241  18.099    -3.702     -2.574       240.946            18.1
#>   145.246       252  18.099    -4.505     -4.968       252.005            18.1
#>    66.709       136  18.099     4.081      4.175       136.042            18.1
#>  DiffCount DiffPercent LowCount InfitFlag OutfitFlag ZSTDFlag
#>     -0.007      -0.001    FALSE      TRUE       TRUE     TRUE
#>      0.054      -0.001    FALSE     FALSE      FALSE     TRUE
#>     -0.005      -0.001    FALSE     FALSE      FALSE     TRUE
#>     -0.042      -0.001    FALSE      TRUE       TRUE     TRUE
#> 
#> Notes
#>  - Rating-scale diagnostics with category usage, fit, and threshold ordering.
summary(t8)$summary
#>   Categories UsedCategories MinCategoryCount MaxCategoryCount MeanCategoryInfit
#> 1          4              4              136              252          1.211781
#>   MeanCategoryOutfit ThresholdMonotonic
#> 1           1.147617               TRUE
p_t8 <- plot(t8, draw = FALSE)
class(p_t8)
#> [1] "mfrm_plot_data" "list"