Package 'ddml'

Description

Random subsample from the data of Angrist & Evans (1998).

Usage

AE98

Format

A data frame with 5,000 rows and 13 variables.

worked

Indicator equal to 1 if the mother is employed.

weeksw

Number of weeks of employment.

hoursw

Hours worked per week.

morekids

Indicator equal to 1 if the mother has more than 2 kids.

samesex

Indicator equal to 1 if the first two children are of the same sex.

age

Age in years.

agefst

Age in years at birth of the first child.

black

Indicator equal to 1 if the mother is black.

hisp

Indicator equal to 1 if the mother is Hispanic.

othrace

Indicator equal to 1 if the mother is neither black nor Hispanic.

educ

Years of education.

boy1st

Indicator equal to 1 if the first child is male.

boy2nd

Indicator equal to 1 if the second child is male.

Source

doi:10.7910/DVN/4W9GW2

References

Angrist J, Evans W (1998). "Children and Their Parents' Labor Supply: Evidence from Exogenous Variation in Family Size." American Economic Review, 88(3), 450-477.

Description

Returns a named list of single-ensemble ddml objects. Each element retains all S3 methods (summary, tidy, glance, confint, vcov).

Usage

## S3 method for class 'ddml'
as.list(x, ...)

Arguments

Value

A named list of length nfit.

Examples

y = AE98[, "worked"]
D = AE98[, "morekids"]
X = AE98[, c("age","agefst","black","hisp","othrace")]
fit = ddml_plm(y, D, X,
               learners = list(
                 list(what = ols),
                 list(what = mdl_glmnet)),
               ensemble_type = c("nnls", "singlebest"),
               sample_folds = 2, silent = TRUE)
as.list(fit)

Description

Returns a named list of single-ensemble ddml_rep objects.

Usage

## S3 method for class 'ddml_rep'
as.list(x, ...)

Arguments

Value

A named list of ddml_rep objects.

Examples

y = AE98[, "worked"]
D = AE98[, "morekids"]
X = AE98[, c("age","agefst","black","hisp","othrace")]
reps = ddml_replicate(ddml_plm, y = y, D = D, X = X,
                      learners = list(what = ols),
                      resamples = 3,
                      sample_folds = 2,
                      silent = TRUE)
as.list(reps)

Description

Returns a named list of single-fit ral objects, one per column of coefficients. This is the primary mechanism for passing multi-ensemble results to modelsummary.

Usage

## S3 method for class 'ral'
as.list(x, ...)

Arguments

Value

A named list of ral objects, each with nfit = 1.

See Also

ral, lincom

Description

Returns a named list of single-fit ral_rep objects. Each element aggregates across resamples for a single ensemble type.

Usage

## S3 method for class 'ral_rep'
as.list(x, ...)

Arguments

Value

A named list of ral_rep objects.

Description

Extract Coefficients from a RAL Object

Usage

## S3 method for class 'ral'
coef(object, ...)

Arguments

Value

Named vector (single fit) or matrix (multiple fits).

Description

Extract Aggregated Coefficients

Usage

## S3 method for class 'ral_rep'
coef(object, aggregation = c("median", "mean", "spectral"), ...)

Arguments

Value

Named vector (single fit) or matrix (multiple).

Description

Computes confidence intervals for one or more parameters.

Usage

## S3 method for class 'ral'
confint(
  object,
  parm = NULL,
  level = 0.95,
  fit_idx = 1,
  type = "HC1",
  uniform = FALSE,
  bootstraps = 999L,
  ...
)

Arguments

Value

A matrix with columns for lower and upper bounds. When uniform = TRUE, the attribute "crit_val" contains the critical value.

References

Chernozhukov V, Chetverikov D, Kato K (2013). "Gaussian approximations and multiplier bootstrap for maxima of sums of high-dimensional random vectors." Annals of Statistics, 41(6), 2786-2819.

See Also

vcov.ral

Description

Confidence Intervals for RAL Rep Objects

Usage

## S3 method for class 'ral_rep'
confint(
  object,
  parm = NULL,
  level = 0.95,
  fit_idx = 1,
  aggregation = c("median", "mean", "spectral"),
  type = "HC1",
  uniform = FALSE,
  bootstraps = 999L,
  ...
)

Arguments

Value

A matrix with columns for lower and upper bounds. When uniform = TRUE, the attribute "crit_val" contains the aggregated critical value.

References

Chernozhukov V, Chetverikov D, Kato K (2013). "Gaussian approximations and multiplier bootstrap for maxima of sums of high-dimensional random vectors." Annals of Statistics, 41(6), 2786-2819.

Description

Cross-fitted predictions using stacking.

Usage

crosspred(
  y,
  X,
  learners,
  sample_folds = 10,
  ensemble_type = "average",
  cv_folds = 10,
  custom_ensemble_weights = NULL,
  cluster_variable = seq_along(y),
  subsamples = NULL,
  cv_subsamples = NULL,
  cv_subsamples_list = NULL,
  silent = FALSE,
  auxiliary_X = NULL,
  parallel = NULL
)

