% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/eta2p.R
\name{eta2p}
\alias{eta2p}
\title{Partial Eta-Squared for Linear Mixed Models}
\usage{
eta2p(
  model,
  effect,
  data,
  design = c("crossed", "nested", "mixed"),
  subj_var = NULL,
  item_var = NULL,
  cross_vars = NULL,
  nest_vars = NULL,
  effect_level = NULL,
  var_x = NULL,
  operative = FALSE,
  partial_predictors = TRUE,
  ci = FALSE,
  ci_level = 0.95,
  n_boot = 1000,
  seed = NULL,
  verbose = FALSE
)
}
\arguments{
\item{model}{A fitted model object from \code{lme4::lmer()}.}

\item{effect}{Character string specifying the fixed effect to analyze.
May be given either as the model coefficient name (e.g.
\code{"Group75yr"}) or as the underlying variable name (e.g.
\code{"Group"}); a variable name that maps to a single coefficient is
resolved automatically (with a message). A variable that maps to several
coefficients (a multi-level factor) raises an informative error pointing to
\code{eta2p_omnibus()} (for one factor-level value) or
\code{batch_eta2p()} (for per-coefficient values). Factor predictors and
factor random slopes are read from the model design matrix / model frame,
so no manual recoding to numeric is required.}

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

\item{design}{Character string: \code{"crossed"}, \code{"nested"}, or
\code{"mixed"}. Use \code{"mixed"} when the model contains both crossed and
nested random effects (e.g., photos nested within models, but both crossed
with participants).}

\item{subj_var}{Character string specifying the subject/participant grouping
variable. Retained for backward compatibility; prefer \code{cross_vars}.}

\item{item_var}{Character string specifying the item/stimulus grouping
variable. Retained for backward compatibility; prefer \code{cross_vars}.}

\item{cross_vars}{Character vector of grouping variable names that are
\emph{crossed} with each other and with the nested hierarchy
(e.g., \code{c("participant")} or \code{c("participant", "rater")}).
Supersedes \code{subj_var} and \code{item_var} when provided.}

\item{nest_vars}{Character vector of nesting variables ordered from lowest
to highest level (e.g., \code{c("photo", "model")} when photos are nested
within models). Required for \code{design = "nested"} or
\code{design = "mixed"}.}

\item{effect_level}{Character string specifying the level at which the effect
varies (e.g., \code{"L1"}, \code{"L2"}). If \code{NULL}, detected
automatically from \code{nest_vars}.}

\item{var_x}{Optional numeric. Pre-computed variance of the predictor (or
interaction product). If supplied, overrides the internal \code{var()}
calculation from \code{data}. Useful when raw data are unavailable but the
predictor variance is known (e.g., from design: a +/-1 binary predictor has
\code{var_x = 1}).}

\item{operative}{Logical. If \code{TRUE}, calculates operative effect size
(excludes variance components that do not contribute to the SE of the
effect). Default is \code{FALSE}.}

\item{partial_predictors}{Logical. If \code{TRUE} (the default), the variance
attributed to a single (non-interaction) predictor is its \emph{unique}
(semipartial) variance -- the variance remaining after removing the part
linearly predictable from the other fixed-effect predictors, equivalently
\eqn{\mathrm{Var}(X) \times \mathrm{tol}(X)} where \eqn{\mathrm{tol}} is the
predictor's tolerance. This yields a measure that reflects only the unique
contribution of the predictor and declines as its redundancy with the
others increases. If \code{FALSE}, the predictor's \emph{total} variance is
used instead (the raw decomposition). For centered, orthogonal designs the
two are identical; they differ only when predictors are correlated. See
Details. Has no effect on interaction terms (whose components are always
centered) or when \code{var_x} is supplied.}

\item{ci}{Logical. If \code{TRUE}, computes a confidence interval for
\code{eta2p} by parametric bootstrap (\code{lme4::bootMer}): new responses
are simulated from the fitted model, the model is refit, and \code{eta2p}
is recomputed on each replicate, with percentile limits taken from the
resulting distribution. This is the appropriate interval for a ratio of
REML variance components, which has no closed-form sampling distribution.
Each replicate refits the model, so this is opt-in and can be slow on large
models. Default is \code{FALSE}.}

\item{ci_level}{Numeric confidence level for the bootstrap interval (default
\code{0.95}).}

\item{n_boot}{Integer number of bootstrap replicates when \code{ci = TRUE}
(default \code{1000}). Use a smaller value (e.g. 100-200) to gauge runtime
on large models before committing to the full count.}

\item{seed}{Optional integer seed for reproducible bootstrap intervals.}

\item{verbose}{Logical. If \code{TRUE}, prints detailed results. Default is
\code{FALSE}.}
}
\value{
An object of class \code{"eta2p_lmm"} containing:
\item{eta2p}{Partial eta-squared value.}
\item{variance_effect}{Variance explained by the effect.}
\item{variance_error}{Error variance (denominator).}
\item{effect}{Name of the effect.}
\item{design}{Design type: \code{"crossed"}, \code{"nested"}, or
\code{"mixed"}.}
\item{operative}{Whether operative effect size was calculated.}
\item{ci_level, ci_lower, ci_upper, boot_n, boot_method}{(Only when
\code{ci = TRUE}) The confidence level, the lower and upper percentile
bootstrap limits, the number of usable bootstrap replicates, and the
method label (\code{"parametric (bootMer)"}).}
\item{variance_components}{List of individual variance components. For
\code{"mixed"} designs this is a list with \code{$crossed} and
\code{$nested} sub-lists.}
\item{within_between}{(Mixed/crossed designs) Named list or vector
classifying each grouping factor as \code{"within"} or \code{"between"}
with respect to the focal effect. Only populated when
\code{operative = TRUE}.}
\item{cross_vars}{(Crossed/mixed designs) Crossed grouping variable names.}
\item{nest_vars}{(Nested/mixed designs) Nested grouping variable names.}
\item{n_per_factor}{(Crossed designs) Number of units per crossed factor.}
\item{n_cross}{(Mixed designs) Number of units per crossed factor.}
\item{n_nested}{(Mixed designs) Number of units per nested factor.}
\item{n_levels}{(Nested designs) Number of units per nested level.}
\item{effect_level}{(Nested/mixed designs) Detected or supplied effect
level.}
}
\description{
Calculates partial eta-squared effect sizes for fixed effects in linear mixed
models with crossed, nested, or mixed (crossed-and-nested) random effects.
}
\details{
\subsection{Variance decomposition}{
The function implements a variance decomposition approach for computing
partial eta-squared in mixed models. The variance a fixed effect explains is
\deqn{\mathrm{Var}_{\text{explained}} = b^2 \times \sigma^2_X,}
where \eqn{b} is the (partial) fixed-effect coefficient and \eqn{\sigma^2_X}
is the variance of the predictor column. Random slope variances are
translated to the outcome scale by the same principle,
\deqn{\sigma^2_{\text{slope}}(Y) = \sigma^2_b \times \sigma^2_X.}
For an interaction, \eqn{\sigma^2_X} is the variance of the product of the
\emph{mean-centered} constituent predictors (see "Centering" below). The
\code{var_x} argument bypasses this computation when the variance is known a
priori.
}

\subsection{Centering and intended scope}{
These quantities are exact when predictors are \strong{mean-centered}, which
is standard and recommended practice for the experimental and contrast-coded
designs the method primarily targets (sum/contrast coding centers factors
automatically). Two points:
\itemize{
\item \strong{Interactions: components are centered automatically.} For an
interaction the function mean-centers each \emph{constituent} predictor
and then takes the variance of their product (it does \emph{not} center
the product itself). This makes the interaction effect size invariant to
the location of the constituents: re-centering a predictor by a constant
leaves the model fit and the interaction coefficient unchanged, and now
also leaves the effect size unchanged. (The variance of the \emph{raw}
product depends on the constituents' means and so is not well defined as
an effect size; this is why the centering is applied. The constituent
predictors should still be centered before fitting for the coefficients
themselves to be interpretable, but the effect-size value no longer
depends on it.)
\item \strong{Main effects / random slopes use} \eqn{\sigma^2_X}\strong{,
which equals} \eqn{E[X^2]} \strong{only when} \eqn{X} \strong{is
centered.} The function does not center main-effect predictors (doing so
would not change \eqn{\sigma^2_X = \mathrm{Var}(X)}, which is already
location-invariant), but the random-slope translation
\eqn{\sigma^2_b \sigma^2_X} is exact only for centered predictors;
center continuous predictors before fitting.
}
Under correlated predictors, each \eqn{b} is a partial coefficient (it
controls for the other predictors). By default (\code{partial_predictors =
TRUE}) it is multiplied by the predictor's \emph{unique} variance -- the
variance remaining after the part linearly predictable from the other
predictors is removed -- so the variance attributed to the predictor is
\deqn{b^2 \, \mathrm{Var}(X \mid X_{others}) = b^2 \, \mathrm{Var}(X) \,
      \mathrm{tol}(X),}
where \eqn{\mathrm{tol}(X) = 1 - R^2_{X \sim X_{others}}} is the predictor's
tolerance. (The two forms are algebraically identical.) This yields a
semipartial variance-explained measure: it reflects only the unique
contribution of the predictor and declines as its redundancy with the others
increases, matching the unique-variance target estimated by an explained-
error (model-comparison) approach.

Setting \code{partial_predictors = FALSE} instead uses the predictor's
\emph{total} variance \eqn{\sigma^2_X}. The resulting per-predictor values
are partial (conditional) effect sizes that do not isolate unique variance
when predictors are correlated. For centered, orthogonal designs the two
options coincide exactly, because the covariance among predictors is zero, so
the choice matters only under collinearity.

The tolerance correction is also what makes the interaction handling
location-invariant: centering an interaction's components is equivalent to
the \eqn{\mathrm{Var} \times \mathrm{tol}} of the product, which is constant
across re-centering. The choice is independent of the operative option, which
concerns the error denominator rather than the numerator. See Rights & Sterba
(2019) on the partial-versus-total distinction.
}

\subsection{General vs. operative effect sizes}{
For \strong{general effect sizes} (default), all variance components appear
in the denominator. For \strong{operative effect sizes}
(\code{operative = TRUE}), only components that contribute to the standard
error of the effect are included. In mixed designs, each grouping factor
(both crossed and nested) is independently classified as
\code{"within"} or \code{"between"} the focal effect; between-subjects
intercept variances are excluded from the operative denominator.

The operative option concerns only the denominator; it is independent of the
\code{partial_predictors} setting, which controls the numerator. The two
compose: an operative effect size uses the same numerator a general one would
(unique variance by default), paired with the reduced operative denominator.
}

\subsection{Mixed designs}{
Use \code{design = "mixed"} when the model contains both crossed and nested
random effects simultaneously. A canonical example is participants viewing
multiple photos of each model (stimulus): photos are nested within models,
but both levels are crossed with participants.

The corresponding \pkg{lme4} model and \code{eta2p} call would be:
\preformatted{
fit <- lmer(y ~ x + (1 | participant) + (1 | model) + (1 | photo:model),
            data = dat)
eta2p(fit, "x", dat,
      design     = "mixed",
      cross_vars = "participant",
      nest_vars  = c("photo", "model"))
}
Residual variance is attributed to the crossed side and counted exactly
once; the nested calculator's residual is subtracted to prevent
double-counting.
}

\subsection{Crossed designs}{
Supports any number of grouping factors via \code{cross_vars}. The
two-argument form (\code{subj_var} + \code{item_var}) is retained for
backward compatibility and is equivalent to
\code{cross_vars = c(subj_var, item_var)}.
}

\subsection{Confidence intervals}{
With \code{ci = TRUE}, a confidence interval is obtained by parametric
bootstrap via \code{lme4::bootMer}: responses are simulated from the fitted
model, the model is refit, and \code{eta2p} is recomputed on each replicate;
\code{ci_lower} and \code{ci_upper} are the percentile limits. Because
\code{eta2p} is a ratio of REML variance components with no closed-form
sampling distribution, this bootstrap is the appropriate interval rather than
an analytic (e.g. noncentral) formula. Set \code{seed} for reproducibility,
and start with a small \code{n_boot} to gauge runtime on large models.
}
}
\examples{
\donttest{
library(lme4)

#  Two crossed factors (backward-compatible call)
set.seed(42)
crossed_data <- data.frame(
  y         = rnorm(120),
  condition = rep(c(-0.5, 0.5), 60),
  subject   = factor(rep(1:20, each = 6)),
  item      = factor(rep(1:6, 20))
)
model_c <- lmer(y ~ condition + (1 | subject) + (1 | item),
                data = crossed_data)
eta2p(model_c, "condition", crossed_data,
      design   = "crossed",
      subj_var = "subject",
      item_var = "item")

#  Three crossed factors using cross_vars
set.seed(42)
three_way_data <- data.frame(
  y         = rnorm(180),
  condition = rep(c(-0.5, 0.5), 90),
  subject   = factor(rep(1:20, each = 9)),
  item      = factor(rep(rep(1:6, each = 3), 10)),
  rater     = factor(rep(1:3, 60))
)
model_3 <- lmer(y ~ condition +
                  (1 | subject) + (1 | item) + (1 | rater),
                data = three_way_data)
eta2p(model_3, "condition", three_way_data,
      design     = "crossed",
      cross_vars = c("subject", "item", "rater"))

#  Mixed design: photos nested within models, crossed with participants
# Participants each view multiple photos of multiple models.
# Photos are nested within models (each photo belongs to one model),
# but both levels are crossed with participants.
set.seed(42)
n_subj  <- 30; n_model <- 10; n_photo <- 3
mixed_data <- expand.grid(
  participant = factor(seq_len(n_subj)),
  photo_id    = factor(seq_len(n_model * n_photo))
)
mixed_data$model_id <- factor(
  rep(seq_len(n_model), each = n_photo)[as.integer(mixed_data$photo_id)]
)
mixed_data$x <- rnorm(nrow(mixed_data))
mixed_data$y <- rnorm(nrow(mixed_data))

model_m <- lmer(y ~ x +
                  (1 | participant) +
                  (1 | model_id) +
                  (1 | photo_id:model_id),
                data = mixed_data)
eta2p(model_m, "x", mixed_data,
      design     = "mixed",
      cross_vars = "participant",
      nest_vars  = c("photo_id", "model_id"))

#  Supply predictor variance directly (var_x)
eta2p(model_c, "condition", crossed_data,
      design     = "crossed",
      cross_vars = c("subject", "item"),
      var_x      = 1)   # +/-1 binary predictor: var = 1 by design

#  Factor predictor (no manual recoding needed)
crossed_data$grp <- factor(rep(c("A", "B"), 60))
model_f <- lmer(y ~ grp + (1 | subject) + (1 | item), data = crossed_data)
# accepts the variable name "grp"; resolves to the coefficient automatically
eta2p(model_f, "grp", crossed_data,
      design = "crossed", cross_vars = c("subject", "item"))

#  Operative effect size
eta2p(model_c, "condition", crossed_data,
      design = "crossed", cross_vars = c("subject", "item"),
      operative = TRUE)

#  Total-variance (raw) numerator instead of the default unique variance
eta2p(model_c, "condition", crossed_data,
      design = "crossed", cross_vars = c("subject", "item"),
      partial_predictors = FALSE)

#  Confidence interval by parametric bootstrap
eta2p(model_c, "condition", crossed_data,
      design = "crossed", cross_vars = c("subject", "item"),
      ci = TRUE, n_boot = 200, seed = 1)

#  Omnibus effect size for a multi-level factor
crossed_data$emo <- factor(rep(c("a", "b", "c", "d"), 30))
model_e <- lmer(y ~ emo + (1 | subject) + (1 | item), data = crossed_data)
eta2p_omnibus(model_e, "emo", crossed_data,
              design = "crossed", cross_vars = c("subject", "item"))

#  All fixed effects at once (per-coefficient)
batch_eta2p(model_c, crossed_data,
            design = "crossed", cross_vars = c("subject", "item"))
}

}
\references{
Correll, J., Mellinger, C., McClelland, G. H., & Judd, C. M. (2020).
Avoid Cohen's 'Small', 'Medium', and 'Large' for Power Analysis.
\emph{Trends in Cognitive Sciences}, 24(3), 200--207.
\doi{10.1016/j.tics.2019.12.009}

Correll, J., Mellinger, C., & Pedersen, E. J. (2022). Flexible approaches
for estimating partial eta squared in mixed-effects models with crossed
random factors. \emph{Behavior Research Methods}, 54, 1626--1642.
\doi{10.3758/s13428-021-01687-2}

Rights, J. D., & Sterba, S. K. (2019). Quantifying explained variance in
multilevel models: An integrative framework for defining R-squared measures.
\emph{Psychological Methods}, 24(3), 309--338.
\doi{10.1037/met0000184}
}
\seealso{
\code{\link{eta2p_omnibus}} for a single factor-level value for a
multi-df factor or interaction (matching an omnibus \emph{F}/chi-square
test); \code{\link{batch_eta2p}} to compute per-coefficient values for all
fixed effects at once.
}
