% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-generalizability.R
\name{mfrm_d_study}
\alias{mfrm_d_study}
\title{Project G-theory coefficients under alternative D-study designs}
\usage{
mfrm_d_study(
  x,
  design_grid = NULL,
  object_facet = "Person",
  random_facets = NULL,
  residual_scaling = c("highest_order", "single_condition", "none", "sensitivity"),
  ...
)
}
\arguments{
\item{x}{Output from \code{\link[=mfrm_generalizability]{mfrm_generalizability()}} or an \code{mfrm_fit}. If an
\code{mfrm_fit} is supplied, \code{\link[=mfrm_generalizability]{mfrm_generalizability()}} is called first.}

\item{design_grid}{Data frame or named list giving planned counts for each
random measurement facet. Column names may be the facet names themselves
(for example \code{Rater}) or \code{n_} plus the facet name (for example
\code{n_Rater}). When \code{NULL}, one row using the observed number of levels is
returned.}

\item{object_facet, random_facets}{Passed to \code{\link[=mfrm_generalizability]{mfrm_generalizability()}} when
\code{x} is an \code{mfrm_fit}.}

\item{residual_scaling}{How the collapsed residual variance should be scaled
when planned facet counts increase. \code{"highest_order"} treats the residual
as highest-order person-by-all-conditions/error variance and divides by
the product of planned counts. \code{"single_condition"} divides by the smallest
planned facet count, a conservative sensitivity check when unmodeled
person-by-one-facet interactions may dominate. \code{"none"} leaves the residual
unscaled. \code{"sensitivity"} returns all three assumptions for each design
row.}

\item{...}{Additional arguments passed to \code{\link[=mfrm_generalizability]{mfrm_generalizability()}} when \code{x}
is an \code{mfrm_fit}.}
}
\value{
An object of class \code{mfrm_d_study}, a data.frame with one row per
design scenario and columns for planned facet counts, variance terms,
projected \code{G}, projected \code{Phi}, and interpretation bands.
}
\description{
\code{mfrm_d_study()} applies a practical D-study projection to the
variance components from \code{\link[=mfrm_generalizability]{mfrm_generalizability()}}. It answers questions such
as "what happens to \code{G} and \code{Phi} if we use 2, 3, or 4 raters?" without
re-fitting the Rasch/MFRM model.
}
\details{
The projection uses the variance decomposition already estimated by
\code{\link[=mfrm_generalizability]{mfrm_generalizability()}}. For a random measurement facet \code{j}, main-effect
variance contributes \code{sigma2_j / n_j} to the absolute-error denominator.
The residual term contains unmodeled person-by-facet and higher-order
interaction variance in the current simplified G-study, so the selected
\code{residual_scaling} assumption is reported explicitly. The relative-decision
denominator uses only this scaled residual term.

This is a pragmatic D-study planning layer, not a full p x r x i ANOVA
decomposition. If person-by-rater or person-by-item interactions are a
primary estimand, use \code{residual_scaling = "sensitivity"} and treat the output
as planning evidence; fit a fully crossed G-theory model externally when
those interaction components must be estimated separately.

The \code{G} and \code{Phi} values returned here belong to the generalizability-theory
metric family. They should not be interpreted as coefficient alpha, omega,
KR-20, or IRT marginal/separation reliability, even though all of those
summaries may be displayed on a 0--1 scale in broader reporting dashboards.
}
\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)
  mfrm_d_study(gt, data.frame(Rater = c(2, 3, 4), Criterion = 4))
}
}
}
\references{
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.

Brennan, R. L. (2001). \emph{Generalizability theory}. Springer.
}
\seealso{
\code{\link[=mfrm_generalizability]{mfrm_generalizability()}}, \code{\link[=evaluate_mfrm_design]{evaluate_mfrm_design()}},
\code{\link[=recommend_mfrm_design]{recommend_mfrm_design()}}, \code{\link[=plot_data]{plot_data()}}
}
