fit_measures_table: Build a FACETS-style fit-measures review table

In mfrmr: Estimation and Diagnostics for Many-Facet Measurement Models

Build a FACETS-style fit-measures review table

Description

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

x	Output from fit_mfrm() or diagnose_mfrm().
diagnostics	Optional diagnostics object. If supplied, x may be the fitted object used only for provenance.
facet	Optional facet-name filter, for example "Rater".
include_person	Logical; if FALSE (default), excludes the Person facet so operational facet elements are shown first.
lower, upper	Optional mean-square review band. Defaults to mfrm_misfit_thresholds().
zstd_cut	Absolute ZSTD cutoff used for directional underfit/overfit flags. Default 2.
ci_level	Confidence level used to add approximate Wald intervals for facet measures. Default 0.95.
threshold_profiles	Which mean-square threshold profiles to summarize in addition to the active table band. "literature" (default) returns commonly cited bands from Linacre, Bond & Fox, and Wright & Linacre; "active" returns only the active band; "all" returns both; "none" suppresses profile summaries.
fit_df_method	Degrees-of-freedom convention used when diagnostics is computed inside the helper. "engine" keeps the package-native fit df, "facets" makes primary ZSTD columns use the FACETS/Wright-Masters fourth-moment df convention, and "both" keeps engine columns primary while adding FACETS-style companion df/ZSTD columns for comparison.
df_zstd_tolerance	Smallest absolute engine-vs-FACETS-style ZSTD difference treated as interpretively visible rather than rounding noise in df_sensitivity. Default 0.05.
df_zstd_large_shift	Absolute engine-vs-FACETS-style ZSTD difference labeled large_zstd_shift when the zstd_cut flag status is unchanged. Default 0.5.
df_ratio_tolerance	Relative df-difference threshold used to label df_convention_difference; for example, 0.05 means a 5 percent engine-vs-FACETS-style df difference. Default 0.05.
sort_by	Sorting rule: "status" prioritizes underfit/overfit rows, "abs_zstd" sorts by largest absolute ZSTD, and "facet" / "level" sort alphabetically.
top_n	Optional maximum number of rows in the returned main 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 diagnose_mfrm().

Directional labels are based on both mean-square and ZSTD evidence: high MnSq or positive large ZSTD is labeled underfit; low MnSq or negative large ZSTD is labeled overfit. Rows with conflicting directions are labeled 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 fit_df_method. MnSq values should be compared first; df and ZSTD columns explain how the same MnSq values are standardized. Use fit_df_method = "both" when preparing a table for FACETS users or when explaining why |ZSTD| flags change across df conventions. The df_zstd_tolerance, df_zstd_large_shift, and df_ratio_tolerance arguments make the df-sensitivity screen explicit so the same table can be reproduced under stricter or more permissive review rules.

Value

A bundle of class mfrm_fit_measures with:

• table: R-friendly fit-measure table with status columns

• facets_table: FACETS-style column labels for reporting/review

• status_summary: counts by facet and fit status

• profile_summary_by_facet: underfit/overfit rates for each threshold profile and facet

• profile_summary_overall: threshold-profile rates pooled over facets

• df_sensitivity: row-level engine-vs-FACETS-style df/ZSTD comparison

• df_sensitive: subset of rows where df convention changes the ZSTD flag or materially changes ZSTD interpretation

• df_sensitivity_summary: counts of df-sensitive rows

• underfit, overfit, mixed: filtered row subsets

• df_conversion_guide: FACETS-style df/ZSTD comparison guide

• settings: thresholds and filters used

See Also

diagnose_mfrm(), facets_fit_review(), plot_bubble(), mfrm_misfit_thresholds()

Examples

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

mfrmr documentation built on June 13, 2026, 1:07 a.m.