Arguments

Details

crosspred implements the cross-fitting step of the Double/Debiased Machine Learning procedure combined with stacking. It produces the cross-fitted nuisance estimates $\hat{\eta}(X_i)$ used in the Neyman orthogonal scores of all ddml_* estimators.

Let $\{I_1, \ldots, I_S\}$ be an $S$-fold partition of $\{1, \ldots, n\}$, and denote the training set for fold $s$ by $\mathcal{T}_s = \{1, \ldots, n\} \setminus I_s$. Given $J$ base learners, the procedure operates on each cross-fitting fold $s$ in three steps:

Step 1 (Stacking weights). Run $K$-fold cross-validation on $\mathcal{T}_s$ (via crossval) to estimate the MSPE of each base learner, and solve for fold-specific stacking weights $\hat{w}_s = (\hat{w}_{1,s}, \ldots, \hat{w}_{J,s})'$.

Step 2 (Fit). Fit each base learner $j$ on the full training set $\mathcal{T}_s$, yielding $\hat{f}_{j,s}(\cdot)$.

Step 3 (Predict). For each $i \in I_s$, compute the ensemble cross-fitted prediction

$\hat{\eta}(X_i) = \sum_{j=1}^{J} \hat{w}_{j,s} \hat{f}_{j,s}(X_i).$

Since every observation belongs to exactly one fold, the result is a complete $n$-vector of out-of-sample predictions. Crucially, both the stacking weights $\hat{w}_s$ and the base learner fits $\hat{f}_{j,s}$ depend only on $\mathcal{T}_s$, which does not contain observation $i$.

When a single learner is used ($J = 1$), no stacking or inner cross-validation is performed: the learner is simply fitted on $\mathcal{T}_s$ and predictions are made for $I_s$.

Value

crosspred returns a list containing the following components:

cf_fitted

A matrix of out-of-sample predictions, each column corresponding to an ensemble type (in chronological order).

weights

An array, providing the weight assigned to each base learner (in chronological order) by the ensemble procedures.

mspe

A numeric vector of per-learner out-of-sample MSPEs, computed from cross-fitted residuals.

r2

A numeric vector of per-learner out-of-sample R-squared values.

cv_resid_byfold

A list (length sample_folds) of inner cross-validation residual matrices used for ensemble weight estimation. NULL when a single learner is used.

auxiliary_fitted

When auxiliary_X is not NULL, a list of matrices with additional predictions.

cf_fitted_bylearner

A matrix of out-of-sample predictions, each column corresponding to a base learner (in chronological order).

cf_resid_bylearner

A matrix of out-of-sample residuals (y - cf_fitted_bylearner), each column corresponding to a base learner.

auxiliary_fitted_bylearner

When auxiliary_X is not NULL, a list of matrices with additional predictions for each learner.

References

Ahrens A, Hansen C B, Schaffer M E, Wiemann T (2024). "Model Averaging and Double Machine Learning." Journal of Applied Econometrics, 40(3): 249-269.

Wolpert D H (1992). "Stacked generalization." Neural Networks, 5(2), 241-259.

See Also

Other utilities: crossval(), ddml(), diagnostics(), ensemble(), ensemble_weights(), shortstacking()

Examples

# Construct variables from the included Angrist & Evans (1998) data
y = AE98[, "worked"]
X = AE98[, c("morekids", "age","agefst","black","hisp","othrace","educ")]

# Compute cross-predictions using stacking with base learners ols and lasso.
#     Two stacking approaches are simultaneously computed: Equally
#     weighted (ensemble_type = "average") and MSPE-minimizing with weights
#     in the unit simplex (ensemble_type = "nnls1"). Predictions for each
#     learner are also calculated.
crosspred_res <- crosspred(y, X,
                           learners = list(list(what = ols),
                                           list(what = mdl_glmnet)),
                           ensemble_type = c("average",
                                             "nnls1",
                                             "singlebest"),
                           sample_folds = 2,
                           cv_folds = 2,
                           silent = TRUE)
dim(crosspred_res$cf_fitted) # = length(y) by length(ensemble_type)
dim(crosspred_res$cf_fitted_bylearner) # = length(y) by length(learners)

Description

Estimator of the mean squared prediction error of different learners using cross-validation.

Usage

crossval(
  y,
  X,
  learners,
  cv_folds = 10,
  cluster_variable = seq_along(y),
  cv_subsamples = NULL,
  silent = FALSE,
  parallel = NULL
)

Arguments

Details

crossval estimates the mean squared prediction error (MSPE) of $J$ base learners via $K$-fold cross-validation. It is the inner workhorse of the stacking machinery used by ensemble_weights to determine ensemble weights.

Given a generic conditional expectation function $f_0(\cdot)$ (e.g., $E[Y\vert X]$, $E[D\vert X]$), let $\{I_1, \ldots, I_K\}$ be a $K$-fold partition of $\{1, \ldots, n\}$ and let $\hat{f}_j^{(-k)}$ denote learner $j$ trained on all observations outside fold $I_k$. The out-of-sample residual for observation $i \in I_k$ is

