% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/es_from_ICC.R
\name{es_from_icc}
\alias{es_from_icc}
\title{Convert an intraclass correlation coefficient (ICC) into an effect size measure}
\usage{
es_from_icc(
  icc,
  n_sample,
  n_measurements,
  icc_type = "agreement",
  icc_to_es = "bonett"
)
}
\arguments{
\item{icc}{intraclass correlation coefficient value}

\item{n_sample}{total sample size (number of subjects)}

\item{n_measurements}{number of measurements or raters}

\item{icc_type}{ICC type: \code{"agreement"} for ICC(2,1) (two-way random, absolute agreement)
or \code{"consistency"} for ICC(3,1) (two-way mixed, consistency). Default is \code{"agreement"}.}

\item{icc_to_es}{method used to compute the effect size from ICC.
Must be either \code{"bonett"} or \code{"raw"}.}
}
\value{
This function estimates the standard error of the ICC.

\tabular{ll}{
\code{natural effect size measure} \tab icc\cr
\tab \cr
\code{converted effect size measure} \tab N/A\cr
\tab \cr
\code{required input data} \tab icc + n_sample + n_measurements\cr
\tab \cr
}
}
\description{
Convert an intraclass correlation coefficient (ICC) into an effect size measure
}
\details{
This function computes an effect size from an ICC.
\enumerate{
\item When \code{icc_to_es = "bonett"} (default), the Bonett (2002) transformation
is applied:
\deqn{T(ICC) = \ln(1 - ICC)}
with the one-way random-model / two-way-consistency leading-order sampling
variance (Bonett, 2002; Donner & Eliasziw, 1987):
\deqn{T\_se = \sqrt{\frac{2 (1 + (k-1) ICC)^2}{k (k - 1)(n - 1)}}}
\item When \code{icc_to_es = "raw"}, the raw ICC is used and its standard error
is obtained by the delta method (\eqn{(1 - ICC)} times the transformed-scale SE).
}

\strong{Scope of the SE formula.} For the two-way consistency ICC(3,1)
(\code{icc_type = "consistency"}) this SE is exact at leading order: deriving
it from \eqn{F_0 = MSR/MSE} (with degrees of freedom \eqn{n-1} and
\eqn{(n-1)(k-1)}) reduces to the same expression, and it still depends on the
ICC value (it is \emph{not} \eqn{\rho}-free). For the two-way
absolute-agreement ICC(2,1) (\code{icc_type = "agreement"}, the default) the
same formula is only a \strong{one-way approximation that assumes negligible
between-rater variance}: when raters differ systematically
(\eqn{\sigma^2_{rater} > 0}), the ICC(2,1) estimator depends on the
between-rater mean square, which has only \eqn{k - 1} degrees of freedom, so
its true sampling variance does not shrink at the \eqn{1/n} rate this formula
assumes and the reported SE/CI can be markedly anti-conservative (simulation:
95\\% CI coverage around 0.74-0.76 with moderate rater variance, degrading as
\eqn{n} grows). The exact ICC(2,1) variance requires the rater-variance
component, which summary data do not report; a per-row informational flag
(V31) marks agreement-type rows for this reason. If the raters are known to
be exchangeable (negligible rater variance), the approximation is accurate.

\strong{Scale note.} Under the default \code{icc_to_es = "bonett"} the returned
\code{icc_se} column is on the \eqn{\ln(1 - ICC)} scale. If you feed it to
\code{\link{compute_sem}} (whose \code{icc_se} argument expects the RAW-scale
SE), convert it first: \code{raw_se = icc_se * (1 - icc)} - or call
\code{es_from_icc} with \code{icc_to_es = "raw"}.
}
\examples{
es_from_icc(
  icc = 0.80, n_sample = 50, n_measurements = 2, icc_type = "agreement"
)
}
\references{
Bonett, D. G. (2002). Sample size requirements for estimating intraclass correlations
with desired precision. Statistics in Medicine, 21(9), 1331-1335.

Shrout, P. E., & Fleiss, J. L. (1979). Intraclass correlations: uses in assessing rater
reliability. Psychological Bulletin, 86(2), 420-428.
}
