% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-reports.R
\name{fit_measures_table}
\alias{fit_measures_table}
\title{Build a FACETS-style fit-measures review table}
\usage{
fit_measures_table(
  x,
  diagnostics = NULL,
  facet = NULL,
  include_person = FALSE,
  lower = NULL,
  upper = NULL,
  zstd_cut = 2,
  ci_level = 0.95,
  threshold_profiles = c("literature", "active", "all", "none"),
  fit_df_method = c("engine", "facets", "both"),
  df_zstd_tolerance = 0.05,
  df_zstd_large_shift = 0.5,
  df_ratio_tolerance = 0.05,
  sort_by = c("status", "abs_zstd", "facet", "level"),
  top_n = Inf
)
}
\arguments{
\item{x}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}} or \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}.}

\item{diagnostics}{Optional diagnostics object. If supplied, \code{x} may be the
fitted object used only for provenance.}

\item{facet}{Optional facet-name filter, for example \code{"Rater"}.}

\item{include_person}{Logical; if \code{FALSE} (default), excludes the \code{Person}
facet so operational facet elements are shown first.}

\item{lower, upper}{Optional mean-square review band. Defaults to
\code{\link[=mfrm_misfit_thresholds]{mfrm_misfit_thresholds()}}.}

\item{zstd_cut}{Absolute ZSTD cutoff used for directional underfit/overfit
flags. Default \code{2}.}

\item{ci_level}{Confidence level used to add approximate Wald intervals for
facet measures. Default \code{0.95}.}

\item{threshold_profiles}{Which mean-square threshold profiles to summarize
in addition to the active table band. \code{"literature"} (default) returns
commonly cited bands from Linacre, Bond & Fox, and Wright & Linacre;
\code{"active"} returns only the active band; \code{"all"} returns both; \code{"none"}
suppresses profile summaries.}

\item{fit_df_method}{Degrees-of-freedom convention used when \code{diagnostics}
is computed inside the helper. \code{"engine"} keeps the package-native fit df,
\code{"facets"} makes primary ZSTD columns use the FACETS/Wright-Masters
fourth-moment df convention, and \code{"both"} keeps engine columns primary
while adding FACETS-style companion df/ZSTD columns for comparison.}

\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 \code{zstd_cut} flag status is unchanged.
Default \code{0.5}.}

\item{df_ratio_tolerance}{Relative df-difference threshold used to label
\code{df_convention_difference}; for example, \code{0.05} means a 5 percent
engine-vs-FACETS-style df difference. Default \code{0.05}.}

\item{sort_by}{Sorting rule: \code{"status"} prioritizes underfit/overfit rows,
\code{"abs_zstd"} sorts by largest absolute ZSTD, and \code{"facet"} / \code{"level"}
sort alphabetically.}

\item{top_n}{Optional maximum number of rows in the returned main table.}
}
\value{
A bundle of class \code{mfrm_fit_measures} with:
\itemize{
\item \code{table}: R-friendly fit-measure table with status columns
\item \code{facets_table}: FACETS-style column labels for reporting/review
\item \code{status_summary}: counts by facet and fit status
\item \code{profile_summary_by_facet}: underfit/overfit rates for each threshold
profile and facet
\item \code{profile_summary_overall}: threshold-profile rates pooled over facets
\item \code{df_sensitivity}: row-level engine-vs-FACETS-style df/ZSTD comparison
\item \code{df_sensitive}: subset of rows where df convention changes the ZSTD flag
or materially changes ZSTD interpretation
\item \code{df_sensitivity_summary}: counts of df-sensitive rows
\item \code{underfit}, \code{overfit}, \code{mixed}: filtered row subsets
\item \code{df_conversion_guide}: FACETS-style df/ZSTD comparison guide
\item \code{settings}: thresholds and filters used
}
}
\description{
Build a FACETS-style fit-measures review table
}
\details{
This helper gives users a direct table route for the common FACETS-style
question: which raters, criteria, or other facet elements show underfit or
overfit? It uses the fit statistics already computed by \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}.

Directional labels are based on both mean-square and ZSTD evidence:
high MnSq or positive large ZSTD is labeled \code{underfit}; low MnSq or negative
large ZSTD is labeled \code{overfit}. Rows with conflicting directions are labeled
\code{mixed}. Treat the table as a review screen and inspect substantive context
before removing raters or changing an instrument.

FACETS-style ZSTD comparison is controlled by \code{fit_df_method}. MnSq values
should be compared first; df and ZSTD columns explain how the same MnSq values
are standardized. Use \code{fit_df_method = "both"} when preparing a table for
FACETS users or when explaining why |ZSTD| flags change across df
conventions. The \code{df_zstd_tolerance}, \code{df_zstd_large_shift}, and
\code{df_ratio_tolerance} arguments make the df-sensitivity screen explicit so
the same table can be reproduced under stricter or more permissive review
rules.
}
\examples{
\donttest{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 30)
fm <- fit_measures_table(fit, facet = "Rater")
fm$facets_table
fm$underfit

# Include FACETS-style df/ZSTD companion columns for comparison.
fm_facets <- fit_measures_table(fit, facet = "Rater", fit_df_method = "both")
fm_facets$df_conversion_guide$decision_guide
}
}
\seealso{
\code{\link[=diagnose_mfrm]{diagnose_mfrm()}}, \code{\link[=facets_fit_review]{facets_fit_review()}}, \code{\link[=plot_bubble]{plot_bubble()}},
\code{\link[=mfrm_misfit_thresholds]{mfrm_misfit_thresholds()}}
}
\concept{confidence intervals}
\concept{fit statistics}
