% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/overlap_coef.R
\name{overlap_coef}
\alias{overlap_coef}
\title{Bhattacharyya overlap coefficient for propensity score distributions}
\usage{
overlap_coef(ps = NULL, Z = NULL, a = NULL, b = NULL)
}
\arguments{
\item{ps}{Numeric vector of estimated propensity scores
\eqn{e_i = \Pr(Z_i = 1 \mid X_i)}, all in \eqn{(0, 1)}.
Required when \code{a} and \code{b} are not supplied.}

\item{Z}{Integer or numeric vector of treatment indicators
(\eqn{Z_i \in \{0, 1\}}), the same length as \code{ps}.
Required when \code{ps} is supplied.}

\item{a}{Shape parameter \eqn{a > 0} of the Beta distribution.
Supply together with \code{b} to use the analytical formula.}

\item{b}{Shape parameter \eqn{b > 0} of the Beta distribution.
Supply together with \code{a} to use the analytical formula.}
}
\value{
A list with components:
\describe{
\item{\code{phi}}{The overlap coefficient \eqn{\hat\phi}.}
\item{\code{r}}{Treatment proportion: \code{mean(Z)} (empirical) or
\code{a / (a + b)} (analytical).}
}
}
\description{
Two calling conventions are provided:

\describe{
\item{From propensity scores (empirical):}{
Supply \code{ps} and \code{Z}.  The empirical formula is
\deqn{\hat\phi = \frac{\mathrm{E}[\sqrt{e(1-e)}]}{\sqrt{r(1-r)}},}
where \eqn{r = \mathrm{E}[Z]}.  This is the sample mean of
\eqn{\sqrt{e_i(1-e_i)}} divided by \eqn{\sqrt{\hat r(1-\hat r)}}.
}
\item{From Beta parameters (analytical):}{
Supply \code{a} and \code{b}.  Under the
\eqn{\mathrm{Beta}(a,b)} approximation,
\deqn{\phi = \exp\!\Bigl[
      \log\Gamma(a+\tfrac12) - \tfrac12\log a - \log\Gamma(a)
      + \log\Gamma(b+\tfrac12) - \tfrac12\log b - \log\Gamma(b)
    \Bigr].}
}
}
}
\details{
Computes the Bhattacharyya overlap coefficient \eqn{\phi}, a scalar
measure of propensity score overlap between the treatment and control
groups.  Values close to 1 indicate near-complete overlap (little
confounding); values well below 1 indicate poor overlap.
}
\examples{
# From propensity scores
set.seed(1)
n  <- 500
X  <- rnorm(n)
ps <- plogis(0.5 * X)
Z  <- rbinom(n, 1, ps)
overlap_coef(ps = ps, Z = Z)

# From Beta parameters
overlap_coef(a = 2, b = 3)

}
\references{
Chengxin Yang, Bo Liu, and Fan Li. Sample size and power calculations for
causal inference with time-to-event outcomes.
\emph{arXiv preprint arXiv:2605.10088} (2026).

Bo Liu, Chengxin Yang, and Fan Li. Sample size and power calculations for
causal inference with continuous and binary outcomes.
\emph{Annals of Statistics} (2026).
}
\seealso{
\code{\link{power_ps}}, \code{\link{power_cox}}
}
