Title:	Double Machine Learning with Instrumental Variables and Heterogeneity
Version:	1.0.0
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>.
URL:	https://github.com/cyrillsch/IVDML
License:	GPL (≥ 3)
Encoding:	UTF-8
RoxygenNote:	7.3.2
Suggests:	testthat (≥ 3.0.0)
Config/testthat/edition:	3
Imports:	mgcv, ranger, stats, xgboost
NeedsCompilation:	no
Packaged:	2025-03-10 12:55:29 UTC; scyrill
Author:	Cyrill Scheidegger [aut, cre, cph]
Maintainer:	Cyrill Scheidegger <cyrill.scheidegger@stat.math.ethz.ch>
Repository:	CRAN
Date/Publication:	2025-03-11 16:40:10 UTC

IVDML: 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.

Author(s)

Maintainer: Cyrill Scheidegger cyrill.scheidegger@stat.math.ethz.ch (ORCID) [copyright holder]

See Also

Useful links:

• https://github.com/cyrillsch/IVDML

Compute Bandwidth Using the Normal Reference Rule

Description

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: h = 1.06 \times \min(\mathrm{sd}(A), \mathrm{IQR}(A) / 1.34) / N^{0.2}, where \mathrm{sd}(A) is the standard deviation of A, \mathrm{IQR}(A) is the interquartile range and N is the length of A.

Usage

bandwidth_normal(A)

Arguments

Value

A numeric value representing the computed bandwidth.

References

Silverman, B. W. (1986). Density Estimation for Statistics and Data Analysis. Chapman & Hall/CRC monographs on statistics and applied probability. Chapman & Hall.

Examples

set.seed(1)
A <- rnorm(100)
bandwidth_normal(A)

Extract Treatment Effect Estimate from an IVDML Object

Description

This function computes the estimated (potentially heterogeneous) treatment effect from a fitted IVDML object (output of fit_IVDML()).

Usage

## S3 method for class 'IVDML'
coef(
  object,
  iv_method,
  a = NULL,
  A = NULL,
  kernel_name = NULL,
  bandwidth = NULL,
  ...
)

Arguments

Value

If a is not specified, the estimated homogeneous treatment effect is returned. If a is specified, the heterogeneous treatment effect \beta(a) at A = a is returned.

Examples

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)

Fitting Double Machine Learning Models with Instrumental Variables and Potentially Heterogeneous Treatment Effect

Description

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 Y = \beta(A)D + g(X) + \epsilon, where the error \epsilon is potentially correlated with the treatment D, but there is an IV Z satisfying \mathbb E[\epsilon|Z,X] = 0. The object of interest is the treatment effect \beta of the treatment D on the response Y. The treatment effect \beta is either constant or can depend on the univariate quantity A, which is typically a component of the covariates X.

Usage

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
)

Arguments

Value

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().

References

Cyrill Scheidegger, Zijian Guo and Peter Bühlmann. Inference for heterogeneous treatment effects with efficient instruments and machine learning. Preprint, arXiv:2503.03530, 2025.

See Also

Inference for a fitted IVDML object is done with the functions coef.IVDML(), se(), standard_confint() and robust_confint().

Examples

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 IVDML

Description

Print information for an IVDML object.

Usage

## S3 method for class 'IVDML'
print(x, ...)

Arguments

Value

No return value, called for side effects

Examples

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)

Compute Robust Confidence Interval for Treatment Effect in an IVDML Object

Description

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).

Usage

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
)

Arguments

Value

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.

References

Meinshausen, N., Meier, L., & Bühlmann, P. (2009). P-values for high-dimensional regression. Journal of the American Statistical Association, 104(488), 1671–1681.

Examples

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))

Compute Aggregated Robust p-Value for Treatment Effect in an IVDML Object

Description

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).

Usage

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
)

Arguments

Value

The aggregated robust p-value for testing the candidate treatment effect.

References

Meinshausen, N., Meier, L., & Bühlmann, P. (2009). P-values for high-dimensional regression. Journal of the American Statistical Association, 104(488), 1671–1681.

Examples

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)

Compute Standard Error for the Treatment Effect Estimate in an IVDML Object

Description

This function calculates the standard error of the estimated (potentially heterogeneous) treatment effect from a fitted IVDML object (output of fit_IVDML()).

Usage

se(object, iv_method, a = NULL, A = NULL, kernel_name = NULL, bandwidth = NULL)

Arguments

Value

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 A = a.

Examples

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)

Compute Standard Confidence Interval for the Treatment Effect Estimate in an IVDML Object

Description

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().

Usage

standard_confint(
  object,
  iv_method,
  a = NULL,
  A = NULL,
  kernel_name = NULL,
  bandwidth = NULL,
  level = 0.95
)

Arguments

Value

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.

Examples

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)