User Manual: High-Dimensional Conditional Average Treatment Effects Estimation (R Package)

The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

This package uses a two-step procedure to estimate the conditional average treatment effects (CATE) with potentially high-dimensional covariate(s). In the first stage, the nuisance functions necessary for identifying CATE can be estimated by machine learning methods, allowing the number of covariates to be comparable to or larger than the sample size. The second stage consists of a low-dimensional local linear regression, reducing CATE to a function of the covariate(s) of interest.

The CATE estimator implemented in this package not only allows for high-dimensional data, but also has the “double robustness” property: either the model for the propensity score or the models for the conditional means of the potential outcomes are allowed to be misspecified (but not both).

The algorithm used in this package is described in the paper by Fan et al., “Estimation of Conditional Average Treatment Effects With High-Dimensional Data” (2022), Journal of Business & Economic Statistics. (doi:10.1080/07350015.2020.1811102)

Installation

Install the package from github:

install.packages('devtools')
devtools::install_github('microfan1/hdcate')

Basic Usage

Load package:

library(hdcate)

Define the empirical data (which is a usual data.frame), here we use a built-in simulated data:

set.seed(1)  # set an arbitrary random seed to ensure the reproducibility
data <- HDCATE.get_sim_data(n_obs=500, n_var=100, n_rel_var=4, intercept=10)  # generate data
#> Actual CATE function is: CATE(x)=10+1*x

The simulated data contains 500 observations, each observation has 100 covariates, only the first 4 of those covariates (X1, X2, X3 and X4) are actually present in the expectation function of potential outcome, and only the last 4 covariates (X97, X98, X99 and X100) are present in the propensity score function.

Let’s see what the data looks like:

data
#>             Y D           X1           X2           X3           X4
#> 1    0.000000 0 -0.626453811  0.077303123  1.134965089  0.850043472
#> 2    0.000000 0  0.183643324 -0.296868642  1.111931845 -0.925312995
#> 3    0.000000 0 -0.835628612 -1.183242240 -0.870777634  0.893581214
#> 4    0.000000 0  1.595280802  0.011292688  0.210731585 -0.941009738
#> 5    0.000000 0  0.329507772  0.991601036  0.069395647  0.538952094
....

In the data, we know that the dependent variable is Y, treatment variable is D, and we use a model with the formula of independent variable as:

x_formula <- "X1+X2+X3+X4+X5+X6"
x_formula
#> [1] "X1+X2+X3+X4+X5+X6"

Note that the propensity score function is misspecified in this example. We shall see the “double robust” shortly.

Then, we can use the data to create a model:

model <- HDCATE(data=data, y_name='Y', d_name='D', x_formula=x_formula)

Pass this model to an operating function HDCATE.set_condition_var() to set the required conditional variable, here we want to know the conditional average treatment effects (CATE) for X2, from X2=-1 to X2=1, step by 0.01:

HDCATE.set_condition_var(model, 'X2', min=-1, max=1, step=0.01)

Then we are ready to fit the model, pass the model to the operating function HDCATE.fit() to fit the model:

HDCATE.fit(model)

After the model fitting, we obtain the resulting average treatment effects (via accesing the ate attribute of model) and conditional average treatment effects (via accesing the hdcate attribute of model):

# ATE
model$ate
#> [1] 9.874983

# CATE
model$hdcate
#>   [1]  8.989368  8.994602  9.001866  9.011095  9.022186  9.035010  9.049411
#>   [8]  9.065215  9.082236  9.100283  9.119161  9.138682  9.158664  9.178935
#>  [15]  9.199339  9.219731  9.239988  9.260001  9.279679  9.298949  9.317753
#>  [22]  9.336050  9.353811  9.371020  9.387670  9.403765  9.419310  9.434320
#>  [29]  9.448809  9.462793  9.476288  9.489310  9.501875  9.513993  9.525677
#>  [36]  9.536936  9.547775  9.558199  9.568210  9.577807  9.586984  9.595733
....

After fitting, we may want to know the uniform confidence bands, to achieve this, pass the fitted model to the operating function HDCATE.inference():

HDCATE.inference(model)

