CRE
In CRE: Interpretable Discovery and Inference of Heterogeneous Treatment Effects

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Installation

Installing from CRAN.

install.packages("CRE")

Installing the latest developing version.

library(devtools)
install_github("NSAPH-Software/CRE", ref = "develop")

Import.

library("CRE")

Arguments

Data (required)

y The observed response/outcome vector (binary or continuous).

z The treatment/exposure/policy vector (binary).

X The covariate matrix (binary or continuous).

Parameters (not required)

method_parameters The list of parameters to define the models used, including:
- ratio_dis The ratio of data delegated to the discovery sub-sample (default: 0.5).
- ite_method The method to estimate the individual treatment effect (default: "aipw") [1].
- learner_ps The (SuperLearner) model for the propensity score estimation (default: "SL.xgboost", used only for "aipw","bart","cf" ITE estimators).
- learner_y The (SuperLearner) model for the outcome estimation (default: "SL.xgboost", used only for "aipw","slearner","tlearner" and "xlearner" ITE estimators).

hyper_params The list of hyper parameters to fine tune the method, including:
- intervention_vars Intervention-able variables used for Rules Generation (default: NULL).
- ntrees The number of decision trees for random forest (default: 20).
- node_size Minimum size of the trees' terminal nodes (default: 20).
- max_rules Maximum number of candidate decision rules (default: 50).
- max_depth Maximum rules length (default: 3).
- t_decay The decay threshold for rules pruning (default: 0.025).
- t_ext The threshold to define too generic or too specific (extreme) rules (default: 0.01).
- t_corr The threshold to define correlated rules (default: 1).
- stability_selection Method for stability selection for selecting the rules. vanilla for stability selection, error_control for stability selection with error control and no for no stability selection (default: vanilla).
- B Number of bootstrap samples for stability selection in rules selection and uncertainty quantification in estimation (default: 20). - subsample Bootstrap ratio subsample for stability selection in rules selection and uncertainty quantification in estimation (default: 0.5). - offset Name of the covariate to use as offset (i.e. "x1") for T-Poisson ITE Estimation. NULL if not used (default: NULL).
- cutoff Threshold defining the minimum cutoff value for the stability scores in Stability Selection (default: 0.9).
- pfer Upper bound for the per-family error rate (tolerated amount of falsely selected rules) in Error Control Stability Selection (default: 1).

Additional Estimates (not required)

ite The estimated ITE vector. If given, both the ITE estimation steps in Discovery and Inference are skipped (default: NULL).

Notes

Options for the ITE estimation

[1] Options for the ITE estimation are as follows:
- S-Learner (slearner).
- T-Learner (tlearner)
- T-Poisson(tpoisson)
- X-Learner (xlearner)
- Augmented Inverse Probability Weighting (aipw)
- Causal Forests (cf)
- Causal Bayesian Additive Regression Trees (bart)

If other estimates of the ITE are provided in ite additional argument, both the ITE estimations in discovery and inference are skipped and those values estimates are used instead. The ITE estimator requires also an outcome learner and/or a propensity score learner from the SuperLearner package (i.e., "SL.lm", "SL.svm"). Both these models are simple classifiers/regressors. By default XGBoost algorithm is used for both these steps.

Customized wrapper for SuperLearner

One can create a customized wrapper for SuperLearner internal packages. The following is an example of providing the number of cores (e.g., 12) for the xgboost package in a shared memory system.

m_xgboost <- function(nthread = 12, ...) {
  SuperLearner::SL.xgboost(nthread = nthread, ...)
}

Then use "m_xgboost", instead of "SL.xgboost".

Examples

Example 1 (default parameters)

set.seed(9687)
dataset <- generate_cre_dataset(n = 1000, 
                                rho = 0, 
                                n_rules = 2, 
                                p = 10,
                                effect_size = 2, 
                                binary_covariates = TRUE,
                                binary_outcome = FALSE,
                                confounding = "no")
y <- dataset[["y"]]
z <- dataset[["z"]]
X <- dataset[["X"]]

cre_results <- cre(y, z, X)
summary(cre_results)
plot(cre_results)
ite_pred <- predict(cre_results, X)

Example 2 (personalized ite estimation)

set.seed(9687)
dataset <- generate_cre_dataset(n = 1000, 
                                rho = 0, 
                                n_rules = 2, 
                                p = 10,
                                effect_size = 2, 
                                binary_covariates = TRUE,
                                binary_outcome = FALSE,
                                confounding = "no")
  y <- dataset[["y"]]
  z <- dataset[["z"]]
  X <- dataset[["X"]]

ite_pred <- ... # personalized ite estimation
cre_results <- cre(y, z, X, ite = ite_pred)
summary(cre_results)
plot(cre_results)
ite_pred <- predict(cre_results, X)

Example 3 (setting parameters)

set.seed(9687)
dataset <- generate_cre_dataset(n = 1000, 
                                rho = 0, 
                                n_rules = 2, 
                                p = 10,
                                effect_size = 2, 
                                binary_covariates = TRUE,
                                binary_outcome = FALSE,
                                confounding = "no")
y <- dataset[["y"]]
z <- dataset[["z"]]
X <- dataset[["X"]]

method_params <- list(ratio_dis = 0.5,
                      ite_method ="aipw",
                      learner_ps = "SL.xgboost",
                      learner_y = "SL.xgboost")

hyper_params <- list(intervention_vars = c("x1","x2","x3","x4"),
                     offset = NULL,
                     ntrees = 20,
                     node_size = 20,
                     max_rules = 50,
                     max_depth = 3,
                     t_decay = 0.025,
                     t_ext = 0.025,
                     t_corr = 1,
                     stability_selection = "vanilla",
                     cutoff = 0.8,
                     pfer = 1,
                     B = 10,
                     subsample = 0.5)

cre_results <- cre(y, z, X, method_params, hyper_params)
summary(cre_results)
plot(cre_results)
ite_pred <- predict(cre_results, X)