markdowns

Author: Matt Secrest

_pkgdown.yml

@@ -18,6 +18,9 @@ navbar:
       aria-label: GitHub
 
 articles:
+  - title: Getting Started
+    contents:
+      - introduction
   - title: Primary Analysis
     contents:
       - primary_analysis_workflow

vignettes/introduction.Rmd

@@ -0,0 +1,101 @@
+---
+title: "Introduction to rdborrow"
+author: "Matt Secrest"
+date: "`r Sys.Date()`"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Introduction to rdborrow}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r setup, include=FALSE}
+library(rdborrow)
+```
+
+## Overview
+
+**rdborrow** implements causal inference methods for incorporating external
+controls in randomized controlled trials (RCTs) with longitudinal outcomes.
+The package provides tools for both analysis and simulation, enabling
+researchers to evaluate different borrowing strategies and design trials
+that leverage external data.
+
+The methods are motivated by the SUNFISH trial for spinal muscular atrophy
+(SMA), where external controls from the olesoxime trial augment the
+randomized data to improve statistical efficiency.
+
+## Methods
+
+### Primary analysis (placebo-controlled phase)
+
+These methods estimate the average treatment effect (ATE) during the
+placebo-controlled phase by borrowing from external controls.
+
+| Method | Function | Description |
+|--------|----------|-------------|
+| EC-IPW | `ec_ipw()` | Inverse probability weighting with external control borrowing |
+| EC-AIPW | `ec_aipw()` | Augmented IPW (doubly robust) |
+
+Both methods support:
+
+- **No borrowing** (`weight = 0`): uses only RCT data
+- **Optimal weight** (`weight = NULL`): data-adaptive weight minimizing variance
+- **Fixed weight** (`weight = 0.3`): user-specified borrowing amount
+- **Sandwich variance** or **bootstrap inference**
+
+See `vignette("primary_analysis_workflow")` for usage.
+
+### OLE phase analysis (open-label extension)
+
+After the placebo-controlled phase, control subjects cross over to
+treatment. These methods estimate the long-term treatment effect using
+external controls who remain untreated.
+
+| Method | Function | Description |
+|--------|----------|-------------|
+| DID-EC-IPW | `did_ec_ipw()` | Difference-in-differences with IPW |
+| DID-EC-AIPW | `did_ec_aipw()` | DID with augmented IPW |
+| DID-EC-OR | `did_ec_or()` | DID with outcome regression |
+| SCM | `scm()` | Synthetic control method |
+
+All OLE methods use bootstrap for inference.
+
+See `vignette("OLE_analysis_workflow")` for usage.
+
+### Simulation
+
+The simulation module evaluates estimator performance via Monte Carlo:
+
+- `simulate_trial()` generates synthetic trial + external control data
+- `setup_simulation_primary()` / `setup_simulation_OLE()` configure simulations
+- `run_simulation()` runs Monte Carlo experiments and reports bias, variance, MSE, coverage, power
+
+See `vignette("primary_simulation_workflow")` and
+`vignette("OLE_simulation_workflow")` for usage.
+
+## Quick start
+
+```{r}
+# create an EC-IPW method with optimal borrowing weight
+method <- ec_ipw(ps_formula = "S ~ x1 + x2 + x3 + x4 + x5")
+
+# set up the analysis
+analysis <- setup_analysis_primary(
+  data = SyntheticData,
+  trial_status_col_name = "S",
+  treatment_col_name = "A",
+  outcome_col_name = c("y1", "y2"),
+  covariates_col_name = c("x1", "x2", "x3", "x4", "x5"),
+  method_weighting_obj = method
+)
+
+# run
+run_analysis(analysis)
+```
+
+## References
+
+- Zhou X, Zhu J, Drake C, Pang H (2024). "Causal estimators for incorporating external controls in randomized trials with longitudinal outcomes." *Journal of the Royal Statistical Society Series A: Statistics in Society*. doi: [10.1093/jrsssa/qnae075](https://doi.org/10.1093/jrsssa/qnae075).
+- Zhou X, Pang H, Drake C, Burger HU, Zhu J (2024). "Estimating treatment effect in randomized trial after control to treatment crossover using external controls." *Journal of Biopharmaceutical Statistics*. doi: [10.1080/10543406.2024.2444222](https://doi.org/10.1080/10543406.2024.2444222).
+- Shi L, Pang H, Chen C, Zhu J (2025). "rdborrow: an R package for causal inference incorporating external controls in randomized controlled trials with longitudinal outcomes." *Journal of Biopharmaceutical Statistics*, 35(6), 1043-1066. doi: [10.1080/10543406.2025.2489283](https://doi.org/10.1080/10543406.2025.2489283).

vignettes/primary_analysis_workflow.Rmd

@@ -13,8 +13,6 @@ vignette: >
 library(rdborrow)
 ```
 
