% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-reports.R
\name{facets_fit_review}
\alias{facets_fit_review}
\title{Review fit standardization against FACETS-style ZSTD conventions}
\usage{
facets_fit_review(
  fit,
  diagnostics = NULL,
  facets_fit = NULL,
  facet_col = NULL,
  level_col = NULL,
  mnsq_tolerance = 0.01,
  external_zstd_tolerance = 0.05,
  df_tolerance = 0.5,
  df_zstd_tolerance = 0.05,
  df_zstd_large_shift = 0.5,
  df_ratio_tolerance = 0.05
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{diagnostics}{Optional output from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}. If it does not
contain FACETS-style fit columns, diagnostics are recomputed with
\code{fit_df_method = "both"} and \code{residual_pca = "none"}.}

\item{facets_fit}{Optional external FACETS fit table, or a list of such
tables. The helper matches rows by \code{Facet} and \code{Level}; a person-only table
with a \code{Person} column is also accepted.}

\item{facet_col, level_col}{Optional explicit column names for the external
FACETS table when automatic detection is not sufficient.}

\item{mnsq_tolerance, external_zstd_tolerance, df_tolerance}{Numeric
tolerances used to classify external FACETS-vs-mfrmr differences.}

\item{df_zstd_tolerance}{Smallest absolute engine-vs-FACETS-style ZSTD
difference treated as interpretively visible rather than rounding noise
in \code{df_sensitivity}. Default \code{0.05}.}

\item{df_zstd_large_shift}{Absolute engine-vs-FACETS-style ZSTD difference
labeled \code{large_zstd_shift} when the |ZSTD| flag status is unchanged.
Default \code{0.5}.}

\item{df_ratio_tolerance}{Relative df-difference tolerance used to classify
the internal engine-vs-FACETS-style df difference; for example, \code{0.05}
means a 5 percent df difference.}
}
\value{
An \code{mfrm_facets_fit_review} bundle with:
\itemize{
\item \code{summary}: one-row overview of internal and external comparison counts
\item \code{standardization}: the fit-standardization guide from diagnostics
\item \code{df_sensitivity}: engine-vs-FACETS-style df/ZSTD comparison using
the same row-level status taxonomy as \code{fit_measures_table()$df_sensitivity}
\item \code{df_sensitive}: subset of \code{df_sensitivity} whose df convention changes
the |ZSTD| flag or materially changes ZSTD interpretation
\item \code{df_sensitivity_summary}: counts by df-sensitivity status
\item \code{external_table_quality}: completeness and duplicate-key review for the
supplied FACETS fit table
\item \code{external_comparison}: optional external FACETS-vs-mfrmr comparison
\item \code{df_conversion_guide}: formulas, column map, and comparison decisions for
FACETS-style df/ZSTD review
\item \code{guidance}: interpretation notes
\item \code{settings}: tolerances and review metadata
}
}
\description{
Review fit standardization against FACETS-style ZSTD conventions
}
\details{
This helper separates two questions that are often conflated when comparing
mfrmr output with FACETS:
\itemize{
\item how much the package-native \code{engine} ZSTD changes when the same MnSq values
are standardized with the FACETS/Wright-Masters fourth-moment df convention;
\item when an external FACETS table is supplied, whether the FACETS-reported rows
match mfrmr's FACETS-style companion columns closely enough for practical
reporting.
}

The review is row-matched by \code{Facet} and \code{Level}. It treats MnSq, ZSTD, and df
differences separately because FACETS documentation makes the df convention
and Wilson-Hilferty/WHEXACT handling central to ZSTD interpretation.

Two upstream boundaries also apply. For \code{method = "MML"} fits, residuals
are evaluated at shrunken EAP person measures while FACETS uses JMLE
estimates, so MnSq itself can differ before standardization; refit with
\code{method = "JML"} for a JMLE-style residual basis. And mfrmr withholds
ZSTD as \code{NA} when the applicable df falls below 1 (Wilson-Hilferty
instability), while FACETS under \code{WHEXACT} can report a value on the same
sparse cell; such NA-vs-finite pairs are availability differences, not
fit differences. Both notes are repeated in the returned \code{guidance} table.
}
\examples{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 30)
review <- facets_fit_review(fit)
summary(review)
}
\seealso{
\code{\link[=diagnose_mfrm]{diagnose_mfrm()}}, \code{\link[=facets_output_contract_review]{facets_output_contract_review()}},
\link{mfrmr_compatibility_layer}
}
