% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-hierarchical-audit.R
\name{compute_facet_design_effect}
\alias{compute_facet_design_effect}
\title{Compute Kish design effects for each facet}
\usage{
compute_facet_design_effect(
  data,
  facets,
  icc_table = NULL,
  score = NULL,
  person = NULL
)
}
\arguments{
\item{data}{Data frame in long format.}

\item{facets}{Character vector of facet column names.}

\item{icc_table}{Output from \code{\link[=compute_facet_icc]{compute_facet_icc()}} (optional; will be
computed on the fly when \code{NULL}).}

\item{score}{Score column name; required when \code{icc_table} is \code{NULL}.}

\item{person}{Person column; passed through to compute_facet_icc().}
}
\value{
A data.frame of class \code{mfrm_facet_design_effect} with columns
\code{Facet}, \code{AvgClusterSize}, \code{ICC}, \code{DesignEffect}, and \code{EffectiveN}.
}
\description{
Combines per-facet average cluster size with ICC estimates to return
the Kish (1965) design effect \code{Deff = 1 + (m - 1) * rho}, where \code{m}
is the average number of observations per facet element and \code{rho} is
the ICC.
}
\section{Interpreting output}{

\itemize{
\item \code{Deff = 1}: facet behaves like simple random sampling; no
clustering-induced variance inflation.
\item \code{Deff > 1}: variance of the mean estimate is inflated by a factor
of \code{Deff} relative to SRS. \code{EffectiveN = N / Deff} is the sample
size one would need under SRS to achieve the same precision. For
rater-mediated designs, \code{Deff} well above 1 on the Rater facet
means rater-level clustering is noticeable; consider whether
rater generalisation is warranted.
\item Reported \code{ICC} is pulled from \code{icc_table$ICC} (the variance share);
interpretation is the same as in \code{\link[=compute_facet_icc]{compute_facet_icc()}}.
}
}

\section{Typical workflow}{

\enumerate{
\item Run \code{\link[=compute_facet_icc]{compute_facet_icc()}} to get the variance-component shares.
\item Feed the result and the data into
\code{compute_facet_design_effect(data, facets, icc_table = icc)}.
\item Use \code{Deff} as part of the Methods discussion when generalising
over raters or sites. Large \code{Deff} values argue for reporting
robust SEs or moving to a hierarchical model.
}
}

\examples{
\donttest{
toy <- load_mfrmr_data("example_core")
if (requireNamespace("lme4", quietly = TRUE)) {
  icc <- compute_facet_icc(toy, facets = c("Rater", "Criterion"),
                           score = "Score", person = "Person")
  deff <- compute_facet_design_effect(toy,
                                      facets = c("Rater", "Criterion"),
                                      icc_table = icc)
  print(deff)
  # Large DesignEffect -> modest EffectiveN relative to raw N.
}
}
}
\references{
Kish, L. (1965). \emph{Survey Sampling}. New York: Wiley.

Park, I., & Lee, H. (2001). The design effect: Do we know all about
it? In \emph{Proceedings of the American Statistical Association, Survey
Research Methods Section} (pp. 143-148).
}
\seealso{
\code{\link[=compute_facet_icc]{compute_facet_icc()}}, \code{\link[=analyze_hierarchical_structure]{analyze_hierarchical_structure()}}.
}