-
-
 ## Primary analysis
 
 This vignette demonstrates the primary analysis workflow using the
@@ -23,27 +21,21 @@ EC-IPW and EC-AIPW weighting estimators proposed in
 for incorporating external controls in randomized trials with
 longitudinal outcomes.
 
-### 1 load and visualize data
+### 1 Load data
 ```{r}
-# load the simulated dataset
 head(SyntheticData)
 ```
 
+### 2 EC-IPW
 
-### 2 Estimation and inference:
-
-#### 2.1 Inverse probability weighting (IPW)
-1) IPW with zero weight (wt = 0):
-
+#### 2.1 No borrowing (weight = 0)
 ```{r}
-# test: within trial
-## Data argument + column names (coxph, glm)
 method <- ec_ipw(
   ps_formula = "S ~ x1 + x2 + x3 + x4 + x5",
   weight = 0
 )
 
-analysis_primary_obj <- setup_analysis_primary(
+analysis <- setup_analysis_primary(
   data = SyntheticData,
   trial_status_col_name = "S",
   treatment_col_name = "A",
@@ -52,16 +44,14 @@ analysis_primary_obj <- setup_analysis_primary(
   method_weighting_obj = method
 )
 
-res <- run_analysis(analysis_primary_obj)
-res
+run_analysis(analysis)
 ```
 
-2) IPW with data-adaptive weight:
+#### 2.2 Optimal weight (data-adaptive)
 ```{r}
-# test: within trial
 method <- ec_ipw(ps_formula = "S ~ x1 + x2 + x3 + x4 + x5")
 
-analysis_primary_obj <- setup_analysis_primary(
+analysis <- setup_analysis_primary(
   data = SyntheticData,
   trial_status_col_name = "S",
   treatment_col_name = "A",
@@ -70,87 +60,69 @@ analysis_primary_obj <- setup_analysis_primary(
   method_weighting_obj = method
 )
 
-res <- run_analysis(analysis_primary_obj)
-
-res$borrow_weight
-res$results
+run_analysis(analysis)
 ```
 
-#### 2.2 Augmented inverse probability weighting (AIPW)
-
-The second approach is AIPW, which also accommodates two external borrowing strategies.
-
-1) AIPW with zero weight (wt = 0):
+#### 2.3 Bootstrap inference
 ```{r}
-# test: AIPW with 0 weight, should be same as IPW with 0 weight
-method_weighting_obj <- setup_method_weighting(
-  method_name = "AIPW",
-  optimal_weight_flag = FALSE,
-  wt = 0,
-  model_form_piS = "S ~ x1 + x2 + x3 + x4 + x5",
-  model_form_mu0_ext = c(
-    "y1 ~ x1 + x2 + x3 + x4 + x5",
-    "y2 ~ x1 + x2 + x3 + x4 + x5"
-  )
+method <- ec_ipw(
+  ps_formula = "S ~ x1 + x2 + x3 + x4 + x5",
+  bootstrap = 50,
+  bootstrap_ci_type = "perc"
 )
 
-analysis_primary_obj <- setup_analysis_primary(
+analysis <- setup_analysis_primary(
   data = SyntheticData,
   trial_status_col_name = "S",
   treatment_col_name = "A",
   outcome_col_name = c("y1", "y2"),
   covariates_col_name = c("x1", "x2", "x3", "x4", "x5"),
-  method_weighting_obj = method_weighting_obj
+  method_weighting_obj = method
 )
 
-res <- run_analysis(analysis_primary_obj)
+run_analysis(analysis)
 ```
 
+### 3 EC-AIPW
 
+EC-AIPW augments the IPW estimator with an outcome regression model,
+making it doubly robust: consistent if either the propensity score model
+or the outcome model is correctly specified.
 