$\hat{e}_{i,j} = y_i - \hat{f}_j^{(-k)}(X_i).$

Since every observation belongs to exactly one fold, this yields a complete $n \times J$ residual matrix. The cross-validated MSPE for learner $j$ is

$\widehat{\textrm{MSPE}}_j = n^{-1} \sum_{i=1}^{n} \hat{e}_{i,j}^2,$

and the cross-validated $R^2$ is

$\hat{R}^2_j = 1 - \widehat{\textrm{MSPE}}_j \,/\, \hat{\sigma}^2_y,$

where $\hat{\sigma}^2_y$ is the sample variance of $y$.

Value

crossval returns a list containing the following components:

mspe

A vector of MSPE estimates, each corresponding to a base learner (in chronological order).

r2

A vector of cross-validated $R^2$ values, each corresponding to a base learner (in chronological order).

cv_resid

A matrix of out-of-sample residuals, each column corresponding to a base learner (in chronological order).

cv_subsamples

Pass-through of cv_subsamples. See above.

See Also

Other utilities: crosspred(), ddml(), diagnostics(), ensemble(), ensemble_weights(), shortstacking()

Examples

# Construct variables from the included Angrist & Evans (1998) data
y = AE98[, "worked"]
X = AE98[, c("morekids", "age","agefst","black","hisp","othrace","educ")]

# Compare ols, lasso, and ridge using 4-fold cross-validation
cv_res <- crossval(y, X,
                   learners = list(list(what = ols),
                                   list(what = mdl_glmnet),
                                   list(what = mdl_glmnet,
                                        args = list(alpha = 0))),
                   cv_folds = 4,
                   silent = TRUE)
cv_res$mspe

Description

Build a "ddml" object from user-supplied score components. The resulting object inherits all S3 methods available for ddml objects, including summary.ddml, confint.ral, vcov.ral, and tidy.ddml.

Usage

ddml(
  coefficients,
  scores,
  J,
  inf_func,
  nobs,
  coef_names,
  estimator_name,
  ensemble_type = colnames(coefficients),
  cluster_variable = seq_len(nobs),
  sample_folds = NULL,
  cv_folds = NULL,
  shortstack = FALSE,
  ensemble_weights = NULL,
  mspe = NULL,
  r2 = NULL,
  fitted = NULL,
  splits = NULL,
  call = match.call(),
  subclass = NULL,
  dinf_dtheta = NULL,
  ...
)

Arguments

Value

An object of S3 class "ddml" (or c(subclass, "ddml") if subclass is specified). See ddml-intro for the output structure.

See Also

Other utilities: crosspred(), crossval(), diagnostics(), ensemble(), ensemble_weights(), shortstacking()

Examples

# A minimal example: construct a ddml object from pre-computed
#     score components for a simple mean estimator.
n <- 100
y <- rnorm(n)
theta <- mean(y)

scores <- array(y - theta, dim = c(n, 1, 1))
J <- array(-1, dim = c(1, 1, 1))
psi_b <- list(matrix(y, ncol = 1))
psi_a <- list(array(-1, dim = c(n, 1, 1)))
inf_func <- array(y - theta, dim = c(n, 1, 1))
dinf_dtheta <- array(1, dim = c(n, 1, 1, 1))
coef <- matrix(theta, 1, 1, dimnames = list("mean", "custom"))

fit <- ddml(coefficients = coef, scores = scores, J = J,
        inf_func = inf_func, nobs = n, coef_names = "mean",
        dinf_dtheta = dinf_dtheta,
        estimator_name = "Sample Mean")
summary(fit)

Description

Estimator for the average potential outcome, allowing for custom weights $\omega(X)$.

Usage

ddml_apo(
  y,
  D,
  X,
  d = 1,
  weights = NULL,
  learners,
  learners_DX = learners,
  sample_folds = 10,
  ensemble_type = "nnls",
  shortstack = FALSE,
  cv_folds = 10,
  custom_ensemble_weights = NULL,
  custom_ensemble_weights_DX = custom_ensemble_weights,
  cluster_variable = seq_along(y),
  stratify = TRUE,
  trim = 0.01,
  silent = FALSE,
  parallel = NULL,
  fitted = NULL,
  splits = NULL,
  save_crossval = TRUE,
  ...
)

Arguments

Details

Parameter of Interest: ddml_apo provides a Double/Debiased Machine Learning estimator for the average potential outcome. Under conditional unconfoundedness and overlap, the parameter is identified by the following reduced form conditional expectation:

$\theta_0^{\textrm{APO}} = E[\omega(X) E[Y|D=d, X]],$

where $W \equiv (Y, D, X)$ is the observed random vector and $\omega(X)$ is a known weighting function. If $\omega(X) = 1$, this parameter corresponds to the average potential outcome at treatment level $d$.

Nuisance Parameters: The nuisance parameters are $\eta = (\ell, r)$ taking true values $\ell_0(X) = E[Y|D=d, X]$ and $r_0(X) = \Pr(D=d|X)$.

