Title: | Double Machine Learning with Instrumental Variables and Heterogeneity |
---|---|
Description: | Instrumental variable (IV) estimators for homogeneous and heterogeneous treatment effects with efficient machine learning instruments. The estimators are based on double/debiased machine learning allowing for nonlinear and potentially high-dimensional control variables. Details can be found in Scheidegger, Guo and Bühlmann (2025) "Inference for heterogeneous treatment effects with efficient instruments and machine learning" <doi:10.48550/arXiv.2503.03530>. |
Authors: | Cyrill Scheidegger [aut, cre, cph]
|
Maintainer: | Cyrill Scheidegger <[email protected]> |
License: | GPL (>= 3) |
Version: | 1.0.0 |
Built: | 2025-03-12 05:55:10 UTC |
Source: | https://github.com/cyrillsch/ivdml |
This function calculates the bandwidth for kernel smoothing using the Normal Reference Rule. The rule is based on Silverman's rule of thumb, which selects the bandwidth as a function of the standard deviation and interquartile range (IQR) of the data. The bandwidth is computed as: , where
is the standard deviation of
A
, is the interquartile range and
N
is the length of A
.
bandwidth_normal(A)
bandwidth_normal(A)
A |
Numeric vector. The data for which the bandwidth is to be computed. |
A numeric value representing the computed bandwidth.
Silverman, B. W. (1986). Density Estimation for Statistics and Data Analysis. Chapman & Hall/CRC monographs on statistics and applied probability. Chapman & Hall.
set.seed(1) A <- rnorm(100) bandwidth_normal(A)
set.seed(1) A <- rnorm(100) bandwidth_normal(A)
This function computes the estimated (potentially heterogeneous) treatment effect from a fitted IVDML
object (output of fit_IVDML()
).
## S3 method for class 'IVDML' coef( object, iv_method, a = NULL, A = NULL, kernel_name = NULL, bandwidth = NULL, ... )
## S3 method for class 'IVDML' coef( object, iv_method, a = NULL, A = NULL, kernel_name = NULL, bandwidth = NULL, ... )
object |
An object of class |
iv_method |
Character. The instrumental variable estimation method to use. Must be one of the methods specified in the fitted object. |
a |
Numeric (optional). A specific value of |
A |
Numeric vector (optional). The variable with respect to which treatment effect heterogeneity is considered. If |
kernel_name |
Character (optional). The name of the kernel function to use for smoothing (if a heterogeneous treatment effect is estimated). Needs to be one of "boxcar", "gaussian", "epanechnikov" or "tricube". |
bandwidth |
Numeric (optional). The bandwidth for the kernel smoothing (if a heterogeneous treatment effect is estimated). |
... |
Further arguments passed to or from other methods. |
If a
is not specified, the estimated homogeneous treatment effect is returned. If a
is specified, the heterogeneous treatment effect at
is returned.
set.seed(1) Z <- rnorm(100) X <- Z + rnorm(100) H <- rnorm(100) D <- Z^2 + sin(X) + H + rnorm(100) A <- X Y <- tanh(A) * D + cos(X) - H + rnorm(100) fit <- fit_IVDML(Y = Y, D = D, Z = Z, X = X, ml_method = "gam") coef(fit, iv_method = "mlIV") coef(fit, iv_method = "mlIV", a = 0, A = A, kernel_name = "boxcar", bandwidth = 0.2)
set.seed(1) Z <- rnorm(100) X <- Z + rnorm(100) H <- rnorm(100) D <- Z^2 + sin(X) + H + rnorm(100) A <- X Y <- tanh(A) * D + cos(X) - H + rnorm(100) fit <- fit_IVDML(Y = Y, D = D, Z = Z, X = X, ml_method = "gam") coef(fit, iv_method = "mlIV") coef(fit, iv_method = "mlIV", a = 0, A = A, kernel_name = "boxcar", bandwidth = 0.2)
This function is used to fit a Double Machine Learning (DML) model with Instrumental Variables (IV) with the goal to perform inference on potentially heterogeneous treatment effects. The model under study is , where the error
is potentially correlated with the treatment
, but there is an IV
satisfying
. The object of interest is the treatment effect
of the treatment
on the response
. The treatment effect
is either constant or can depend on the univariate quantity
, which is typically a component of the covariates
.
fit_IVDML( Y, D, Z, X = NULL, A = NULL, ml_method, ml_par = list(), A_deterministic_X = TRUE, K_dml = 5, iv_method = c("linearIV", "mlIV"), S_split = 1 )
fit_IVDML( Y, D, Z, X = NULL, A = NULL, ml_method, ml_par = list(), A_deterministic_X = TRUE, K_dml = 5, iv_method = c("linearIV", "mlIV"), S_split = 1 )
Y |
Numeric vector. Response variable. |
D |
Numeric vector. Treatment variable. |
Z |
Matrix, vector, or data frame. Instrumental variables. |
X |
Matrix, vector, or data frame. Additional covariates (default: NULL). |
A |
Numeric vector. Variable with respect to which treatment effect heterogeneity is considered. Usually equal to a column of X and in this case it can also be specified later (default: NULL). |
ml_method |
Character. Machine learning method to use. Options are "gam", "xgboost", and "randomForest". |
ml_par |
List. Parameters for the machine learning method:
|
A_deterministic_X |
Logical. Whether |
K_dml |
Integer. Number of cross-fitting folds (default: 5). |
iv_method |
Character vector. Instrumental variables estimation method. Options:
"linearIV", "mlIV", "mlIV_direct" (default: c("linearIV", "mlIV")). "linearIV" corresponds to using instruments linearly and "mlIV" corresponds to using machine learning instruments. "mlIV_direct" is a variant of "mlIV" that uses the same estimate of |
S_split |
Integer. Number of sample splits for cross-fitting (default: 1). |
An object of class IVDML
, containing:
results_splits
: A list of S_split lists of cross-fitted residuals from the different sample splits.
A
: The argument A
of the function.
ml_method
: The argument ml_method
of the function.
A_deterministic_X
: The argument A_deterministic_X
of the function.
iv_method
: The argument iv_method
of the function.
The treatment effect estimates, standard errors and confidence intervals can be calculated from the IVDML
object using the functions coef.IVDML()
, se()
, standard_confint()
, robust_confint()
.
Cyrill Scheidegger, Zijian Guo and Peter Bühlmann. Inference for heterogeneous treatment effects with efficient instruments and machine learning. Preprint, arXiv:2503.03530, 2025.
Inference for a fitted IVDML
object is done with the functions coef.IVDML()
, se()
, standard_confint()
and robust_confint()
.
set.seed(1) Z <- rnorm(100) X <- Z + rnorm(100) H <- rnorm(100) D <- Z^2 + sin(X) + H + rnorm(100) A <- X Y <- tanh(A) * D + cos(X) - H + rnorm(100) fit <- fit_IVDML(Y = Y, D = D, Z = Z, X = X, A = A, ml_method = "gam") coef(fit, iv_method = "mlIV", a = 0, A = A, kernel_name = "boxcar", bandwidth = 0.2)
set.seed(1) Z <- rnorm(100) X <- Z + rnorm(100) H <- rnorm(100) D <- Z^2 + sin(X) + H + rnorm(100) A <- X Y <- tanh(A) * D + cos(X) - H + rnorm(100) fit <- fit_IVDML(Y = Y, D = D, Z = Z, X = X, A = A, ml_method = "gam") coef(fit, iv_method = "mlIV", a = 0, A = A, kernel_name = "boxcar", bandwidth = 0.2)
Print information for an IVDML object.
## S3 method for class 'IVDML' print(x, ...)
## S3 method for class 'IVDML' print(x, ...)
x |
Fitted object of class |
... |
Further arguments passed to or from other methods. |
No return value, called for side effects
set.seed(1) Z <- rnorm(100) X <- Z + rnorm(100) H <- rnorm(100) D <- Z^2 + sin(X) + H + rnorm(100) A <- X Y <- tanh(A) * D + cos(X) - H + rnorm(100) fit <- fit_IVDML(Y = Y, D = D, Z = Z, X = X, A = A, ml_method = "gam") print(fit)
set.seed(1) Z <- rnorm(100) X <- Z + rnorm(100) H <- rnorm(100) D <- Z^2 + sin(X) + H + rnorm(100) A <- X Y <- tanh(A) * D + cos(X) - H + rnorm(100) fit <- fit_IVDML(Y = Y, D = D, Z = Z, X = X, A = A, ml_method = "gam") print(fit)
This function computes a robust (with respect to weak IV) confidence interval/confidence set for the estimated treatment effect in a fitted IVDML
object (output of fit_IVDML()
). The confidence interval/confidence set is constructed by inverting the robust test from the robust_p_value_aggregated()
function, which either uses the Double Machine Learning aggregation method ("DML_agg"
) or the quantile-based method of Meinshausen, Meier, and Bühlmann (2009) ("MMB_agg"
) to aggregate the p-values corresponding to the S_split
cross-fitting sample splits (where S_split
was an argument of the fit_IVDML()
function).
robust_confint( object, iv_method, level = 0.95, a = NULL, A = NULL, kernel_name = NULL, bandwidth = NULL, CI_range = NULL, agg_method = "DML_agg", gamma = 0.5 )
robust_confint( object, iv_method, level = 0.95, a = NULL, A = NULL, kernel_name = NULL, bandwidth = NULL, CI_range = NULL, agg_method = "DML_agg", gamma = 0.5 )
object |
An object of class |
iv_method |
Character. The instrumental variable estimation method to use. Must be one of the methods specified in the fitted object. |
level |
Numeric (default: 0.95). The confidence level for the confidence interval. |
a |
Numeric (optional). A specific value of |
A |
Numeric vector (optional). The variable with respect to which treatment effect heterogeneity is considered. If |
kernel_name |
Character (optional). The name of the kernel function to use for smoothing (if a heterogeneous treatment effect is estimated). Must be one of |
bandwidth |
Numeric (optional). The bandwidth for the kernel smoothing (if a heterogeneous treatment effect is estimated). |
CI_range |
Numeric vector of length 2 (optional). The search range for the confidence interval. If |
agg_method |
Character (default:
|
gamma |
Numeric (default: 0.5). Quantile level for the |
A list with the following elements:
CI
: A named numeric vector with the lower and upper bounds of the confidence interval.
level
: The confidence level used.
message
: A message describing the nature of the confidence set (e.g., whether it spans the full range, is non-connected, or is empty due to optimization failure).
heterogeneous_parameters
: A list of parameters (a
, kernel_name
, bandwidth
) if a heterogeneous treatment effect is considered; otherwise, NULL
.
Meinshausen, N., Meier, L., & Bühlmann, P. (2009). P-values for high-dimensional regression. Journal of the American Statistical Association, 104(488), 1671–1681.
set.seed(1) Z <- rnorm(100) X <- Z + rnorm(100) H <- rnorm(100) D <- Z^2 + sin(X) + H + rnorm(100) A <- X Y <- tanh(A) * D + cos(X) - H + rnorm(100) fit <- fit_IVDML(Y = Y, D = D, Z = Z, X = X, ml_method = "gam") robust_confint(fit, iv_method = "mlIV", CI_range = c(-10, 10)) robust_confint(fit, iv_method = "mlIV", a = 0, A = A, kernel_name = "boxcar", bandwidth = 0.2, CI_range = c(-10, 10))
set.seed(1) Z <- rnorm(100) X <- Z + rnorm(100) H <- rnorm(100) D <- Z^2 + sin(X) + H + rnorm(100) A <- X Y <- tanh(A) * D + cos(X) - H + rnorm(100) fit <- fit_IVDML(Y = Y, D = D, Z = Z, X = X, ml_method = "gam") robust_confint(fit, iv_method = "mlIV", CI_range = c(-10, 10)) robust_confint(fit, iv_method = "mlIV", a = 0, A = A, kernel_name = "boxcar", bandwidth = 0.2, CI_range = c(-10, 10))
This function calculates an aggregated robust (with respect to weak IV) p-value for testing a candidate treatment effect value in a fitted IVDML
object (output of fit_IVDML()
), using either the the standard Double Machine Learning aggregation method ("DML_agg") or the method by Meinshausen, Meier, and Bühlmann (2009) ("MMB_agg") to aggregate the p-values corresponding to the S_split
cross-fitting sample splits (where S_split
was an argument of the fit_IVDML()
function).
robust_p_value_aggregated( object, candidate_value, iv_method, a = NULL, A = NULL, kernel_name = NULL, bandwidth = NULL, agg_method = "DML_agg", gamma = 0.5 )
robust_p_value_aggregated( object, candidate_value, iv_method, a = NULL, A = NULL, kernel_name = NULL, bandwidth = NULL, agg_method = "DML_agg", gamma = 0.5 )
object |
An object of class |
candidate_value |
Numeric. The candidate treatment effect value to test. |
iv_method |
Character. The instrumental variable estimation method to use. Must be one of the methods specified in the fitted object. |
a |
Numeric (optional). A specific value of |
A |
Numeric vector (optional). The variable with respect to which treatment effect heterogeneity is considered. If |
kernel_name |
Character (optional). The name of the kernel function to use for smoothing (if a heterogeneous treatment effect is estimated). Must be one of "boxcar", "gaussian", "epanechnikov", or "tricube". |
bandwidth |
Numeric (optional). The bandwidth for the kernel smoothing (if a heterogeneous treatment effect is estimated). |
agg_method |
Character (default: "DML_agg"). The aggregation method for computing the p-value. Options are:
|
gamma |
Numeric (default: 0.5). Quantile level for the |
The aggregated robust p-value for testing the candidate treatment effect.
Meinshausen, N., Meier, L., & Bühlmann, P. (2009). P-values for high-dimensional regression. Journal of the American Statistical Association, 104(488), 1671–1681.
set.seed(1) Z <- rnorm(100) X <- Z + rnorm(100) H <- rnorm(100) D <- Z^2 + sin(X) + H + rnorm(100) A <- X Y <- tanh(A) * D + cos(X) - H + rnorm(100) fit <- fit_IVDML(Y = Y, D = D, Z = Z, X = X, A = A, ml_method = "gam") robust_p_value_aggregated(fit, candidate_value = 0, iv_method = "mlIV") robust_p_value_aggregated(fit, candidate_value = 0, iv_method = "mlIV", a = 0, A = A, kernel_name = "boxcar", bandwidth = 0.2)
set.seed(1) Z <- rnorm(100) X <- Z + rnorm(100) H <- rnorm(100) D <- Z^2 + sin(X) + H + rnorm(100) A <- X Y <- tanh(A) * D + cos(X) - H + rnorm(100) fit <- fit_IVDML(Y = Y, D = D, Z = Z, X = X, A = A, ml_method = "gam") robust_p_value_aggregated(fit, candidate_value = 0, iv_method = "mlIV") robust_p_value_aggregated(fit, candidate_value = 0, iv_method = "mlIV", a = 0, A = A, kernel_name = "boxcar", bandwidth = 0.2)
This function calculates the standard error of the estimated (potentially heterogeneous) treatment effect from a fitted IVDML
object (output of fit_IVDML()
).
se(object, iv_method, a = NULL, A = NULL, kernel_name = NULL, bandwidth = NULL)
se(object, iv_method, a = NULL, A = NULL, kernel_name = NULL, bandwidth = NULL)
object |
An object of class |
iv_method |
Character. The instrumental variable estimation method to use. Must be one of the methods specified in the fitted object. |
a |
Numeric (optional). A specific value of |
A |
Numeric vector (optional). The variable with respect to which treatment effect heterogeneity is considered. If |
kernel_name |
Character (optional). The name of the kernel function to use for smoothing (if a heterogeneous treatment effect is estimated). Must be one of "boxcar", "gaussian", "epanechnikov", or "tricube". |
bandwidth |
Numeric (optional). The bandwidth for the kernel smoothing (if a heterogeneous treatment effect is estimated). |
A numeric value representing the estimated standard error of the treatment effect estimate. If a
is not specified, the function returns the standard error of the homogeneous treatment effect. If a
is specified, it returns the standard error of the heterogeneous treatment effect estimate at .
set.seed(1) Z <- rnorm(100) X <- Z + rnorm(100) H <- rnorm(100) D <- Z^2 + sin(X) + H + rnorm(100) A <- X Y <- tanh(A) * D + cos(X) - H + rnorm(100) fit <- fit_IVDML(Y = Y, D = D, Z = Z, X = X, ml_method = "gam") se(fit, iv_method = "mlIV") se(fit, iv_method = "mlIV", a = 0, A = A, kernel_name = "boxcar", bandwidth = 0.2)
set.seed(1) Z <- rnorm(100) X <- Z + rnorm(100) H <- rnorm(100) D <- Z^2 + sin(X) + H + rnorm(100) A <- X Y <- tanh(A) * D + cos(X) - H + rnorm(100) fit <- fit_IVDML(Y = Y, D = D, Z = Z, X = X, ml_method = "gam") se(fit, iv_method = "mlIV") se(fit, iv_method = "mlIV", a = 0, A = A, kernel_name = "boxcar", bandwidth = 0.2)
This function calculates a standard confidence interval for the estimated (potentially heterogeneous) treatment effect from a fitted IVDML
object (output of fit_IVDML()
). The confidence interval is computed using the normal approximation method using the standard error computed by se()
and the treatment effect estimate from coef()
.
standard_confint( object, iv_method, a = NULL, A = NULL, kernel_name = NULL, bandwidth = NULL, level = 0.95 )
standard_confint( object, iv_method, a = NULL, A = NULL, kernel_name = NULL, bandwidth = NULL, level = 0.95 )
object |
An object of class |
iv_method |
Character. The instrumental variable estimation method to use. Must be one of the methods specified in the fitted object. |
a |
Numeric (optional). A specific value of |
A |
Numeric vector (optional). The variable with respect to which treatment effect heterogeneity is considered. If |
kernel_name |
Character (optional). The name of the kernel function to use for smoothing (if a heterogeneous treatment effect is estimated). Must be one of "boxcar", "gaussian", "epanechnikov", or "tricube". |
bandwidth |
Numeric (optional). The bandwidth for the kernel smoothing (if a heterogeneous treatment effect is estimated). |
level |
Numeric (default: 0.95). The confidence level for the interval (e.g., 0.95 for a 95% confidence interval). |
description A list containing:
CI
: A numeric vector of length 2 with the lower and upper confidence interval bounds.
level
: The confidence level used.
heterogeneous_parameters
: A list with values of a
, kernel_name
, and bandwidth
(if applicable), or NULL
if a homogeneous treatment effect is estimated.
set.seed(1) Z <- rnorm(100) X <- Z + rnorm(100) H <- rnorm(100) D <- Z^2 + sin(X) + H + rnorm(100) A <- X Y <- tanh(A) * D + cos(X) - H + rnorm(100) fit <- fit_IVDML(Y = Y, D = D, Z = Z, X = X, ml_method = "gam") standard_confint(fit, iv_method = "mlIV") standard_confint(fit, iv_method = "mlIV", a = 0, A = A, kernel_name = "boxcar", bandwidth = 0.2, level = 0.95)
set.seed(1) Z <- rnorm(100) X <- Z + rnorm(100) H <- rnorm(100) D <- Z^2 + sin(X) + H + rnorm(100) A <- X Y <- tanh(A) * D + cos(X) - H + rnorm(100) fit <- fit_IVDML(Y = Y, D = D, Z = Z, X = X, ml_method = "gam") standard_confint(fit, iv_method = "mlIV") standard_confint(fit, iv_method = "mlIV", a = 0, A = A, kernel_name = "boxcar", bandwidth = 0.2, level = 0.95)