Package {ccwr}

ccwr: Clone-Censor-Weight Methods for Target Trial Emulation

Description

Provides methods for clone-censor-weight analyses that emulate target trials with grace-period treatment strategies using observational time-to-event data. Tools clone participants across strategies, apply strategy-specific artificial censoring, and estimate inverse probability of censoring weights using pooled logistic or Cox models, fit weighted outcome models, and obtain subject-level bootstrap confidence intervals by repeating the complete analysis. The methods are described by Maringe et al. (2020) doi:10.1093/ije/dyaa057 and Gaber et al. (2024) doi:10.1002/cam4.70461.

Author(s)

Maintainer: Sang Ho Park shstat1729@gmail.com

Authors:

• Youngrok Lee

• Jihyeon Baek

• Hye Won Yang

• Donghoon Jeong

See Also

Useful links:

• https://github.com/CausalInferenceLab/ccwr

• Report bugs at https://github.com/CausalInferenceLab/ccwr/issues

Apply case_when logics (e.g. policy, censoring) to clones

Description

Apply case_when logics (e.g. policy, censoring) to clones

Usage

apply_logics(clones, logics)

Arguments

Value

A list of data frame that each data frame include new variables created by the provided logics.

Examples

data(lungcancer)
arms <- c("Control", "Surgery")
clones <- clone_arms(lungcancer, arms)
policies <- create_policy_A(
  arms,
  treatment = "surgery",
  time_to_treatment = "timetosurgery",
  grace_period = 182.62,
  outcome = "death",
  followup = "fup_obs",
  clone_outcome = "outcome",
  clone_followup = "fup"
)
clones_policy <- apply_logics(clones, policies)

Duplicate data frame for each treatment arm to emulate

Description

Duplicate data frame for each treatment arm to emulate

Usage

clone_arms(data, arms)

Arguments

Value

A list of data frame. Each element of list is associated with each arm.

Examples

data(lungcancer)
clones <- clone_arms(lungcancer, c("Control", "Surgery"))

Generate censoring logic for scenario A

Description

Generate censoring logic for scenario A

Usage

create_censoring_logics_A(
  arms,
  treatment,
  time_to_treatment,
  grace_period,
  followup,
  clone_censoring = ".censoring",
  clone_uncensored_followup = ".fup_uncensored"
)

Arguments

Value

A nested list. The first element of the outer list represents untreated arm, while the second element of the outer list represents treated arm. For each element of outer list, the first element of the inner list represents emulated censoring binary indicator (0/1) that represents whether the observation violated the arm's policy within the grace period. The second element of the inner list represents the strategy-specific follow-up time for the censoring process: observed follow-up for adherent clones and artificial-censoring time for non-adherent clones. Each element of the inner list represents a sequence of logics to be passed into case_when() when creating new variables for the emulated censoring indicator and follow-up time.

Examples

arms <- c("Control", "Surgery")
censoring_logics <- create_censoring_logics_A(
  arms,
  treatment = "surgery",
  time_to_treatment = "timetosurgery",
  grace_period = 182.62,
  followup = "fup_obs",
  clone_censoring = "censoring",
  clone_uncensored_followup = "fup_uncensored"
)

Create training data for censoring probability estimation

Description

Create training data for censoring probability estimation

Usage

create_final_data(
  clones,
  clone_followup,
  clone_outcome,
  clone_censoring,
  col_ids,
  timestamp_start = "Tstart",
  id = "ID",
  timestamp_stop = "Tstop"
)

Arguments

Value

A list of long-form data frames. Each data frame represents each clone arm. Each row of the long-form data frame represents a subrecord of each observation associated with each specific time interval. The first subrecord starts with time 0, and the rows are expanded up to clone_followup, where cut times are determined by t_events argument.

Examples

data(lungcancer)
arms <- c("Control", "Surgery")
clones <- clone_arms(lungcancer, arms)
policies <- create_policy_A(
  arms, "surgery", "timetosurgery", 182.62, "death", "fup_obs",
  clone_outcome = "outcome", clone_followup = "fup"
)
clones_policy <- apply_logics(clones, policies)
censoring_logics <- create_censoring_logics_A(
  arms, "surgery", "timetosurgery", 182.62, "fup_obs",
  clone_censoring = "censoring",
  clone_uncensored_followup = "fup_uncensored"
)
clones_censored <- apply_logics(clones_policy, censoring_logics)
clones_final <- create_final_data(
  clones_censored,
  clone_followup = "fup",
  clone_outcome = "outcome",
  clone_censoring = "censoring",
  col_ids = "id"
)

Generate clone policy for scenario A

Description

Generate clone policy for scenario A

Usage