Neyman Orthogonal Score / Moment Equation: The Neyman orthogonal score is:

$m(W; \theta, \eta) = \left( \frac{\mathbf{1}\{D=d\} (Y - \ell(X))}{r(X)} + \ell(X) \right) \omega(X) - \theta$

Jacobian:

$J = -1$

See ddml-intro for how the influence function and inference are derived from these components.

Value

ddml_apo returns an object of S3 class ddml_apo and ddml. See ddml-intro for the common output structure. Additional pass-through fields: learners, learners_DX.

See Also

Other ddml estimators: ddml-intro, ddml_ate(), ddml_attgt(), ddml_fpliv(), ddml_late(), ddml_pliv(), ddml_plm(), ddml_policy()

Examples

# Construct variables from the included Angrist & Evans (1998) data
y = AE98[, "worked"]
D = AE98[, "morekids"]
X = AE98[, c("age","agefst","black","hisp","othrace","educ")]

# Estimate the APO for d = 1 using a single base learner, ridge.
apo_fit <- ddml_apo(y, D, X,
                    learners = list(what = mdl_glmnet),
                    sample_folds = 2,
                    silent = TRUE)
summary(apo_fit)

Description

Estimator for the average treatment effect and the average treatment effect on the treated.

Usage

ddml_ate(
  y,
  D,
  X,
  learners,
  learners_DX = learners,
  sample_folds = 10,
  ensemble_type = "nnls",
  shortstack = FALSE,
  cv_folds = 10,
  custom_ensemble_weights = NULL,
  custom_ensemble_weights_DX = custom_ensemble_weights,
  cluster_variable = seq_along(y),
  stratify = TRUE,
  trim = 0.01,
  silent = FALSE,
  parallel = NULL,
  fitted = NULL,
  splits = NULL,
  save_crossval = TRUE,
  ...
)

ddml_att(
  y,
  D,
  X,
  learners,
  learners_DX = learners,
  sample_folds = 10,
  ensemble_type = "nnls",
  shortstack = FALSE,
  cv_folds = 10,
  custom_ensemble_weights = NULL,
  custom_ensemble_weights_DX = custom_ensemble_weights,
  cluster_variable = seq_along(y),
  stratify = TRUE,
  trim = 0.01,
  silent = FALSE,
  parallel = NULL,
  fitted = NULL,
  splits = NULL,
  save_crossval = TRUE,
  ...
)

Arguments

Details

Parameter of Interest: ddml_ate and ddml_att provide Double/Debiased Machine Learning estimators for the average treatment effect and the average treatment effect on the treated, respectively. Under conditional unconfoundedness and overlap, the parameters are identified by the following reduced form parameters:

$\theta_0^{\textrm{ATE}} = E[E[Y|D=1, X] - E[Y|D=0, X]]$

and the average treatment effect on the treated (ATT) is defined as

$\theta_0^{\textrm{ATT}} = E[Y|D=1] - E[E[Y|D=0, X]|D = 1].$

where $W \equiv (Y, D, X)$ is the observed random vector.

Neyman Orthogonal Score: The Neyman orthogonal scores are:

$m^{\textrm{ATE}}(W; \theta, \eta) = \frac{D(Y - \ell_1(X))}{r(X)} - \frac{(1-D)(Y-\ell_0(X))}{1-r(X)} + \ell_1(X) - \ell_0(X) - \theta$

$m^{\textrm{ATT}}(W; \theta, \eta) = \frac{D(Y - \ell_0(X))}{\pi} - \frac{r(X)(1-D)(Y-\ell_0(X))}{\pi(1-r(X))} - \frac{D}{\pi}\theta$

where the nuisance parameters are $\eta = (\ell_0, \ell_1, r, \pi)$ taking true values $\ell_{d,0}(X) = E[Y|D=d, X]$, $r_0(X) = \Pr(D=1|X)$, and $\pi_0 = \Pr(D=1)$.

Jacobian:

$J^{\textrm{ATE}} = -1$

$J^{\textrm{ATT}} = -1$

See ddml-intro for how the influence function and inference are derived from these components.

Value

ddml_ate and ddml_att return objects of S3 class ddml_ate/ddml_att and ddml. See ddml-intro for the common output structure. Additional pass-through fields: learners, learners_DX.

See Also

Other ddml estimators: ddml-intro, ddml_apo(), ddml_attgt(), ddml_fpliv(), ddml_late(), ddml_pliv(), ddml_plm(), ddml_policy()

Examples

# Construct variables from the included Angrist & Evans (1998) data
y = AE98[, "worked"]
D = AE98[, "morekids"]
X = AE98[, c("age","agefst","black","hisp","othrace","educ")]

# Estimate the average treatment effect using a single base learner, ridge.
ate_fit <- ddml_ate(y, D, X,
                    learners = list(what = mdl_glmnet,
                                    args = list(alpha = 0)),
                    sample_folds = 2,
                    silent = TRUE)
