mfrm_generalizability: Generalizability-theory variance decomposition for an MFRM...

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

Generalizability-theory variance decomposition for an MFRM design

Description

Re-fits the rating data underlying an mfrm_fit as a crossed random-effects model Score ~ 1 + (1 | Person) + (1 | Facet1) + ... + Residual via lme4::lmer, and returns the canonical G-theory variance components plus G / Phi coefficients. Useful when reviewers ask for a generalizability-theory complement to the Rasch-style separation / reliability statistics that diagnose_mfrm() already emits.

Usage

mfrm_generalizability(
  fit,
  data = NULL,
  object_facet = "Person",
  random_facets = NULL,
  reml = TRUE
)

Arguments

fit	An mfrm_fit from fit_mfrm().
data	Optional data frame. When NULL, the rating data stored on fit$prep$data is used.
object_facet	Facet that plays the role of the "object of measurement" – typically "Person" (default).
random_facets	Character vector of non-person facets to treat as random conditions of measurement. Default uses every facet other than object_facet.
reml	Logical, passed to lme4::lmer() (default TRUE).

Value

An object of class mfrm_generalizability with:

variance_components

One row per random effect plus residual, with columns Source, Variance, and ProportionVariance.

coefficients

One-row data frame with G (generalizability coefficient, relative decision) and Phi (dependability coefficient, absolute decision), using the single-observation-per-cell convention.

design

Description of the crossed-random model.

Interpretation

• G is appropriate for relative decisions (rank-ordering persons): G = sigma2(p) / (sigma2(p) + sigma2(Residual)).

• The reported Phi is appropriate for absolute decisions (cut-score classification): ⁠Phi = sigma2(p) / (sigma2(p) + sigma2(facet main effects) + sigma2(Residual))⁠, before D-study scaling.

• Use mfrm_d_study() to project G / Phi under planned numbers of raters, items, criteria, or other random measurement facets.

• Reporting bands follow Brennan (2001): G / Phi >= 0.8 for high-stakes decisions, >= 0.7 for routine reporting.

Limitations

This helper formulates the random-effects model with main effects only (Score ~ 1 + (1|Person) + (1|Facet1) + ... + Residual); no explicit (1 | Person:Rater), (1 | Person:Criterion), or (1 | Rater:Criterion) interaction terms are estimated. All two-way and higher interaction variance is therefore folded into the Residual term – the standard one-observation-per-cell approximation – which can bias G downward when person x facet interactions are substantively large. This function reports the one-observation-per-cell baseline. mfrm_d_study() applies D-study scaling, including residual-scaling sensitivity checks, to the same simplified variance-component decomposition. Because person-by-facet interaction terms are not estimated separately, D-study projections remain practical planning evidence rather than a replacement for a fully specified G-theory design.

References

• Cronbach, L. J., Gleser, G. C., Nanda, H., & Rajaratnam, N. (1972). The dependability of behavioral measurements: Theory of generalizability for scores and profiles. Wiley.

• Brennan, R. L. (2001). Generalizability theory. Springer.

See Also

mfrm_d_study(), compute_facet_icc(), diagnose_mfrm()

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 30)
if (requireNamespace("lme4", quietly = TRUE)) {
  gt <- mfrm_generalizability(fit)
  gt$variance_components
  # Look for: a Person variance component well above any single
  #   non-person facet's variance share. Large rater or criterion
  #   variance shares mean those conditions add measurement error
  #   relative to person spread.
  gt$coefficients
  # Look for: G >= 0.7 for routine reporting, >= 0.8 for high-stakes.
  #   G < Phi means absolute decisions are noisier than relative
  #   decisions; review whether facet main effects need anchoring.
}

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