% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/es_from_ETASQ.R
\name{es_from_etasq_adj}
\alias{es_from_etasq_adj}
\title{Convert an adjusted eta-squared value (i.e., from an ANCOVA) to various effect size measures}
\usage{
es_from_etasq_adj(
  etasq_adj,
  n_exp,
  n_nexp,
  n_cov_ancova,
  cov_outcome_r,
  smd_to_cor = "viechtbauer",
  smd_var = "borenstein",
  reverse_etasq
)
}
\arguments{
\item{etasq_adj}{an adjusted eta-squared value obtained from an ANCOVA model. This
must be the \strong{partial} eta-squared of the group effect,
\eqn{\eta_p^2 = SS_{group} / (SS_{group} + SS_{error})} — the quantity that
most software (SPSS, \code{car}, \code{effectsize}) prints for an ANCOVA term.
Do \strong{not} supply the classical eta-squared \eqn{SS_{group} / SS_{total}}: in an
ANCOVA the total sum of squares also contains the covariate variance, so the
classical value is smaller than the partial one and would be inverted into too
small an F, biasing the effect size toward zero. (In a covariate-free one-way
ANOVA the two definitions coincide; see \code{\link{es_from_etasq}()}.)}

\item{n_exp}{number of participants in the experimental/exposed group.}

\item{n_nexp}{number of participants in the non-experimental/non-exposed group.}

\item{n_cov_ancova}{number of covariates in the ANCOVA model.}

\item{cov_outcome_r}{correlation between the outcome and covariate (multiple correlation when multiple covariates are included in the ANCOVA model).}

\item{smd_to_cor}{formula used to convert the \code{cohen_d} value into a coefficient correlation (see details).}

\item{smd_var}{name of the sampling-variance formula for the standardized mean difference: "borenstein" (default) or "hedges_olkin" (alias "viechtbauer"). The two differ by a squared small-sample-correction factor (J^2); "hedges_olkin" is a few percent larger at small samples.}

\item{reverse_etasq}{a logical value indicating whether the direction of generated effect sizes should be flipped.}
}
\value{
This function estimates and converts between several effect size measures.

\tabular{ll}{
\code{natural effect size measure} \tab D + G\cr
\tab \cr
\code{converted effect size measure} \tab OR + R + Z \cr
\tab \cr
\code{required input data} \tab See 'Section 18. Adjusted: ANCOVA statistics, eta-squared'\cr
\tab https://metaconvert.org/input.html\cr
\tab \cr
}
}
\description{
Convert an adjusted eta-squared value (i.e., from an ANCOVA) to various effect size measures
}
\details{
This function converts the adjusted (partial) eta-squared of a binary predictor
(ANCOVA model) into the ANCOVA F-statistic it implies, and then relies on the
calculations of the \code{\link{es_from_ancova_f}()} function. The returned
Cohen's d (D) and Hedges' g (G) are therefore expressed on the
\strong{marginal (unadjusted) SD scale} — consistent with the other
\code{es_from_ancova_*} functions — not on the residual (covariate-adjusted)
SD scale on which a partial eta-squared is natively defined.
Odds ratio (OR) and correlation coefficients (R/Z) are then converted from the Cohen's d.

\strong{To convert the adjusted eta-squared into an ANCOVA F-statistic},
the partial-eta-squared identity \eqn{\eta_p^2 = F / (F + df)} is inverted
(this is why a \emph{partial} eta-squared, not a classical one, is required):
\deqn{df = n\_exp + n\_nexp - 2 - n\_cov\_ancova}
\deqn{ancova\_f = \frac{etasq\_adj * df}{1 - etasq\_adj}}

\strong{To estimate a Cohen's d} the formula used is (table 12.3 in Cooper):
\deqn{cohen\_d = \sqrt{ancova\_f * \frac{(n\_exp+n\_nexp)}{n\_exp*n\_nexp}} * \sqrt{1 - cov\_out\_cor^2}}

Note that the back-transformation to the marginal SD scale requires
\code{cov_outcome_r}; when it is missing, the effect size estimates are
returned as NA (the marginal scale is not identified from the adjusted
eta-squared alone).

\strong{To estimate other effect size measures},
calculations of the \code{\link{es_from_cohen_d_adj}()} are applied.
}
\note{
Two cautions apply. (1) \code{etasq_adj} must be the \emph{partial} eta-squared (see
the parameter description); a classical eta-squared biases the effect size
toward zero. (2) The sampling variance is rebuilt from Cooper's eq. 12.26, which
assumes a covariate balanced across groups and treats \code{cov_outcome_r} as
known; in covariate-imbalanced designs the standard error is a lower bound
(anti-conservative), while the point estimate remains unbiased. See Lai and
Kelley (2012).
}
\examples{
es_from_etasq_adj(etasq_adj = 0.28, n_cov_ancova = 3, cov_outcome_r = 0.2, n_exp = 20, n_nexp = 22)
}
\references{
Cooper, H., Hedges, L. V., & Valentine, J. C. (Eds.). (2019). The handbook of research synthesis and meta-analysis. Russell Sage Foundation.

Lai, K., & Kelley, K. (2012). Accuracy in parameter estimation for ANCOVA and ANOVA contrasts: Sample size planning via narrow confidence intervals. British Journal of Mathematical and Statistical Psychology, 65(2), 350-370.
}