summary(ate_fit)

# Estimate the average treatment effect using short-stacking with base
#     learners ols, lasso, and ridge. We can also use custom_ensemble_weights
#     to estimate the ATE using every individual base learner.
weights_everylearner <- diag(1, 3)
colnames(weights_everylearner) <- c("mdl:ols", "mdl:lasso", "mdl:ridge")
ate_fit <- ddml_ate(y, D, X,
                    learners = list(list(what = ols),
                                    list(what = mdl_glmnet),
                                    list(what = mdl_glmnet,
                                         args = list(alpha = 0))),
                    ensemble_type = 'nnls',
                    custom_ensemble_weights = weights_everylearner,
                    shortstack = TRUE,
                    sample_folds = 2,
                    silent = TRUE)
summary(ate_fit)

Description

Estimator for group-time average treatment effects on the treated (GT-ATT) in staggered Difference-in-Differences designs.

Usage

ddml_attgt(
  y,
  X = NULL,
  t,
  G,
  learners,
  learners_qX = learners,
  sample_folds = 10,
  ensemble_type = "nnls",
  shortstack = FALSE,
  cv_folds = 10,
  custom_ensemble_weights = NULL,
  custom_ensemble_weights_qX = custom_ensemble_weights,
  cluster_variable = seq_len(nrow(as.matrix(y))),
  trim = 0.01,
  control_group = c("notyettreated", "nevertreated"),
  anticipation = 0,
  silent = FALSE,
  parallel = NULL,
  fitted = NULL,
  splits = NULL,
  save_crossval = TRUE,
  ...
)

Arguments

Details

Parameter of Interest: ddml_attgt provides a Double/Debiased Machine Learning estimator for the group-time average treatment effects on the treated (GT-ATT) in the staggered adoption model. For each group $g$ and time period $t$, define the differenced outcome $\Delta_g Y_{i,t} = Y_{i,t} - Y_{i,g^*}$ where $g^*$ is the universal base period. The GT-ATT is:

$\theta_0^{(g,t)} = E[\Delta_g Y_{i,t} | G_i = g] - E[E[\Delta_g Y_{i,t} | X_i, G_i \ne g, G_i > t] | G_i = g]$

where $W_i \equiv (Y_{i,1}, \dots, Y_{i,T}, G_i, X_i)$ is the observed random vector.

Neyman Orthogonal Score: The Neyman orthogonal score is:

$m^{(g,t)}(W_i; \theta, \eta) = \frac{\mathbf{1}\{G_i = g\} (\Delta_g Y_{i,t} - \ell^{(g,t)}(X_i))}{\pi^g} - \frac{q^{(g,t)}(X_i) \mathbf{1}\{G_i \ne g\} \mathbf{1}\{G_i > t\} (\Delta_g Y_{i,t} - \ell^{(g,t)}(X_i))}{\pi^g (1 - q^{(g,t)}(X_i))} - \frac{\mathbf{1}\{G_i = g\}}{\pi^g} \theta$

where the nuisance parameters are $\eta = (\ell, q, \pi)$ taking true values $\ell_0^{(g,t)}(X) = E[\Delta_g Y_{i,t} \mid G_i \ne g, G_i > t, X_i]$, $q_0^{(g,t)}(X) = \Pr(G_i = g \mid X_i, \{G_i = g\} \cup \{G_i > t\})$, and $\pi_0^g = \Pr(G_i = g)$.

Jacobian:

$J^{(g,t)} = -1$

See ddml-intro for how the influence function and inference are derived from these components.

Value

ddml_attgt returns an object of S3 class ddml_attgt and ddml. See ddml-intro for the common output structure. Additional pass-through fields: learners, learners_qX, cell_info, control_group, anticipation.

References

Callaway B, Sant'Anna P H C (2021). "Difference-in-Differences with multiple time periods." Journal of Econometrics, 225(2), 200-230.

Chang N-C (2020). "Double/debiased machine learning for difference-in-differences models." Econometrics Journal, 23(2), 177-191.

Ahrens A, Chernozhukov V, Hansen C B, Kozbur D, Schaffer M E, Wiemann T (2026). "An Introduction to Double/Debiased Machine Learning." Journal of Economic Literature, forthcoming.

See Also

Other ddml estimators: ddml-intro, ddml_apo(), ddml_ate(), ddml_fpliv(), ddml_late(), ddml_pliv(), ddml_plm(), ddml_policy()

Examples

set.seed(42)
n <- 200; T_ <- 4
X <- matrix(rnorm(n * 2), n, 2)
G <- sample(c(3, 4, Inf), n, replace = TRUE,
            prob = c(0.3, 0.3, 0.4))
y <- matrix(rnorm(n * T_), n, T_)
# Add treatment effect for treated units
for (i in seq_len(n)) {
  if (is.finite(G[i])) {
    for (j in seq_len(T_)) {
      if (j >= G[i]) y[i, j] <- y[i, j] + 1
    }
  }
}
fit <- ddml_attgt(y, X, t = 1:T_, G = G,
                learners = list(what = ols),
                sample_folds = 2,
                silent = TRUE)