Then we obtain the uniform confidence bands for 2-sided test, left-sided test and right-sided test by accessing the i_two_side, i_left_side and i_right_side attributes of the model, respectively:

# two-sided bands
model$i_two_side
#>                                Sigificant level 0.01 Sigificant level 0.01
#> CATE on X2=-1                               8.070107              9.908629
#> CATE on X2=-0.99                            8.079787              9.909418
#> CATE on X2=-0.98                            8.091711              9.912022
#> CATE on X2=-0.97                            8.105821              9.916368
#> CATE on X2=-0.96                            8.122017              9.922356
....

# left-sided bands
model$i_left_side
#>                                Sigificant level 0.01
#> CATE on X2=-1                               8.070107
#> CATE on X2=-0.99                            8.079787
#> CATE on X2=-0.98                            8.091711
#> CATE on X2=-0.97                            8.105821
#> CATE on X2=-0.96                            8.122017
....

# right-sided bands
model$i_right_side
#>                                Sigificant level 0.01
#> CATE on X2=-1                               9.908629
#> CATE on X2=-0.99                            9.909418
#> CATE on X2=-0.98                            9.912022
#> CATE on X2=-0.97                            9.916368
#> CATE on X2=-0.96                            9.922356
....

Finally, we may want a plot for the estimated results above:

HDCATE.plot(model)

# Alternatively, if the model is not inferenced, use the code below:
# HDCATE.plot(model, include_band=FALSE)

# Alternatively, we may want to save the full plot as a high-definition PDF file:
# HDCATE.plot(model, output_pdf=TRUE, pdf_name='hdcate_plot.pdf', 
#   include_band=TRUE, test_side='both', y_axis_min='auto', y_axis_max='auto',
#   display.hdcate='HDCATEF', display.ate='ATE', display.siglevel='sig_level'
# )

HDCATE Estimation (propensity function is misspecified)

From the graph above, although the model we use is misspecified for the propensity score function (we used the formula Y~X1+X2+X3+X4+X5+X6), we still obtain a robust result, which is very close to the actual CATE function (CATE(X2)=10+X2). If we use a model that is misspecified for the expectation function of potential outcome, the results are also robust:

x_formula = paste(paste0('X', c(90:100)), collapse ='+')  # x_formula="X90+...+X100"

model <- HDCATE(data=data, y_name='Y', d_name='D', x_formula=x_formula)

HDCATE.set_condition_var(model, 'X2', min=-1, max=1, step=0.01)
HDCATE.fit(model)
HDCATE.inference(model)
HDCATE.plot(model)

HDCATE Estimation (expectation function is misspecified)

The results above show the “double robust” property of the estimating approach in this package, see Fan et al. (2022) for more theoretical results.

Advanced Usage

Full-sample Estimator vs Cross-fitting Estimator

By default, when creating an HDCATE model, this package uses full-sample approach, but you are also very welcome to use the cross-fitting approach described in Fan et al. (2022), by simply pass model into the operator HDCATE.use_cross_fitting() right after the HDCATE model has been created, that is:

# create the model first, or use an existing `model` and skip this line
model <- HDCATE(data=data, y_name='Y', d_name='D', x_formula=x_formula)

# suppose we want to use the 5-fold cross-fitting approach:
HDCATE.use_cross_fitting(model, k_fold=5)

You may also want to set the folds manually, in this case, pass a list of index vector to the third argument of the operator:

# In this case, the param k_fold is auto detected, you can pass any value to it.
HDCATE.use_cross_fitting(model, k_fold=1, folds=list(c(1:250), c(251:500)))

If we wants to use full-sample approach again, then we can use anothor operator HDCATE.use_full_sample().

HDCATE.use_full_sample(model)

User-defined Machine Learning Approach

By default, the package uses LASSO on the first stage (i.e. the estimation of the treated/untreated expectation functions and propensity score functions), but it is highly (and easily) extendable.

Researchers are welcome to define their own preferred methods (such as other ML methods) to run the first-stage estimation.

To define your own approach, you should define several functions that describe how you fit and predict the input data, and then pass those functions (and the model object) to the operator HDCATE.set_first_stage(). Then the package will use your method on the first stage.

The template of those functions are given as follows:

my_method_to_fit_expectation <- function(df) {
  # fit the input data.frame (df), where the first column is outcome value (Y)
  #   and the rest are covariates in x_formula
  # ...
  # return a fitted object
}
my_method_to_predict_expectation <- function(fitted_model, df) {
  # use the fitted object (returned by your function above) to predict the conditional expectation
  #   fucntion on the input data.frame (df)
  # ...
  # return a vector of predicted values
}
my_method_to_fit_propensity <- function(df) {
  # fit the input data.frame (df), where the first column is dummy treatment 
  #   value (D) and the rest are covariates in x_formula
  # ...
  # return a fitted object
}
my_method_to_predict_propensity <- function(fitted_model, df) {
  # use the fitted object (returned by your function above) to predict the propensity score 
  #   fucntion on the input data.frame (df)
  # ...
  # return a vector of predicted values
}

Example 1 (LASSO): the default ML method in HDCATE.fit is LASSO, users can manually define a ML method using the above template, and we again use LASSO as an example, similar practice applies for other ML methods:

Note: In practice, LASSO is the built-in method in the package, if you just want to use LASSO, there’s no need to do the following.

x_formula <- "X1+X2+X3+X4+X5+X6"  # propensity function is misspecified
# create a model
model <- HDCATE(data=data, y_name='Y', d_name='D', x_formula=x_formula)

# using the template above, we can write:
my_method_to_fit_expectation <- function(df) {
  # fit the input data.frame (df), where the first column is outcome value (Y)
  #   and the rest are covariates in x_formula
  hdm::rlasso(as.formula(paste0('Y', "~", x_formula)), df)
  # return a fitted object
}
my_method_to_predict_expectation <- function(fitted_model, df) {
  # use the fitted object (fitted_model) to predict the conditional expectation
  #   fucntion on the input data.frame (df)
  predict(fitted_model, df)
  # return a vector of predicted values
}
my_method_to_fit_propensity <- function(df) {
  # fit the input data.frame (df), where the first column is dummy treatment 
  #   variable (D) and the rest are covariates in x_formula
  hdm::rlassologit(as.formula(paste0('D', "~", x_formula)), df)
  # return a fitted object
}
my_method_to_predict_propensity <- function(fitted_model, df) {
  # use the fitted object (fitted_model) to predict the propensity score 
  #   fucntion on the input data.frame (df)
  predict(fitted_model, df, type="response")
  # return a vector of predicted values
}

After defining these functions, we can easily plug them into the package using operator HDCATE.set_first_stage():

HDCATE.set_first_stage(
  model,
  fit.treated=my_method_to_fit_expectation,
  fit.untreated=my_method_to_fit_expectation,
  fit.propensity=my_method_to_fit_propensity,
  predict.treated=my_method_to_predict_expectation,
  predict.untreated=my_method_to_predict_expectation,
  predict.propensity=my_method_to_predict_propensity
)

And then we can use the user-defined first-stage ML methods to estimate CATE:

HDCATE.set_condition_var(model, 'X2', min=-1, max=1, step=0.01)
HDCATE.fit(model)
HDCATE.inference(model)
HDCATE.plot(model)

HDCATE Estimation (using user-defined LASSO on the first stage)

We shall see the similar result, since the user-defined method in this example is the same as the built-in method (LASSO).

To clear the user-defined first-stage method and return to the default built-in method, simply call:

HDCATE.unset_first_stage(model)

Example 2 (Random Forest): Here we provide an additional example for another popular ML method: Random Forest, to further show how users can easily plug their own ML methods into this package:

# propensity function is misspecified, for example
x_formula <- "X1+X2+X3+X4+X5+X6"
# create a model
model <- HDCATE(data=data, y_name='Y', d_name='D', x_formula=x_formula)

# =========== User-defined ML approach start ===========

