*! version 30aug2024

help ddml stacking v1.4.4

ddml - Stata package for Double Debiased Machine Learning

ddml implements algorithms for causal inference aided by supervised
machine learning as proposed in
Double/debiased machine learning for treatment and structural parameters
(Econometrics Journal, 2018). Five different models are supported, allowing for
binary or continuous treatment variables and endogeneity, high-dimensional
controls and/or instrumental variables.

Stacking regression is a simple and powerful method for
combining predictions from multiple learners.
pystacked is the recommended way to specify multiple learners in ddml,
and ddml has integrated support for various features provided by pystacked.
This help file provides an overview of how to implement stacking
when estimating using ddml.

Stacking

Stacking regression (Wolpert, 1992)
is a way of combining predictions from multiple base ("level-0") learners
into a final prediction.
A final estimator ("level-1") is used to combine the base predictions.
A common approach is to use the cross-validated (out-of-sample, OOS) predictions
of the base learners to obtain the weights for combining the learners.

Three ways of pairing stacking with DDML are supported:
standard stacking, provided via the pystacked package;
pooled stacking, a variant of standard stacking;
and short-stacking, a version of stacking specific to double-debiased machine learning.

pystacked is the recommended way to specify multiple learners in ddml.
pystacked provides a fast way of estimating all the learners in a single call to one program,
and ddml has integrated support for various features provided by pystacked.
ddml will store the predicted values of the specified base learners as well as the combined ("stacked") predicted values.
It also stores the standard and pooled stacking weights used by pystacked
along with the ddml short-stacking weights.

Important: For these features to be available, pystacked needs to be the only learner for each conditional expectation.
Multiple learners must be specified in the call to pystacked; see the examples below.
pystacked can be provided directly to ddml as one of several learners for a conditional expectation,
but in this case the extra features for pystacked will not be availabe.

Note: some of the ddml stacking options available via pystacked integration
are not available for the flexible IV model.
See this help file for examples and discussion
of how to stack and short-stack when using the flexible IV model).

Standard stacking

Standard stacking is implemented via the pystacked package.
This is done by specifying pystacked as the learner for a conditional expectation;
pystacked in turn estimates using the user-specified base learners,
and stacks them to get the stacked (ensemble) prediction.
This is done in the context of ddml's cross-fitting algorithm,
meaning that for k-fold cross-fitting, stacking is done k times,
once for each of the cross-fit folds.

The pystacked base learners are specified at the ddml eq stage,
when the supervised ML learners are added.
This is also where other pystacked options can be specified, e.g.,
the final ("level-1") estimator used to combined the predictions.
The pystacked default final predictor for stacking
regession is non-negative least squares (NNLS) without an intercept
and with the constraint that weights sum to one.
See pystacked for alternative final estimators.

Pooled stacking

Pooled stacking is a variant of standard stacking that implements additional regularization
via the cross-fitting step of ddml.
Pooled stacking is done once, after all cross-fitting has been done
and a full set of all cross-validated OOS predictions has been obtained.
This means that a single set of stacking weights is used to obtain all OOS cross-fit predictions.
This is in contrast to standard stacking and k-fold cross-fitting,
where k different sets of stacking weights are estimated and used to obtain the k OOS cross-fit predictions.
Pooled stacking is specified at the ddml crossfit stage using the poolstack option.
Pooled stacking is available only in conjunction with standard stacking.
The default final estimator is the same as with pystacked,
and can be changed using the psfinalest(estimator) option.

Note: all final estimators available with pystacked are also available for pooled stacking.
However, the current version of pystacked generates the necessary cross-validated OOS predicted values
only if the standard stacking final estimator used by pystacked
is either nnls1 (the default), ls1, ols, ridge or singlebest.
Hence when using pooled stacking,
the standard stacking final estimator specified with pystacked needs to be one of these.

Short-stacking

Short-stacking is a form of stacking specific to double debiased machine learning and cross-fitting.
Short-stacking uses the cross-fitted predicted values to obtain
the stacked (weighted average) of the multiple base learner predictions.
It is computationally faster (often much faster) than
either standard stacking or pooled stacking available via pystacked.
Short-stacking also does not require use of pystacked;
the predictions of any base learners specified by the user can be short-stacked.
Short-stacking is specified at the ddml crossfit stage using the shortstack option.
The default final estimator is the same as with pystacked,
and can be changed using the finalest(estimator) option.

Because short-stacking is typically much faster than standard or pooled stacking,
users may wish to use short-stacking as the only stacking method.
This can be done efficiently in combination with pystacked.
To do this, (1) use pystacked as the single learner in each equation;
(2) at the cross-fitting stage, specify the shortstack and nostdstack options.
This causes pystacked to estimate the base learners
without the computationally-costly stacking step in each cross-fit fold.

Re-stacking after cross-fitting

Users have the option of re-stacking the base learner predictions using a different final estimator
without having to re-cross-fit/re-estimate the entire model.
This is done by specifying the stacking method and final estimator
at the ddml estimate step.
This feature is available only if pystacked is the single learner in every equation.

Stacking weights

The weights used for standard stacking, pooled stacking and short-stacking
can be inspected after estimation using ddml extract
with the show(stweights), show(psweights) and/or show(ssweights), respectively.
In the case of standard stacking, the mean weights across cross-fit folds are displayed;
to display the standard stacking weights for all k folds along with the separate learner MSEs,
use the show(pystacked) option.

Examples

See help ddml init for details of model initialization and learner specification options.

Note: the additional support provided by ddml for pystacked (see above)
is available only if pystacked is the sole learner for each conditional expectation.
Mutliple learners are provided to pystacked, not directly to ddml.