% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/es_disattenuate.R
\name{es_disattenuate}
\alias{es_disattenuate}
\title{Disattenuate (correct for unreliability) a correlation coefficient}
\usage{
es_disattenuate(r, r_se, reliability_x, reliability_y, n_sample)
}
\arguments{
\item{r}{observed correlation coefficient (values outside \eqn{[-1, 1]}
trigger a warning; the arithmetic is still applied so the inputs can be
inspected)}

\item{r_se}{standard error of the observed correlation. Optional: when omitted,
it is derived from \code{n_sample} (see Details).}

\item{reliability_x}{reliability of measure X (e.g., target PROM)}

\item{reliability_y}{reliability of measure Y (e.g., comparator instrument)}

\item{n_sample}{sample size. Used only to derive \code{r_se} when \code{r_se}
is not supplied; otherwise unused.}
}
\value{
A data.frame with the corrected correlation and its Fisher's z
transformation (with their standard errors and 95\% CIs), and the
attenuation factor.
}
\description{
Disattenuate (correct for unreliability) a correlation coefficient
}
\details{
Corrects an observed correlation for attenuation due to measurement error
in both measures, using the classical disattenuation formula
(Hunter & Schmidt, 2004; Spearman, 1904):

\deqn{r_c = \frac{r_{obs}}{\sqrt{rel_x \times rel_y}}}

where \eqn{rel_x} and \eqn{rel_y} are reliability coefficients for the
two measures (e.g., Cronbach's alpha, test-retest ICC).

The standard error of the corrected correlation is approximated as:
\deqn{r_c\_se = \frac{r\_se}{\sqrt{rel_x \times rel_y}}}

This approximation treats the reliabilities as known constants, so the SE
and CI are a lower bound when the reliabilities are themselves estimated
(Hunter & Schmidt, 2004, Ch. 3).

When \code{r_se} is not supplied, it is first obtained from the sample size as
the large-sample Pearson correlation SE \eqn{\sqrt{(1 - r^2)^2 / (n - 1)}}
(Cooper et al., 2019).

The function also provides Fisher's z transformation of the corrected
correlation for use in meta-analysis, with
\eqn{SE(z_c) = SE(r_c) / (1 - r_c^2)} (delta method). The corrected-r
confidence interval is obtained by back-transforming the Fisher-z interval
(\eqn{\tanh}), so it always lies within (-1, 1).

When the corrected correlation is extreme (\eqn{|r_c| > 0.999}, including
the mathematically impossible \eqn{|r_c| \ge 1} that inconsistent inputs
produce), no meaningful Fisher's z or CI exists: the corrected-r CI and all
Fisher's z outputs (\code{z_corrected}, \code{z_corrected_se} and its CI
bounds) are set to \code{NA} and a warning is emitted. The corrected point
estimate and its first-order standard error are always returned as
computed, so the offending inputs can be inspected.

This function is typically applied to the results of
\code{summary(convert_df(..., measure = "r"))}:

\preformatted{
res <- summary(convert_df(my_data, measure = "r"))
corrected <- es_disattenuate(
  r = res$es, r_se = res$se,
  reliability_x = my_data$rel_target,
  reliability_y = my_data$rel_comparator,
  n_sample = my_data$n_sample
)
}
}
\examples{
es_disattenuate(r = 0.50, r_se = 0.05,
                reliability_x = 0.85, reliability_y = 0.80,
                n_sample = 100)

# Only correct for one measure's unreliability (set other to 1)
es_disattenuate(r = 0.50, r_se = 0.05,
                reliability_x = 0.85, reliability_y = 1.0,
                n_sample = 100)
}
\references{
Hunter, J. E., & Schmidt, F. L. (2004). Methods of Meta-Analysis: Correcting
Error and Bias in Research Findings (2nd ed.). Sage Publications.

Spearman, C. (1904). The proof and measurement of association between two things.
The American Journal of Psychology, 15(1), 72-101.

Cooper, H., Hedges, L.V., & Valentine, J.C. (Eds.). (2019). The handbook of
research synthesis and meta-analysis. Russell Sage Foundation.
}