summary(fit)

Description

Estimator for the flexible partially linear IV coefficient.

Usage

ddml_fpliv(
  y,
  D,
  Z,
  X,
  learners,
  learners_DXZ = learners,
  learners_DX = learners,
  sample_folds = 10,
  ensemble_type = "nnls",
  shortstack = FALSE,
  cv_folds = 10,
  custom_ensemble_weights = NULL,
  custom_ensemble_weights_DXZ = custom_ensemble_weights,
  custom_ensemble_weights_DX = custom_ensemble_weights,
  cluster_variable = seq_along(y),
  silent = FALSE,
  parallel = NULL,
  fitted = NULL,
  splits = NULL,
  save_crossval = TRUE,
  ...
)

Arguments

Details

Parameter of Interest: ddml_fpliv provides a Double/Debiased Machine Learning estimator for the flexible partially linear instrumental variable (IV) coefficient $\theta_0$, defined by the partially linear IV model:

$Y = \theta_0 D + g_0(X) + \varepsilon, \quad E[\varepsilon|X, Z] = 0,$

where $W \equiv (Y, D, X, Z, \varepsilon)$ is a random vector such that $E[Var(E[D|X, Z]|X)] \neq 0$, and $g_0(X)$ is an unknown nuisance function.

Neyman Orthogonal Score: The Neyman orthogonal score is:

$m(W; \theta, \eta) = [(Y - \ell(X)) - \theta(D - r(X))](v(X, Z) - r(X))$

where the nuisance parameters are $\eta = (\ell, r, v)$ taking true values $\ell_0(X) = E[Y|X]$, $r_0(X) = E[D|X]$, and $v_0(X, Z) = E[D|X, Z]$.

Jacobian:

$J = -E[(D - r(X))(v(X, Z) - r(X))^\top]$

See ddml-intro for how the influence function and inference are derived from these components.

Value

ddml_fpliv returns an object of S3 class ddml_fpliv and ddml. See ddml-intro for the common output structure. Additional pass-through fields: learners, learners_DXZ, learners_DX.

See Also

Other ddml estimators: ddml-intro, ddml_apo(), ddml_ate(), ddml_attgt(), ddml_late(), ddml_pliv(), ddml_plm(), ddml_policy()

Examples

# Construct variables from the included Angrist & Evans (1998) data
y = AE98[, "worked"]
D = AE98[, "morekids"]
Z = AE98[, "samesex", drop = FALSE]
X = AE98[, c("age","agefst","black","hisp","othrace","educ")]

# Estimate the partially linear IV model using a single base learner, ridge.
fpliv_fit <- ddml_fpliv(y, D, Z, X,
                        learners = list(what = mdl_glmnet,
                                        args = list(alpha = 0)),
                        sample_folds = 2,
                        silent = TRUE)
summary(fpliv_fit)

Description

Estimator for the local average treatment effect.

Usage

ddml_late(
  y,
  D,
  Z,
  X,
  learners,
  learners_DXZ = learners,
  learners_ZX = learners,
  sample_folds = 10,
  ensemble_type = "nnls",
  shortstack = FALSE,
  cv_folds = 10,
  custom_ensemble_weights = NULL,
  custom_ensemble_weights_DXZ = custom_ensemble_weights,
  custom_ensemble_weights_ZX = custom_ensemble_weights,
  cluster_variable = seq_along(y),
  stratify = TRUE,
  trim = 0.01,
  silent = FALSE,
  parallel = NULL,
  fitted = NULL,
  splits = NULL,
  save_crossval = TRUE,
  ...
)

Arguments

Details

Parameter of Interest: ddml_late provides a Double/Debiased Machine Learning estimator for the local average treatment effect. Under the standard instrumental variable assumptions (conditional independence, exclusion restriction, relevance, and monotonicity) with a binary instrument $Z$ and a binary treatment $D$, the parameter is identified by the following reduced form parameter:

$\theta_0^{\textrm{LATE}} = \frac{E[E[Y|Z=1, X] - E[Y|Z=0, X]]}{E[E[D|Z=1, X] - E[D|Z=0, X]]}$

where $W \equiv (Y, D, X, Z)$ is the observed random vector.

Nuisance Parameters: The nuisance parameters are $\eta = (\ell_0, \ell_1, r_0, r_1, p)$ taking true values $\ell_{z,0}(X) = E[Y|Z=z, X]$, $r_{z,0}(X) = E[D|Z=z, X]$, and $p_0(X) = \Pr(Z=1|X)$.

Neyman Orthogonal Score / Moment Equation: The Neyman orthogonal score is:

$m(W; \theta, \eta) = \frac{Z(Y - \ell_1(X))}{p(X)} - \frac{(1-Z)(Y-\ell_0(X))}{1-p(X)} + \ell_1(X) - \ell_0(X) - \theta\left(\frac{Z(D - r_1(X))}{p(X)} - \frac{(1-Z)(D-r_0(X))}{1-p(X)} + r_1(X) - r_0(X)\right)$