create_policy_A(
  arms,
  treatment,
  time_to_treatment,
  grace_period,
  outcome,
  followup,
  clone_outcome = ".outcome",
  clone_followup = ".fup"
)

Arguments

Value

A nested list. The first element of the outer list represents untreated arm, while the second element of the outer list represents treated arm. For each element of outer list, the first element of the inner list represents emulated outcome, and the second element of the inner list represents emulated follow up time. Each element of the inner list represents a sequence of logics to be passed into case_when() when creating new variables for emulated outcome and follow up time.

Examples

arms <- c("Control", "Surgery")
policies <- create_policy_A(
  arms,
  treatment = "surgery",
  time_to_treatment = "timetosurgery",
  grace_period = 182.62,
  outcome = "death",
  followup = "fup_obs",
  clone_outcome = "outcome",
  clone_followup = "fup"
)

Estimate the emulated trial effect

Description

Estimate the emulated trial effect

Usage

emul_estimate(
  clones_weighted,
  method = c("Cox", "logistic", "KM"),
  cluster = "id",
  weights = NULL,
  predictors = NULL,
  outcome = "outcome",
  time_start = "Tstart",
  time_stop = "Tstop",
  arm = "arms"
)

Arguments

Value

A fitted model object: "coxph" for Cox, "glm" for logistic, or "survfit" for KM.

Examples

data(lungcancer)
arms <- c("Control", "Surgery")
clones <- clone_arms(lungcancer, arms)
policies <- create_policy_A(
  arms, "surgery", "timetosurgery", 182.62, "death", "fup_obs",
  clone_outcome = "outcome", clone_followup = "fup"
)
clones_policy <- apply_logics(clones, policies)
censoring_logics <- create_censoring_logics_A(
  arms, "surgery", "timetosurgery", 182.62, "fup_obs",
  clone_censoring = "censoring",
  clone_uncensored_followup = "fup_uncensored"
)
clones_censored <- apply_logics(clones_policy, censoring_logics)
clones_final <- create_final_data(
  clones_censored, "fup", "outcome", "censoring", "id"
)
clones_estimated <- estimate_censoring(
  clones_final,
  predictors = c("age", "sex"),
  method = "pooled_logit"
)
clones_weighted <- weight_cases(clones_estimated)
fit <- emul_estimate(
  clones_weighted,
  method = "Cox",
  weights = "weight_Cox",
  predictors = c("age", "sex")
)

Bootstrap a complete clone-censor-weight analysis

Description

Resamples subjects from the original subject-level data and repeats the complete analysis in every bootstrap replicate: cloning, strategy-specific artificial censoring, person-time expansion, censoring-model estimation, weighting, and outcome-model estimation.

Usage

emul_estimate_bootstrap(
  data,
  arms,
  id,
  treatment,
  time_to_treatment,
  grace_period,
  outcome,
  followup,
  censoring_predictors = NULL,
  censoring_method = c("pooled_logit", "stabilized_logit", "Cox"),
  numerator_predictors = NULL,
  censoring_time_spline_df = NULL,
  method = c("Cox", "logistic"),
  predictors = NULL,
  n_bootstrap = 200,
  conf_level = 0.95,
  eps = 1e-06,
  seed = NULL
)

Arguments

Value

A list containing the full-sample effect estimate, percentile confidence limits, bootstrap estimates, and analysis settings. Effects are returned on the exponentiated coefficient scale: a hazard ratio for Cox models and an odds ratio for logistic models.

Examples

data(lungcancer)
boot <- emul_estimate_bootstrap(
  lungcancer,
  arms = c("Control", "Surgery"),
  id = "id",
  treatment = "surgery",
  time_to_treatment = "timetosurgery",
  grace_period = 182.62,
  outcome = "death",
  followup = "fup_obs",
  censoring_predictors = c("age", "sex"),
  predictors = c("age", "sex"),
  n_bootstrap = 3,
  seed = 1
)

Estimate censoring probabilities

Description

Estimate censoring probabilities

Usage

estimate_censoring(
  clones,
  predictors = NULL,
  method = c("Cox", "pooled_logit", "stabilized_logit"),
  numerator_predictors = NULL,
  censoring = "censoring",
  id = "id",
  time_start = "Tstart",
  time_stop = "Tstop",
  time_spline_df = NULL,
  eps = 1e-06
)

Arguments

Value

A named list of clone data frames with censoring probability columns added. All methods add P_uncens; pooled-logit methods also add p_cens_den, and stabilized pooled logit adds p_cens_num and P_uncens_num.

Examples

