EC-IPW method constructor — ec

Creates a method object for IPW estimation with external control borrowing (Zhou et al., 2025). Pass to setup_analysis_primary and run_analysis.

Usage

ec_ipw(ps_formula, weight = NULL, bootstrap = NULL, bootstrap_ci_type = NULL)

Arguments

ps_formula: Formula string for the propensity score model predicting trial participation. The left-hand side is replaced internally (e.g., "S ~ x1 + x2 + x3"). The right-hand side should use only columns in covariates_col_name. . or any other column is an error; an outcome gives a warning, because adjusting for an outcome measured after randomization can bias the treatment effect.
weight: Borrowing weight. NULL (default) for data-adaptive optimal weight, 0 for RCT-only, or a value in (0, 1].
bootstrap: Number of bootstrap replicates (at least 2), or NULL (default) for sandwich variance with normal CIs. Use about 1000 or more for reported intervals; small values are for quick checks only, and their interval can exclude the point estimate.
bootstrap_ci_type: Bootstrap CI type, or NULL (default) which resolves to "perc" when bootstrap is set. One of "perc", "bca", "norm", or "basic". Needs bootstrap. "bca" is slow when bootstrap is smaller than the number of patients: boot::boot.ci() then refits the estimator once for each patient.

Value

An S4 object of class ec_ipw_method.

References

Zhou et al. (2025). Causal estimators for incorporating external controls in randomized trials with longitudinal outcomes. JRSS-A, 188(3), 791-818. doi:10.1093/jrsssa/qnae075

Examples

# optimal weight, sandwich SE
ec_ipw(ps_formula = "S ~ x1 + x2 + x3 + x4 + x5")
#> An object of class "ec_ipw_method"
#> Slot "ps_formula":
#> [1] "S ~ x1 + x2 + x3 + x4 + x5"
#> 
#> Slot "weight":
#> NULL
#> 
#> Slot "method_name":
#> [1] "EC-IPW"
#> 
#> Slot "bootstrap":
#> NULL
#> 
#> Slot "bootstrap_ci_type":
#> NULL
#> 

# no borrowing
ec_ipw(ps_formula = "S ~ x1 + x2 + x3 + x4 + x5", weight = 0)
#> An object of class "ec_ipw_method"
#> Slot "ps_formula":
#> [1] "S ~ x1 + x2 + x3 + x4 + x5"
#> 
#> Slot "weight":
#> [1] 0
#> 
#> Slot "method_name":
#> [1] "EC-IPW"
#> 
#> Slot "bootstrap":
#> NULL
#> 
#> Slot "bootstrap_ci_type":
#> NULL
#> 

# optimal weight with bootstrap
ec_ipw(
  ps_formula = "S ~ x1 + x2 + x3 + x4 + x5",
  bootstrap = 500
)
#> An object of class "ec_ipw_method"
#> Slot "ps_formula":
#> [1] "S ~ x1 + x2 + x3 + x4 + x5"
#> 
#> Slot "weight":
#> NULL
#> 
#> Slot "method_name":
#> [1] "EC-IPW"
#> 
#> Slot "bootstrap":
#> [1] 500
#> 
#> Slot "bootstrap_ci_type":
#> [1] "perc"
#> 

# fixed weight with bootstrap
ec_ipw(
  ps_formula = "S ~ x1 + x2 + x3 + x4 + x5",
  weight = 0.3,
  bootstrap = 500
)
#> An object of class "ec_ipw_method"
#> Slot "ps_formula":
#> [1] "S ~ x1 + x2 + x3 + x4 + x5"
#> 
#> Slot "weight":
#> [1] 0.3
#> 
#> Slot "method_name":
#> [1] "EC-IPW"
#> 
#> Slot "bootstrap":
#> [1] 500
#> 
#> Slot "bootstrap_ci_type":
#> [1] "perc"
#>