Jacobian:

$J = -E[r_1(X) - r_0(X)]$

See ddml-intro for how the influence function and inference are derived from these components.

Value

ddml_late returns an object of S3 class ddml_late and ddml. See ddml-intro for the common output structure. Additional pass-through fields: learners, learners_DXZ, learners_ZX.

References

Imbens G, Angrist J (1994). "Identification and Estimation of Local Average Treatment Effects." Econometrica, 62(2), 467-475.

See Also

Other ddml estimators: ddml-intro, ddml_apo(), ddml_ate(), ddml_attgt(), ddml_fpliv(), ddml_pliv(), ddml_plm(), ddml_policy()

Examples

# Construct variables from the included Angrist & Evans (1998) data
y = AE98[, "worked"]
D = AE98[, "morekids"]
Z = AE98[, "samesex"]
X = AE98[, c("age","agefst","black","hisp","othrace","educ")]

# Estimate the local average treatment effect using a single base learner,
#     ridge.
late_fit <- ddml_late(y, D, Z, X,
                      learners = list(what = mdl_glmnet,
                                      args = list(alpha = 0)),
                      sample_folds = 2,
                      silent = TRUE)
summary(late_fit)


# Estimate the local average treatment effect using short-stacking with base
#     learners ols, lasso, and ridge. We can also use custom_ensemble_weights
#     to estimate the LATE using every individual base learner.
weights_everylearner <- diag(1, 3)
colnames(weights_everylearner) <- c("mdl:ols", "mdl:lasso", "mdl:ridge")
late_fit <- ddml_late(y, D, Z, X,
                      learners = list(list(what = ols),
                                      list(what = mdl_glmnet),
                                      list(what = mdl_glmnet,
                                           args = list(alpha = 0))),
                      ensemble_type = 'nnls',
                      custom_ensemble_weights = weights_everylearner,
                      shortstack = TRUE,
                      sample_folds = 2,
                      silent = TRUE)
summary(late_fit)

Description

Estimator for the partially linear IV coefficient.

Usage

ddml_pliv(
  y,
  D,
  Z,
  X,
  learners,
  learners_DX = learners,
  learners_ZX = learners,
  sample_folds = 10,
  ensemble_type = "nnls",
  shortstack = FALSE,
  cv_folds = 10,
  custom_ensemble_weights = NULL,
  custom_ensemble_weights_DX = custom_ensemble_weights,
  custom_ensemble_weights_ZX = custom_ensemble_weights,
  cluster_variable = seq_along(y),
  silent = FALSE,
  parallel = NULL,
  fitted = NULL,
  splits = NULL,
  save_crossval = TRUE,
  ...
)

Arguments

Details

Parameter of Interest: ddml_pliv provides a Double/Debiased Machine Learning estimator for the partially linear instrumental variable (IV) coefficient $\theta_0$, defined by the partially linear IV model:

$Y = \theta_0 D + g_0(X) + \varepsilon, \quad E[Z\varepsilon] = 0, \quad E[\varepsilon|X] = 0,$

where $W \equiv (Y, D, X, Z, \varepsilon)$ is a random vector such that $E[Cov(D, Z|X)] \neq 0$, and $g_0(X)$ is an unknown nuisance function.

Neyman Orthogonal Score: The Neyman orthogonal score is:

$m(W; \theta, \eta) = [(Y - \ell(X)) - \theta(D - r_D(X))](Z - r_Z(X))$

where the nuisance parameters are $\eta = (\ell, r_D, r_Z)$ taking true values $\ell_0(X) = E[Y|X]$, $r_{D,0}(X) = E[D|X]$, and $r_{Z,0}(X) = E[Z|X]$.

Jacobian:

$J = -E[(D - r_D(X))(Z - r_Z(X))^\top]$

See ddml-intro for how the influence function and inference are derived from these components.

Value

ddml_pliv returns an object of S3 class ddml_pliv and ddml. See ddml-intro for the common output structure. Additional pass-through fields: learners, learners_DX, learners_ZX.

See Also

Other ddml estimators: ddml-intro, ddml_apo(), ddml_ate(), ddml_attgt(), ddml_fpliv(), ddml_late(), ddml_plm(), ddml_policy()

Examples

# Construct variables from the included Angrist & Evans (1998) data
y = AE98[, "worked"]
D = AE98[, "morekids"]
Z = AE98[, "samesex"]
X = AE98[, c("age","agefst","black","hisp","othrace","educ")]

# Estimate the partially linear IV model using a single base learner, ridge.
pliv_fit <- ddml_pliv(y, D, Z, X,
                      learners = list(what = mdl_glmnet,
                                      args = list(alpha = 0)),
                      sample_folds = 2,
                      silent = TRUE)
summary(pliv_fit)

Description

Estimator for the partially linear regression coefficient.

Usage