data(lungcancer)
arms <- c("Control", "Surgery")
clones <- clone_arms(lungcancer, arms)
policies <- create_policy_A(
  arms, "surgery", "timetosurgery", 182.62, "death", "fup_obs",
  clone_outcome = "outcome", clone_followup = "fup"
)
clones_policy <- apply_logics(clones, policies)
censoring_logics <- create_censoring_logics_A(
  arms, "surgery", "timetosurgery", 182.62, "fup_obs",
  clone_censoring = "censoring",
  clone_uncensored_followup = "fup_uncensored"
)
clones_censored <- apply_logics(clones_policy, censoring_logics)
clones_final <- create_final_data(
  clones_censored, "fup", "outcome", "censoring", "id"
)
clones_estimated <- estimate_censoring(
  clones_final,
  predictors = c("age", "sex"),
  method = "pooled_logit"
)

Simulated lung cancer patients data by Maringe et al. (2020)

Description

The dataset is from the supplementary files of Maringe et al. (2020), doi:10.1093/ije/dyaa057. The dataset is a set of 200 simulated lung cancer patients. These patients are followed up for a year following their cancer diagnosis: 106 of them received surgery within six months of their diagnosis and 48 died in the year.

Usage

lungcancer

Format

lungcancer

A data frame with 200 rows and 12 columns:

id

patient identifier

fup_obs

observed follow-up time (time to death or 1 year if censored alive)

death

observed event of interest (all-cause death) 1: dead, 0:alive

timetosurgery

time to surgery (NA if no surgery)

surgery

observed treatment 1 if the patient received surgery within 6 month, 0 otherwise

age

age at diagnosis

sex

patient's sex

perf

performance status at diagnosis

stage

stage at diagnosis

deprivation

deprivation score

charlson

Charlson's comorbidity index

emergency

route to diagnosis

Details

See system.file("COPYRIGHTS", package = "ccwr") for the source and copyright notice.

Source

doi:10.1093/ije/dyaa057

Examples

data(lungcancer)

Construct a survival response

Description

Construct a survival response

Usage

make_surv_response(data, follow_up, event)

Arguments

Value

An object of class "Surv".

Examples

data(lungcancer)
surv_response <- make_surv_response(
  lungcancer,
  follow_up = "fup_obs",
  event = "death"
)

13 types of patient records in Maringe et al. (2020)

Description

The dataset is from Figure 2 in Maringe et al. (2020), doi:10.1093/ije/dyaa057. The dataset illustrates all possible censoring mechanisms with 13 types of patients records that could be seen in the cancer registry data, when allowing at most one treatment (surgery in this example) for each patient and outcome event (death in this example) happens at most once for each patient.

Usage

patients13

Format

patients13

A data frame with 13 rows and 5 columns:

id

patient identifier

surgery

observed treatment 1 if the patient received surgery during follow-up, 0 otherwise

time_to_surgery

time to surgery in days (NA if no surgery)

death

observed event at the latest follow-up, 1: dead, 0: alive

followup

observed follow-up time (time to death or time to latest followup with 1 year (365 days) at maximum)

Details

See system.file("COPYRIGHTS", package = "ccwr") for the source and copyright notice.

Source

doi:10.1093/ije/dyaa057

Examples

data(patients13)

Read trial-style data from CSV

Description

Read trial-style data from CSV

Usage

read_trial_data(file, show_col_types = FALSE)

Arguments

Value

A tibble.

Examples

csv_file <- tempfile(fileext = ".csv")
writeLines(
  c(
    "id,follow_up,event,treatment",
    "1,10,1,A",
    "2,12,0,B"
  ),
  con = csv_file
)
trial_data <- read_trial_data(csv_file)

Add inverse probability of censoring weights

Description

Add inverse probability of censoring weights

Usage

weight_cases(
  clones,
  uncensored_prob = "P_uncens",
  numerator_uncensored_prob = "P_uncens_num",
  weight = "weight_Cox",
  eps = 1e-06
)

Arguments

Value

A named list of clone data frames with the weight column added.

Examples

data(lungcancer)
arms <- c("Control", "Surgery")
clones <- clone_arms(lungcancer, arms)
policies <- create_policy_A(
  arms, "surgery", "timetosurgery", 182.62, "death", "fup_obs",
  clone_outcome = "outcome", clone_followup = "fup"
)
clones_policy <- apply_logics(clones, policies)
censoring_logics <- create_censoring_logics_A(
  arms, "surgery", "timetosurgery", 182.62, "fup_obs",
  clone_censoring = "censoring",
  clone_uncensored_followup = "fup_uncensored"
)
clones_censored <- apply_logics(clones_policy, censoring_logics)
clones_final <- create_final_data(
  clones_censored, "fup", "outcome", "censoring", "id"
)
clones_estimated <- estimate_censoring(
  clones_final,
  predictors = c("age", "sex"),
  method = "pooled_logit"
)
clones_weighted <- weight_cases(clones_estimated)