% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-generalizability.R
\name{mfrm_generalizability}
\alias{mfrm_generalizability}
\title{Generalizability-theory variance decomposition for an MFRM design}
\usage{
mfrm_generalizability(
  fit,
  data = NULL,
  object_facet = "Person",
  random_facets = NULL,
  reml = TRUE
)
}
\arguments{
\item{fit}{An \code{mfrm_fit} from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{data}{Optional data frame. When \code{NULL}, the rating data
stored on \code{fit$prep$data} is used.}

\item{object_facet}{Facet that plays the role of the "object of
measurement" -- typically \code{"Person"} (default).}

\item{random_facets}{Character vector of non-person facets to
treat as random conditions of measurement. Default uses every
facet other than \code{object_facet}.}

\item{reml}{Logical, passed to \code{\link[lme4:lmer]{lme4::lmer()}} (default \code{TRUE}).}
}
\value{
An object of class \code{mfrm_generalizability} with:
\describe{
\item{\code{variance_components}}{One row per random effect plus
residual, with columns \code{Source}, \code{Variance}, and
\code{ProportionVariance}.}
\item{\code{coefficients}}{One-row data frame with \code{G}
(generalizability coefficient, relative decision) and
\code{Phi} (dependability coefficient, absolute decision), using the
single-observation-per-cell convention.}
\item{\code{design}}{Description of the crossed-random model.}
}
}
\description{
Re-fits the rating data underlying an \code{mfrm_fit} as a crossed
random-effects model
\code{Score ~ 1 + (1 | Person) + (1 | Facet1) + ... + Residual}
via \code{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 \code{diagnose_mfrm()}
already emits.
}
\section{Interpretation}{

\itemize{
\item \code{G} is appropriate for \strong{relative} decisions (rank-ordering
persons): \code{G = sigma2(p) / (sigma2(p) + sigma2(Residual))}.
\item The reported \code{Phi} is appropriate for \strong{absolute} decisions (cut-score
classification): \verb{Phi = sigma2(p) / (sigma2(p) + sigma2(facet main effects) + sigma2(Residual))}, before D-study scaling.
\item Use \code{\link[=mfrm_d_study]{mfrm_d_study()}} to project \code{G} / \code{Phi} under planned numbers of
raters, items, criteria, or other random measurement facets.
\item Reporting bands follow Brennan (2001): G / Phi >= 0.8 for
high-stakes decisions, >= 0.7 for routine reporting.
}
}

\section{Limitations}{

This helper formulates the random-effects model with main effects
only (\code{Score ~ 1 + (1|Person) + (1|Facet1) + ... + Residual}); no
explicit \code{(1 | Person:Rater)}, \code{(1 | Person:Criterion)}, or
\code{(1 | Rater:Criterion)} interaction terms are estimated. All
two-way and higher interaction variance is therefore folded into
the \code{Residual} term -- the standard one-observation-per-cell
approximation -- which can bias \code{G} downward when person x facet
interactions are substantively large. This function reports the
one-observation-per-cell baseline. \code{\link[=mfrm_d_study]{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.
}

\section{References}{

\itemize{
\item Cronbach, L. J., Gleser, G. C., Nanda, H., & Rajaratnam, N.
(1972). \emph{The dependability of behavioral measurements: Theory
of generalizability for scores and profiles}. Wiley.
\item Brennan, R. L. (2001). \emph{Generalizability theory}. Springer.
}
}

\examples{
\donttest{
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.
}
}
}
\seealso{
\code{\link[=mfrm_d_study]{mfrm_d_study()}}, \code{\link[=compute_facet_icc]{compute_facet_icc()}}, \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}
}