ddml_plm(
  y,
  D,
  X,
  learners,
  learners_DX = learners,
  sample_folds = 10,
  ensemble_type = "nnls",
  shortstack = FALSE,
  cv_folds = 10,
  custom_ensemble_weights = NULL,
  custom_ensemble_weights_DX = custom_ensemble_weights,
  cluster_variable = seq_along(y),
  silent = FALSE,
  parallel = NULL,
  fitted = NULL,
  splits = NULL,
  save_crossval = TRUE,
  ...
)

Arguments

Details

Parameter of Interest: ddml_plm provides a Double/Debiased Machine Learning estimator for the partially linear regression coefficient $\theta_0$, defined by the partially linear regression model:

$Y = \theta_0 D + g_0(X) + \varepsilon, \quad E[D\varepsilon] = 0, \quad E[\varepsilon|X] = 0,$

where $W\equiv(Y, D, X, \varepsilon)$ is a random vector such that $E[Var(D|X)] \neq 0$, and $g_0(X)$ is an unknown nuisance function.

Neyman Orthogonal Score: The Neyman orthogonal score is:

$m(W; \theta, \eta) = [(Y - \ell(X)) - \theta(D - r(X))](D - r(X))$

where the nuisance parameters are $\eta = (\ell, r)$ taking true values $\ell_0(X) = E[Y|X]$ and $r_0(X) = E[D|X]$.

Jacobian:

$J = -E[(D - r_0(X))(D - r_0(X))^\top]$

See ddml-intro for how the influence function and inference are derived from these components.

Value

ddml_plm returns an object of S3 class ddml_plm and ddml. See ddml-intro for the common output structure. Additional pass-through fields: learners, learners_DX.

See Also

Other ddml estimators: ddml-intro, ddml_apo(), ddml_ate(), ddml_attgt(), ddml_fpliv(), ddml_late(), ddml_pliv(), ddml_policy()

Examples

# Construct variables from the included Angrist & Evans (1998) data
y = AE98[, "worked"]
D = AE98[, "morekids"]
X = AE98[, c("age","agefst","black","hisp","othrace","educ")]

# Estimate the partially linear model using a single base learner, ridge.
plm_fit <- ddml_plm(y, D, X,
                    learners = list(what = mdl_glmnet,
                                    args = list(alpha = 0)),
                    sample_folds = 2,
                    silent = TRUE)
summary(plm_fit)

# Estimate the partially linear model using short-stacking with base learners
#     ols, lasso, and ridge. We can also use custom_ensemble_weights
#     to estimate the ATE using every individual base learner.
weights_everylearner <- diag(1, 3)
colnames(weights_everylearner) <- c("mdl:ols", "mdl:lasso", "mdl:ridge")
plm_fit <- ddml_plm(y, D, X,
                    learners = list(list(what = ols),
                                    list(what = mdl_glmnet),
                                    list(what = mdl_glmnet,
                                         args = list(alpha = 0))),
                    ensemble_type = 'nnls',
                    custom_ensemble_weights = weights_everylearner,
                    shortstack = TRUE,
                    sample_folds = 2,
                    silent = TRUE)
summary(plm_fit)


# Re-estimate with a different ensemble type using pass-through
#     (skips cross-fitting, only recomputes ensemble weights).
plm_fit2 <- ddml_plm(y, D, X,
                     learners = list(list(what = ols),
                                     list(what = mdl_glmnet),
                                     list(what = mdl_glmnet,
                                          args = list(alpha = 0))),
                     ensemble_type = 'average',
                     shortstack = TRUE,
                     sample_folds = 2,
                     silent = TRUE,
                     fitted = plm_fit$fitted,
                     splits = plm_fit$splits)
summary(plm_fit2)

Description

Estimator for the expected value of a multi-action policy, with optional per-level margins.

Usage

ddml_policy(
  y,
  D,
  X,
  policy,
  margins = NULL,
  learners,
  learners_DX = learners,
  sample_folds = 10,
  ensemble_type = "nnls",
  shortstack = FALSE,
  cv_folds = 10,
  custom_ensemble_weights = NULL,
  custom_ensemble_weights_DX = custom_ensemble_weights,
  cluster_variable = seq_along(y),
  stratify = TRUE,
  trim = 0.01,
  silent = FALSE,
  parallel = NULL,
  fitted = NULL,
  splits = NULL,
  save_crossval = TRUE,
  ...
)

Arguments

Details

Parameter of Interest: ddml_policy provides a Double/Debiased Machine Learning estimator for the expected value of a multi-action policy $\pi:\operatorname{supp}(X) \to \{d_1, \ldots, d_K\}$ that assigns each unit to one of $K$ treatment levels. The target parameter is

$\theta_0 = \sum_{k=1}^{K} E\!\left[\omega_k(X)\, E[Y \mid D = d_k, X]\right],$

where the known weight functions are $\omega_k(X) = c_k \,\mathbf{1}\{\pi(X) = d_k\}$, and $c_1, \ldots, c_K$ are user-supplied margins. When all margins equal one (margins = NULL), the parameter reduces to the policy value $E[Y(\pi(X))]$.