% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/eta2p.R
\name{eta2p_omnibus}
\alias{eta2p_omnibus}
\title{Omnibus (factor-level) Partial Eta-Squared for a Multi-df Effect}
\usage{
eta2p_omnibus(model, effect, data, ...)
}
\arguments{
\item{model}{A fitted lme4 model.}

\item{effect}{The variable/effect name. For a factor main effect, the bare
variable name (e.g. "rating_type"). For an interaction, the colon form of
the term as it appears in the design matrix (e.g. "group:rating_type").}

\item{data}{The data frame used to fit the model.}

\item{...}{Passed to eta2p() to obtain the error denominator (design,
cross_vars, subj_var, item_var, nest_vars, operative, etc.).}
}
\value{
An object of class \code{"eta2p_omnibus"}: a list containing
\item{eta2p}{The omnibus (factor-level) partial eta-squared.}
\item{variance_effect}{Variance of the summed fitted contribution of all the
effect's design-matrix columns (includes covariances among them).}
\item{variance_error}{Error variance denominator (from \code{eta2p()}).}
\item{effect}{The effect name requested.}
\item{coefficients}{The design-matrix column names aggregated.}
\item{n_df}{Number of columns aggregated (the effect's degrees of freedom;
matches the df of the corresponding omnibus test).}
\item{type}{\code{"omnibus"}.}
}
\description{
For a multi-level factor or a multi-df interaction, computes a single
factor-level partial eta-squared corresponding to the omnibus test of that
effect (e.g. the chi-square or F test on all of its degrees of freedom),
rather than one value per contrast. The variance attributed to the effect is
the variance of the summed fitted contribution of all the design-matrix
columns belonging to the effect (which correctly includes the covariances
among those columns); the error denominator is the same one eta2p() uses.
}
\details{
\code{batch_eta2p()} and a per-coefficient call to \code{eta2p()} return one
value per contrast (per design-matrix column). For a multi-level factor or a
multi-df interaction, none of those single values corresponds to the omnibus
test of the whole effect (the \emph{F} or chi-square test on all of its
degrees of freedom). This function fills that gap.

The omnibus variance explained is computed as the variance of the
\emph{summed} fitted contribution of all the effect's columns,
\eqn{\mathrm{Var}(\sum_j b_j x_j)}, which correctly includes the covariances
among the dummy/contrast columns. Simply adding the per-coefficient
numerators would drop those covariances and is incorrect. The error
denominator is the same one \code{eta2p()} uses, so the result remains a
partial eta-squared (error-variance denominator), \emph{not} a total-variance
\eqn{R^2}; expect it to differ from \code{r2glmm::r2beta()}, which targets the
latter.
}
\examples{
\donttest{
library(lme4)
set.seed(1)
d <- expand.grid(subject = factor(1:30), item = factor(1:12),
                 emo = factor(c("a", "b", "c", "d")))
d$y <- as.integer(d$emo) + rnorm(30)[d$subject] + rnorm(nrow(d))
m <- lmer(y ~ emo + (1 | subject) + (1 | item), data = d)
# one factor-level value to pair with the omnibus test of `emo`:
eta2p_omnibus(m, "emo", d, design = "crossed",
              cross_vars = c("subject", "item"))
}

}
\seealso{
\code{\link{eta2p}} for single-coefficient values and
\code{\link{batch_eta2p}} for all coefficients at once.
}
