% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-reports.R
\name{facets_fit_df_guide}
\alias{facets_fit_df_guide}
\title{Guide FACETS-style fit df and ZSTD standardization}
\usage{
facets_fit_df_guide(include_references = TRUE)
}
\arguments{
\item{include_references}{If \code{TRUE}, include source-reference rows for the
FACETS/Winsteps documentation and Rasch measurement texts that motivate the
guide.}
}
\value{
A bundle of class \code{mfrm_facets_fit_df_guide} with:
\itemize{
\item \code{summary}: one-row scope summary
\item \code{formula_guide}: formulas and package columns
\item \code{column_guide}: where engine and FACETS-style columns appear
\item \code{decision_guide}: recommended comparison steps
\item \code{interpretation_guide}: how to read common difference patterns
\item \code{references}: optional source-reference rows
\item \code{settings}: guide metadata
}
}
\description{
\code{facets_fit_df_guide()} gives a compact user-facing guide to the degrees of
freedom and ZSTD standardization choices used when comparing mfrmr fit
output with FACETS-style fit tables.
}
\details{
The guide separates mean-square size from ZSTD standardization. Infit and
outfit MnSq values answer how large the residual noise or predictability
signal is. ZSTD values standardize those MnSq values using a degrees-of-
freedom convention and a Wilson-Hilferty-style transformation, so ZSTD can
differ even when the underlying MnSq values are nearly identical.

Two boundaries sit upstream of any df comparison. First, the residual
basis: \code{method = "MML"} fits evaluate residuals at shrunken EAP person
measures, whereas FACETS evaluates them at JMLE estimates, so MnSq values
themselves can differ before any standardization is applied; refit with
\code{method = "JML"} when the comparison requires a JMLE-style residual basis.
Second, small df: \code{mfrmr} returns \code{NA} ZSTD when \code{df < 1} because the
Wilson-Hilferty transformation is numerically unstable there, while
FACETS/Winsteps under \code{WHEXACT} can continue with a linear approximation,
so sparse cells can show \code{NA} against a finite external value without
indicating a fit difference.
}
\examples{
facets_fit_df_guide()
facets_fit_df_guide()$decision_guide
}
\seealso{
\code{\link[=diagnose_mfrm]{diagnose_mfrm()}}, \code{\link[=fit_measures_table]{fit_measures_table()}},
\code{\link[=facets_fit_review]{facets_fit_review()}}
}
