% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-tables.R
\name{rating_scale_table}
\alias{rating_scale_table}
\title{Build a rating-scale diagnostics report}
\usage{
rating_scale_table(
  fit,
  diagnostics = NULL,
  whexact = FALSE,
  drop_unused = FALSE
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

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

\item{whexact}{Use exact ZSTD transformation for category fit.}

\item{drop_unused}{If \code{TRUE}, remove categories with zero count from the
displayed category table; \code{summary} and \code{caveats} still retain the omitted
score-support warning.}
}
\value{
A named list with:
\itemize{
\item \code{category_table}: category-level counts, expected counts, fit, and ZSTD
\item \code{threshold_table}: model step/threshold estimates
\item \code{summary}: one-row summary (usage and threshold monotonicity)
\item \code{caveats}: structured score-support warning/review rows
\item \code{diagnostic_mode}: character scalar carried from
\code{diagnostics$diagnostic_mode} (\code{"legacy"}, \code{"both"}, or
\code{"marginal_fit"}); used by downstream reporting helpers to
pick the correct expected-count basis
\item \code{marginal_fit}: list bundle from \code{diagnostics$marginal_fit} when
strict marginal fit was computed, otherwise \code{NULL}. Carries
the raw OverallRMSD / OverallMaxAbsStdResidual / per-cell
tables that feed the \code{MarginalOverallRMSD} columns in
\code{summary}.
}
}
\description{
Build a rating-scale diagnostics report
}
\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 \code{step_facet}, threshold diagnostics should be interpreted within each
\code{StepFacet} rather than as one pooled whole-scale verdict.

Typical checks:
\itemize{
\item sparse category usage (\code{Count}, \code{ExpectedCount})
\item category fit (\code{Infit}, \code{Outfit}, \code{ZStd})
\item threshold ordering within each \code{StepFacet}
(\code{threshold_table$Estimate}, \code{GapFromPrev})
}
}
\section{Interpreting output}{

Start with \code{summary}:
\itemize{
\item \code{UsedCategories} close to total \code{Categories} suggests that most score
categories are represented in the observed data.
\item very small \code{MinCategoryCount} indicates potential instability.
\item \code{ThresholdMonotonic = FALSE} indicates disordered thresholds within at
least one threshold set. In PCM fits, inspect \code{threshold_table} by
\code{StepFacet} before drawing scale-wide conclusions.
}

Then inspect:
\itemize{
\item \code{category_table} for global category-level misfit/sparsity.
\item \code{threshold_table} for adjacent-step gaps and ordering within each
\code{StepFacet}.
}
}

\section{Typical workflow}{

\enumerate{
\item Fit model: \code{\link[=fit_mfrm]{fit_mfrm()}}.
\item Build diagnostics: \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}.
\item Run \code{rating_scale_table()} and review \code{summary()}.
\item Use \code{plot()} to visualize category profile quickly.
}
}

\section{Further guidance}{

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

\section{Output columns}{

The \code{category_table} data.frame contains:
\describe{
\item{Category}{Score category value.}
\item{Count, Percent}{Observed count and percentage of total.}
\item{AvgPersonMeasure}{Mean person measure for respondents in this
category.}
\item{Infit, Outfit}{Category-level fit statistics.}
\item{InfitZSTD, OutfitZSTD}{Standardized fit values.}
\item{ExpectedCount, DiffCount}{Expected count and observed-expected
difference.}
\item{LowCount}{Logical; \code{TRUE} if count is below minimum threshold.}
\item{InfitFlag, OutfitFlag, ZSTDFlag}{Fit-based warning flags.}
\item{ZeroCount, UnusedCategoryType, WeaklyIdentified, CategoryCaveat}{
Structured score-support caveats for retained zero-count categories.}
}

The \code{threshold_table} data.frame contains:
\describe{
\item{Step}{Step label (e.g., "1-2", "2-3").}
\item{Estimate}{Estimated threshold/step difficulty (logits).}
\item{StepFacet}{Threshold family identifier when the fit uses facet-specific
threshold sets.}
\item{GapFromPrev}{Difference from the previous threshold within the same
\code{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).}
\item{ThresholdMonotonic}{Logical flag repeated within each threshold set.
For PCM fits, read this within \code{StepFacet}, not as a pooled item-bank
verdict.}
\item{LowerCategory, UpperCategory, WeaklyIdentified, ThresholdCaveat}{
Adjacent score-category support metadata. Thresholds adjacent to retained
zero-count categories are flagged for cautious interpretation.}
}
}

\section{References}{

\itemize{
\item Andrich, D. (1978). \emph{A rating formulation for ordered response
categories}. Psychometrika, 43(4), 561-573.
\doi{10.1007/BF02293814}
\item Masters, G. N. (1982). \emph{A Rasch model for partial credit scoring}.
Psychometrika, 47(2), 149-174. \doi{10.1007/BF02296272}
\item Linacre, J. M. (2002). What do Infit and Outfit, mean-square and
standardized mean? \emph{Rasch Measurement Transactions, 16}(2), 878.
(Source for the 0.5-1.5 mean-square acceptance band and the
threshold-gap heuristics used in \code{summary(t8)$summary}.)
\item Wind, S. A. (2023). \emph{Detecting rating scale malfunctioning with the
partial credit model and generalized partial credit model}.
Educational and Psychological Measurement, 83(5), 953-983.
\doi{10.1177/00131644221116292} (Recent simulation evidence on
PCM- and GPCM-based rating-scale diagnostics; useful for
interpreting the \code{summary(t8)$summary} flags in the bounded
\code{GPCM} route.)
}
}

\examples{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 30)
t8 <- rating_scale_table(fit)
summary(t8)
summary(t8)$summary
p_t8 <- plot(t8, draw = FALSE)
p_t8$data$plot

}
\seealso{
\code{\link[=diagnose_mfrm]{diagnose_mfrm()}}, \code{\link[=measurable_summary_table]{measurable_summary_table()}}, \code{\link[=plot.mfrm_fit]{plot.mfrm_fit()}},
\link{mfrmr_visual_diagnostics}
}