# using the template above, we can write:
my_method_to_fit_expectation <- function(df) {
  # fit the input data.frame (df), where the first column is outcome value (Y)
  #   and the rest are covariates in x_formula
  randomForest::randomForest(as.formula(paste0('Y', "~", x_formula)), data = df)
  # return a fitted object
}
my_method_to_predict_expectation <- function(fitted_model, df) {
  # use the fitted object (fitted_model) to predict the conditional expectation
  #   fucntion on the input data.frame (df)
  predict(fitted_model, df)
  # return a vector of predicted values
}
my_method_to_fit_propensity <- function(df) {
  # fit the input data.frame (df), where the first column is dummy treatment 
  #   variable (D) and the rest are covariates in x_formula
  randomForest::randomForest(as.formula(paste0('D', "~", x_formula)), data = df)
  # return a fitted object
}
my_method_to_predict_propensity <- function(fitted_model, df) {
  # use the fitted object (fitted_model) to predict the propensity score 
  #   fucntion on the input data.frame (df)
  predict(fitted_model, df)
  # return a vector of predicted values
}

HDCATE.set_first_stage(
  model,
  fit.treated=my_method_to_fit_expectation,
  fit.untreated=my_method_to_fit_expectation,
  fit.propensity=my_method_to_fit_propensity,
  predict.treated=my_method_to_predict_expectation,
  predict.untreated=my_method_to_predict_expectation,
  predict.propensity=my_method_to_predict_propensity
)

# =========== User-defined ML approach end ===========

# set conditional variable in CATE, same as above
HDCATE.set_condition_var(model, 'X2', min=-1, max=1, step=0.01)

# fit, inference and plot
HDCATE.fit(model)
HDCATE.inference(model)
HDCATE.plot(model)

HDCATE Estimation (using user-defined Random Forest model on the first stage)

As shown above, after applying user-defined Random Forest approach into this package, the CATE estimation result seems even better than that using LASSO in respect of confidence bands.

Futhermore, users may want to extract the fitted ML model for analysis, this can be achieved by accessing the propensity_score_model_list, untreated_cond_exp_model_list and treated_cond_exp_model_list attributes of the model object for the fitted propensity score model, fitted conditional expectation model (for untreated) and fitted conditional expectation model (for treated), respectively. The value of these attributes are “List of K”, where K is the number of folds, K=1 when using the default full-sample estimator.

For example, we may want to calculate the variable importance in fitting treated conditional expectations using the fitted random forest model:

# the list have only one element since we use full-sample estimator
rf_model <- model$treated_cond_exp_model_list[[1]]

# then, we can use the fitted object `rf_model` for futher analysis.
# the rest of codes are omitted since they are unconcerned for this package.
# ...

Variable Importance Extracted from the User-defined Random Forest Model

We can see that in this example, the powerful random forest model captures the actual relevant variable of conditional expectation functions of potential outcome (i.e. X1, X2, X3 and X4) correctly.

Similar practice applies for other ML methods.

User-defined Inference Options

Users can define their own inference procedure by passing the following arguments into HDCATE.inference():

sig_level: set significant level of the confidence bands, the default is 0.01, passing a vector of significant levels is also allowed.
n_rep_boot: set the number of bootstrap replications, the default is 1000.

For example, we may want to construct uniform confidence bands with a larger number of bootstrap replications=3000, and use another significant level=5%:

HDCATE.inference(model, sig_level=0.05, n_rep_boot=3000)

User-defined Bandwidth

On the second stage, we use rule-of-thumb to decide the bandwidth in the local linear regression, the bandwidth can also be manually set before calling HDCATE.fit():

HDCATE.set_bw(model, 0.15)  # for example, set bandwidth=0.15

To reset to default rule-of-thumb approach, call:

HDCATE.set_bw(model)

Other Details

Other details for using this package can be found on the detailed package documentation or the help files below:

help(HDCATE)
help(HDCATE.set_condition_var)
help(HDCATE.fit)
help(HDCATE.inference)
help(HDCATE.plot)
help(HDCATE.use_cross_fitting)
help(HDCATE.use_full_sample)
help(HDCATE.set_first_stage)
help(HDCATE.unset_first_stage)
help(HDCATE.set_bw)

References

Qingliang Fan, Yu-Chin Hsu, Robert P. Lieli & Yichong Zhang (2022) Estimation of Conditional Average Treatment Effects With High-Dimensional Data, Journal of Business & Economic Statistics, 40:1, 313-327, DOI: 10.1080/07350015.2020.1811102

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.