-2) AIPW with data adaptive weight:
+#### 3.1 No borrowing (weight = 0)
 ```{r}
-# test: AIPW with given weight
-# bootstrap as part of the method and analysis
-method_weighting_obj <- setup_method_weighting(
-  method_name = "AIPW",
-  optimal_weight_flag = TRUE,
-  model_form_piS = "S ~ x1 + x2 + x3 + x4 + x5",
-  model_form_mu0_ext = c(
+method <- ec_aipw(
+  ps_formula = "S ~ x1 + x2 + x3 + x4 + x5",
+  outcome_formula = c(
     "y1 ~ x1 + x2 + x3 + x4 + x5",
     "y2 ~ x1 + x2 + x3 + x4 + x5"
-  )
+  ),
+  weight = 0
 )
 
-analysis_primary_obj <- setup_analysis_primary(
+analysis <- setup_analysis_primary(
   data = SyntheticData,
   trial_status_col_name = "S",
   treatment_col_name = "A",
   outcome_col_name = c("y1", "y2"),
   covariates_col_name = c("x1", "x2", "x3", "x4", "x5"),
-  method_weighting_obj = method_weighting_obj
+  method_weighting_obj = method
 )
 
-res <- run_analysis(analysis_primary_obj)
+run_analysis(analysis)
 ```
 
-
-
-### 3 Bootstrap inference
-
-In this section we present Bootstrap inference results. We report Bootstrap confidence intervals with adjusted quantile ranges. 
-
-1) IPW with bootstrap CI
+#### 3.2 Optimal weight (data-adaptive)
 ```{r}
-# test: within trial
-## bootstrap is now specified directly in the method constructor
-method <- ec_ipw(
+method <- ec_aipw(
   ps_formula = "S ~ x1 + x2 + x3 + x4 + x5",
-  bootstrap = 50,
-  bootstrap_ci_type = "perc"
+  outcome_formula = c(
+    "y1 ~ x1 + x2 + x3 + x4 + x5",
+    "y2 ~ x1 + x2 + x3 + x4 + x5"
+  )
 )
 
-analysis_primary_obj <- setup_analysis_primary(
+analysis <- setup_analysis_primary(
   data = SyntheticData,
   trial_status_col_name = "S",
   treatment_col_name = "A",
@@ -159,52 +131,36 @@ analysis_primary_obj <- setup_analysis_primary(
   method_weighting_obj = method
 )
 
-res <- run_analysis(analysis_primary_obj)
-res
+run_analysis(analysis)
 ```
 
-2) AIPW with bootstrap CI
-
+#### 3.3 Bootstrap inference
 ```{r}
-# test: with optimal weight
-## Data argument + column names (coxph, glm)
-bootstrap_obj <- setup_bootstrap(
-  replicates = 50,
-  bootstrap_CI_type = "perc"
-)
-
-method_weighting_obj <- setup_method_weighting(
-  method_name = "AIPW",
-  optimal_weight_flag = TRUE,
-  wt = 0,
-  bootstrap_flag = TRUE,
-  bootstrap_obj = bootstrap_obj,
-  model_form_piS = "S ~ x1 + x2 + x3 + x4 + x5",
-  model_form_mu0_ext = c(
+method <- ec_aipw(
+  ps_formula = "S ~ x1 + x2 + x3 + x4 + x5",
+  outcome_formula = c(
     "y1 ~ x1 + x2 + x3 + x4 + x5",
     "y2 ~ x1 + x2 + x3 + x4 + x5"
-  )
+  ),
+  bootstrap = 50,
+  bootstrap_ci_type = "perc"
 )
 
-analysis_primary_obj <- setup_analysis_primary(
+analysis <- setup_analysis_primary(
   data = SyntheticData,
-  trial_status = "S",
-  treatment = "A",
-  outcome = c("y1", "y2"),
-  covariates = c("x1", "x2", "x3", "x4", "x5"),
-  method_weighting_obj = method_weighting_obj
+  trial_status_col_name = "S",
+  treatment_col_name = "A",
+  outcome_col_name = c("y1", "y2"),
+  covariates_col_name = c("x1", "x2", "x3", "x4", "x5"),
+  method_weighting_obj = method
 )
 
-
-res <- run_analysis(analysis_primary_obj)
-
-## best to just do the last one, but also have options
-## time dependent way of effects and modeling
+run_analysis(analysis)
 ```
 
 ### 4 Notes
 
-1. When there are missing values in the data, the suggestion we have for now is to preprocess the dataset (such as deletion, imputing, etc.) to obtain a dataset without missingness, then apply the package. For general methodology development regarding missing values, we save it for future research work.
+1. When there are missing values in the data, preprocess the dataset (deletion, imputation, etc.) to obtain a complete dataset before applying the package.
 
 ## References