power_cox: Sample size and power for PS-weighted marginal Cox model

In PSpower: Sample Size and Power for Propensity Score Weighted Estimators

Sample size and power for PS-weighted marginal Cox model

Description

The required sample size is

N = V\,(z_{1-\alpha} + z_{\beta})^2 \,/\, \tau_0^2,

where \tau_0 = \log(\text{HR}) is the target log hazard ratio and V is the asymptotic variance of the estimator.

Randomized trial — robust sandwich variance (method = "robust"):

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 \lambda_1 = \sqrt{r/(1-r)}\,e^{\tau_0/2}, \lambda_0 = 1/\lambda_1, and d = r\,d_1 + (1-r)\,d_0.

Randomized trial — Schoenfeld formula (method = "schoenfeld"):

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.

Observational study — inverse probability weights (ATE), robust sandwich variance (study_type = "obs", estimand = "ATE"):

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 a, b > 1 are Beta distribution parameters determined by (r, \phi). Requires \min(a, b) > 1.

Observational study — overlap weights (ATO) or treated population weights (ATT) (study_type = "obs", estimand in "ATO", "ATT"):

N = \kappa_{DE} \times N_{RCT},

where N_{RCT} uses V_{RCT} above and \kappa_{DE} is a design effect estimated by Monte Carlo simulation from the Beta approximation of propensity scores.

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

effect_size	Log hazard ratio \tau_0 = \log(\text{HR}). Negative values indicate benefit (lower hazard in group 1). Scalar or vector.
r	Treatment proportion r = \Pr(Z = 1), in (0, 1). Scalar or vector.
d1	Event rate in group 1 (treated), in (0, 1]. Scalar or vector.
d0	Event rate in group 0 (control), in (0, 1]. If NULL (default), set equal to d1. Scalar or vector.
phi	Overlap coefficient \phi \in (0, 1). Required when study_type = "obs"; ignored for "rct". Rule of thumb: < 0.80 very poor, [0.80, 0.90) poor, [0.90, 0.95) moderate, \ge 0.95 good. Scalar or vector.
study_type	"obs" (observational study, default) or "rct" (randomized trial).
estimand	Target estimand. "ATE" (average treatment effect, uses inverse probability weights), "ATO" (overlap population, uses overlap weights), or "ATT" (group 1 population, uses weights for the treated). Ignored when study_type = "rct". Scalar or character vector.
method	Variance approximation method. "robust" (default) for the robust sandwich variance; "schoenfeld" for the classical Schoenfeld formula. "schoenfeld" is only available when study_type = "rct". Scalar or character vector.
sig_level	Significance level \alpha. Default 0.05.
power	Target power \beta. Provide for sample size calculation; mutually exclusive with sample_size.
sample_size	Total sample size N. Provide for power calculation; mutually exclusive with power.
test	"one-sided" (default) or "two-sided".
n_mc	Number of Monte Carlo samples used to estimate the design effect for estimand in "ATO", "ATT". Default 1e6.

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.

Value

An object of class "power_cox", a list containing:

call

The matched call.

calculation

"sample_size" or "power".

result

A data frame with one row per scenario and columns for every design parameter plus the computed sample_size or power.

settings

A list with sig_level, power, sample_size, and test.

n_scenarios

Number of rows in result.

d0_set_equal

Logical; TRUE when d0 was not specified and set equal to d1.

References

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

See Also

power_ps, overlap_coef

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)

PSpower documentation built on May 14, 2026, 9:07 a.m.