% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/power_cox.R
\name{power_cox}
\alias{power_cox}
\title{Sample size and power for PS-weighted marginal Cox model}
\usage{
power_cox(
  effect_size,
  r,
  d1,
  d0 = NULL,
  phi = NULL,
  study_type = "obs",
  estimand = "ATE",
  method = "robust",
  sig_level = 0.05,
  power = NULL,
  sample_size = NULL,
  test = "one-sided",
  n_mc = 1e+06
)
}
\arguments{
\item{effect_size}{Log hazard ratio \eqn{\tau_0 = \log(\text{HR})}.
Negative values indicate benefit (lower hazard in group 1).
Scalar or vector.}

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

\item{d1}{Event rate in group 1 (treated), in \eqn{(0, 1]}.
Scalar or vector.}

\item{d0}{Event rate in group 0 (control), in \eqn{(0, 1]}.
If \code{NULL} (default), set equal to \code{d1}.  Scalar or vector.}

\item{phi}{Overlap coefficient \eqn{\phi \in (0, 1)}.  Required when
\code{study_type = "obs"}; ignored for \code{"rct"}.  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{study_type}{\code{"obs"} (observational study, default) or
\code{"rct"} (randomized trial).}

\item{estimand}{Target estimand.  \code{"ATE"} (average treatment effect,
uses inverse probability weights), \code{"ATO"} (overlap population,
uses overlap weights), or \code{"ATT"} (group 1 population, uses
weights for the treated). Ignored when \code{study_type = "rct"}.
Scalar or character vector.}

\item{method}{Variance approximation method.  \code{"robust"} (default)
for the robust sandwich variance; \code{"schoenfeld"} for the classical
Schoenfeld formula. \code{"schoenfeld"} is only available when
\code{study_type = "rct"}. 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{"one-sided"} (default) or \code{"two-sided"}.}

\item{n_mc}{Number of Monte Carlo samples used to estimate the design
effect for \code{estimand} in \code{"ATO"}, \code{"ATT"}.
Default \code{1e6}.}
}
\value{
An object of class \code{"power_cox"}, 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 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{d0_set_equal}}{Logical; \code{TRUE} when \code{d0} was
not specified and set equal to \code{d1}.}
}
}
\description{
The required sample size is
\deqn{N = V\,(z_{1-\alpha} + z_{\beta})^2 \,/\, \tau_0^2,}
where \eqn{\tau_0 = \log(\text{HR})} is the target log hazard ratio and
\eqn{V} is the asymptotic variance of the estimator.

\strong{Randomized trial — robust sandwich variance} (\code{method = "robust"}):
\deqn{V_{RCT} = \frac{(\lambda_1 + \lambda_0)^2
  \bigl[r\lambda_0^2 d_1 + (1-r)\lambda_1^2 d_0\bigr]}{d^2},}
where \eqn{\lambda_1 = \sqrt{r/(1-r)}\,e^{\tau_0/2}},
\eqn{\lambda_0 = 1/\lambda_1}, and \eqn{d = r\,d_1 + (1-r)\,d_0}.

\strong{Randomized trial — Schoenfeld formula} (\code{method = "schoenfeld"}):
\deqn{V_{Sch} = \frac{1}{r(1-r)\,d}.}
Note: the Schoenfeld formula is derived under a null effect and may
underestimate or overestimate the required sample size at non-null effects.

\strong{Observational study — inverse probability weights (ATE),
robust sandwich variance} (\code{study_type = "obs"}, \code{estimand = "ATE"}):
\deqn{V_{obs} = \frac{(\lambda_1+\lambda_0)^2}{d^2}
  \left[r^2\lambda_0^2 d_1\,\frac{a+b-1}{a-1}
       + (1-r)^2\lambda_1^2 d_0\,\frac{a+b-1}{b-1}\right],}
where \eqn{a, b > 1} are Beta distribution parameters determined by
\eqn{(r, \phi)}.  Requires \eqn{\min(a, b) > 1}.

\strong{Observational study — overlap weights (ATO) or
treated population weights (ATT)}
(\code{study_type = "obs"}, \code{estimand} in \code{"ATO"}, \code{"ATT"}):
\deqn{N = \kappa_{DE} \times N_{RCT},}
where \eqn{N_{RCT}} uses \eqn{V_{RCT}} above and \eqn{\kappa_{DE}} is a
design effect estimated by Monte Carlo simulation from the Beta
approximation of propensity scores.
}
\details{
Computes the required sample size or the achieved power for the
propensity-score-weighted partial likelihood estimator of the marginal
hazard ratio in a Cox proportional hazards model.
}
\examples{
# RCT sample size, robust variance
power_cox(effect_size = log(0.6), r = 0.5, d1 = 0.8, study_type = "rct",
          power = 0.8)

# Observational study, ATE
power_cox(effect_size = log(0.6), r = 0.5, d1 = 0.8, phi = 0.9,
          study_type = "obs", estimand = "ATE", power = 0.8)

# Sensitivity over phi and estimand
power_cox(effect_size = log(0.6), r = 0.5, d1 = 0.8,
          phi = c(0.9, 0.95), estimand = c("ATE", "ATO"),
          power = 0.8)

}
\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).
}
\seealso{
\code{\link{power_ps}}, \code{\link{overlap_coef}}
}
