% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/power_ps.R
\name{power_ps}
\alias{power_ps}
\title{Sample size and power for PS-weighted average treatment effect estimators}
\usage{
power_ps(
  effect_size,
  r,
  phi,
  rho2 = 0,
  estimand = "ATE",
  sig_level = 0.05,
  power = NULL,
  sample_size = NULL,
  test = "two-sided"
)
}
\arguments{
\item{effect_size}{Standardized effect size \eqn{\tilde{\tau} = \tau / S},
where \eqn{\tau} is the treatment effect and
\eqn{S = \sqrt{\mathrm{Var}(Y(0))}}. Scalar or vector.}

\item{r}{Treatment proportion \eqn{r = \Pr(Z = 1)}, in \eqn{(0, 1)}.
Scalar or vector.}

\item{phi}{Overlap coefficient \eqn{\phi \in (0, 1)}, measuring covariate
similarity between groups.  Rule of thumb: \eqn{< 0.80} very poor,
\eqn{[0.80, 0.90)} poor, \eqn{[0.90, 0.95)} moderate,
\eqn{\ge 0.95} good.  Scalar or vector.}

\item{rho2}{Confounding coefficient \eqn{\rho^2 \in [0, 1)}, the squared
correlation between the potential outcome and the propensity score linear
predictor. Bounded above by the \eqn{R^2} of regressing the outcome on
covariates. Sensitivity analysis over \eqn{\rho^2 \in [0, 0.05)} is
recommended. Default \code{0}. Scalar or vector.}

\item{estimand}{Target estimand.  One of \code{"ATE"} (average treatment
effect), \code{"ATT"} (average treatment effect for group 1),
\code{"ATC"} (average treatment effect for group 0), \code{"ATO"}
(average treatment effect for the overlap population), or a custom
tilting function \code{h(e)} (must be a scalar function, not vectorized
with other parameters). Scalar or character vector.}

\item{sig_level}{Significance level \eqn{\alpha}. Default \code{0.05}.}

\item{power}{Target power \eqn{\beta}. Provide for sample size calculation;
mutually exclusive with \code{sample_size}.}

\item{sample_size}{Total sample size \eqn{N}. Provide for power
calculation; mutually exclusive with \code{power}.}

\item{test}{\code{"two-sided"} (default) or \code{"one-sided"}.}
}
\value{
An object of class \code{"power_ps"}, a list containing:
\describe{
\item{\code{call}}{The matched call.}
\item{\code{calculation}}{\code{"sample_size"} or \code{"power"}.}
\item{\code{result}}{A data frame with one row per scenario (all
combinations of vector inputs) and columns for every design parameter
plus the computed \code{sample_size} or \code{power}.}
\item{\code{settings}}{A list with \code{sig_level}, \code{power},
\code{sample_size}, and \code{test}.}
\item{\code{n_scenarios}}{Number of rows in \code{result}.}
\item{\code{rho2_is_default}}{Logical; \code{TRUE} when \code{rho2}
was left at its default value of \code{0}.}
}
}
\description{
The required sample size is
\deqn{N = \bar{V}\,(z_{1-\alpha/2} + z_{\beta})^2 \,/\, \tilde{\tau}^2,}
where \eqn{\tilde{\tau}} is the standardized effect size and
\eqn{\bar{V}} is the asymptotic variance of the Hajek estimator.

For the \strong{ATE} estimand, \eqn{\bar{V}} has the closed form
\deqn{\bar{V} = 2\!\left\{1 + \bigl(\rho^2\sigma_e^2+1\bigr)
  \exp\!\bigl(\sigma_e^2/2\bigr)\cosh(\mu_e)\right\},}
where \eqn{(\mu_e,\,\sigma_e^2)} are uniquely determined by \eqn{(r,\phi)}.

For the \strong{ATT}, \strong{ATC}, and \strong{ATO} estimands, \eqn{\bar{V}} is computed
by numerical integration of the same variance expression with the
corresponding tilting function \eqn{h(e)}.  A custom tilting function may
also be supplied.

For binary outcomes, the estimand is the risk difference; the same formula
applies with \eqn{S^2 = \mathrm{Var}(Y(0))} estimated from a linear
probability model.
}
\details{
Computes the required sample size or the achieved power for the
propensity-score-weighted Hajek estimator of a weighted average treatment
effect (WATE) with continuous or binary outcomes.
}
\examples{
# Sample size for ATE, scalar inputs
power_ps(effect_size = 0.2, r = 0.5, phi = 0.9, power = 0.8)

# Power at a fixed N
power_ps(effect_size = 0.2, r = 0.5, phi = 0.9, sample_size = 250)

# Sensitivity over r and estimand (vector inputs)
power_ps(effect_size = 0.2, r = c(0.3, 0.5, 0.7), phi = 0.9,
         estimand = c("ATE", "ATO"), power = 0.8)

}
\references{
Bo Liu, Chengxin Yang, and Fan Li. Sample size and power calculations for
causal inference in observational studies.
\emph{Annals of Statistics} (2026), forthcoming.
}
\seealso{
\code{\link{power_cox}}, \code{\link{overlap_coef}}
}
