2.3.1. doubleml.did.DoubleMLDIDMulti#

class doubleml.did.DoubleMLDIDMulti(obj_dml_data, ml_g, ml_m=None, gt_combinations='standard', control_group='never_treated', anticipation_periods=0, n_folds=5, n_rep=1, score='observational', panel=True, in_sample_normalization=True, trimming_rule='truncate', trimming_threshold=0.01, draw_sample_splitting=True, print_periods=False)#

Double machine learning for multi-period difference-in-differences models.

Parameters:

obj_dml_data (DoubleMLPanelData object) – The DoubleMLPanelData object providing the data and specifying the variables for the causal model.
ml_g (estimator implementing fit() and predict()) – A machine learner implementing fit() and predict() methods (e.g. sklearn.ensemble.RandomForestRegressor) for the nuisance function \(g_0(0,X) = E[Y_{t_{\text{eval}}}-Y_{t_{\text{pre}}}|X, C_{t_{ ext{eval}} + \delta} = 1]\). For a binary outcome variable \(Y\) (with values 0 and 1), a classifier implementing fit() and predict_proba() can also be specified.
ml_m (classifier implementing fit() and predict_proba()) – A machine learner implementing fit() and predict_proba() methods (e.g. sklearn.ensemble.RandomForestClassifier) for the nuisance function \(m_0(X) = E[D=1|X]\). Only relevant for score='observational'. Default is None.
gt_combinations (array-like or str) – A list of tuples with the group-time combinations to be evaluated. Can be a string with the value 'standard', 'all' or 'universal', which constructs the corresponding combinations automatically. Default is 'standard'.
control_group (str) – Specifies the control group. Either 'never_treated' or 'not_yet_treated'. Default is 'never_treated'.
anticipation_periods (int) – Number of anticipation periods. Default is 0.
n_folds (int) – Number of folds for cross-fitting. Default is 5.
n_rep (int) – Number of repetitions for the sample splitting. Default is 1.
score (str) – A str ('observational' or 'experimental') specifying the score function. The 'experimental' scores refers to an A/B setting, where the treatment is independent from the pretreatment covariates. Default is 'observational'.
panel (bool) – Indicates whether to rely on panel data structure (True) or repeated cross sections (False). Default is True.
in_sample_normalization (bool) – Indicates whether to use in-sample normalization of weights. Default is True.
trimming_rule (str) – A str ('truncate' is the only choice) specifying the trimming approach. Default is 'truncate'.
trimming_threshold (float) – The threshold used for trimming. Default is 1e-2.
draw_sample_splitting (bool) – Indicates whether the sample splitting should be drawn during initialization. Default is True.
print_periods (bool) – Indicates whether to print information about the evaluated periods. Default is False.

Examples

>>> import numpy as np
>>> import doubleml as dml
>>> from doubleml.did.datasets import make_did_CS2021
>>> from sklearn.ensemble import RandomForestRegressor, RandomForestClassifier
>>> np.random.seed(42)
>>> df = make_did_CS2021(n_obs=500)
>>> dml_data = dml.data.DoubleMLPanelData(
...     df,
...     y_col="y",
...     d_cols="d",
...     id_col="id",
...     t_col="t",
...     x_cols=["Z1", "Z2", "Z3", "Z4"],
...     datetime_unit="M"
... )
>>> ml_g = RandomForestRegressor(n_estimators=100, max_depth=5)
>>> ml_m = RandomForestClassifier(n_estimators=100, max_depth=5)
>>> dml_did_obj = dml.did.DoubleMLDIDMulti(
...     obj_dml_data=dml_data,
...     ml_g=ml_g,
...     ml_m=ml_m,
...     gt_combinations="standard",
...     control_group="never_treated",
... )
>>> print(dml_did_obj.fit())

Methods

`aggregate`([aggregation])	Aggregates treatment effects.
`bootstrap`([method, n_rep_boot])	Multiplier bootstrap for DoubleML models.
`confint`([joint, level])	Confidence intervals for DoubleML models.
`fit`([n_jobs_models, n_jobs_cv, ...])	Estimate DoubleMLDIDMulti models.
`p_adjust`([method])	Multiple testing adjustment for DoubleML models.
`plot_effects`([level, joint, figsize, ...])	Plots coefficient estimates with confidence intervals over time, grouped by first treated period.
`sensitivity_analysis`([cf_y, cf_d, rho, ...])	Performs a sensitivity analysis to account for unobserved confounders.
`sensitivity_benchmark`(benchmarking_set[, ...])	Computes a benchmark for a given set of features.
`sensitivity_plot`([idx_treatment, value, ...])	Contour plot of the sensivity with respect to latent/confounding variables.

Attributes

`all_coef`	Estimates of the causal parameter(s) for the `n_rep` different sample splits after calling `fit()` (shape (`n_gt_atts`, `n_rep`)).
`all_se`	Standard errors of the causal parameter(s) for the `n_rep` different sample splits after calling `fit()` (shape (`n_gt_atts`, `n_rep`)).
`anticipation_periods`	The number of anticipation periods.
`boot_method`	The method to construct the bootstrap replications.
`boot_t_stat`	Bootstrapped t-statistics for the causal parameter(s) after calling `fit()` and `bootstrap()` (shape (`n_rep_boot`, `n_gt_atts`, `n_rep`)).
`coef`	Estimates for the causal parameter(s) after calling `fit()` (shape (`n_gt_atts`,)).
`control_group`	The control group.
`framework`	The corresponding `doubleml.DoubleMLFramework` object.
`g_values`	The values of the treatment variable.
`gt_combinations`	The combinations of g and t values.
`gt_index`	The index of the combinations of g and t values.
`gt_labels`	The evaluated labels of the treatment effects 'ATT(g, t_pre, t_eval)' and the period.
`in_sample_normalization`	Indicates whether the in sample normalization of weights are used.
`modellist`	The list of DoubleMLDIDBinary models.
`n_folds`	Number of folds.
`n_gt_atts`	The number of evaluated combinations of the treatment variable and the period.
`n_rep`	Number of repetitions for the sample splitting.
`n_rep_boot`	The number of bootstrap replications.
`never_treated_value`	The value indicating that a unit was never treated.
`nuisance_loss`	The losses of the nuisance models (root-mean-squared-errors or logloss).
`panel`	Indicates whether to rely on panel data structure (`True`) or repeated cross sections (`False`).
`pval`	p-values for the causal parameter(s) (shape (`n_gt_atts`,)).
`score`	The score function.
`se`	Standard errors for the causal parameter(s) after calling `fit()` (shape (`n_gt_atts`,)).
`sensitivity_elements`	Values of the sensitivity components after calling `fit()`; If available (e.g., PLR, IRM) a dictionary with entries `sigma2`, `nu2`, `psi_sigma2`, `psi_nu2` and `riesz_rep`.
`sensitivity_params`	Values of the sensitivity parameters after calling `sesitivity_analysis()`; If available (e.g., PLR, IRM) a dictionary with entries `theta`, `se`, `ci`, `rv` and `rva`.
`sensitivity_summary`	Returns a summary for the sensitivity analysis after calling `sensitivity_analysis()`.
`summary`	A summary for the estimated causal effect after calling `fit()`.
`t_stat`	t-statistics for the causal parameter(s) after calling `fit()` (shape (`n_gt_atts`,)).
`t_values`	The values of the time periods.
`trimming_rule`	Specifies the used trimming rule.
`trimming_threshold`	Specifies the used trimming threshold.

DoubleMLDIDMulti.aggregate(aggregation='group')#

Aggregates treatment effects.

Parameters:: aggregation (str or dict) – Method to aggregate treatment effects or dictionary with aggregation weights (masked numpy array). Has to one of 'group', 'time', 'eventstudy' or a masked numpy array. Default is 'group'.
Returns:: Aggregated treatment effects framework
Return type:: DoubleMLFramework

DoubleMLDIDMulti.bootstrap(method='normal', n_rep_boot=500)#

Multiplier bootstrap for DoubleML models.

Parameters:

method (str) – A str ('Bayes', 'normal' or 'wild') specifying the multiplier bootstrap method. Default is 'normal'
n_rep_boot (int) – The number of bootstrap replications.

Returns:

self

Return type:

object

DoubleMLDIDMulti.confint(joint=False, level=0.95)#

Confidence intervals for DoubleML models.

Parameters:

joint (bool) – Indicates whether joint confidence intervals are computed. Default is False
level (float) – The confidence level. Default is 0.95.

Returns:

df_ci – A data frame with the confidence interval(s).

Return type:

pd.DataFrame

DoubleMLDIDMulti.fit(n_jobs_models=None, n_jobs_cv=None, store_predictions=True, store_models=False, external_predictions=None)#

Estimate DoubleMLDIDMulti models.

Parameters:

n_jobs_models (None or int) – The number of CPUs to use to fit the group-time ATTs. None means 1. Default is None.
n_jobs_cv (None or int) – The number of CPUs to use to fit the learners. None means 1. Does not speed up computation for quantile models. Default is None.
store_predictions (bool) – Indicates whether the predictions for the nuisance functions should be stored in predictions. Default is True.
store_models (bool) – Indicates whether the fitted models for the nuisance functions should be stored in models. This allows to analyze the fitted models or extract information like variable importance. Default is False.
external_predictions (dict or None) – A nested dictionary where the keys correspond the the treatment levels and can contain predictions according to each treatment level. The values have to be dictionaries which can contain keys 'ml_g0', 'ml_g1' and 'ml_m'. Default is None.

Returns:

self

Return type:

object

DoubleMLDIDMulti.p_adjust(method='romano-wolf')#

Multiple testing adjustment for DoubleML models.

Parameters:: method (str) – A str ('romano-wolf'', 'bonferroni', 'holm', etc) specifying the adjustment method. In addition to 'romano-wolf'', all methods implemented in statsmodels.stats.multitest.multipletests() can be applied. Default is 'romano-wolf'.
Returns:: p_val – A data frame with adjusted p-values.
Return type:: pd.DataFrame

DoubleMLDIDMulti.plot_effects(level=0.95, joint=True, figsize=(12, 8), color_palette='colorblind', date_format=None, y_label='Effect', title='Estimated ATTs by Group', jitter_value=None, default_jitter=0.1)#

Plots coefficient estimates with confidence intervals over time, grouped by first treated period.

Parameters:

level (float) – The confidence level for the intervals. Default is 0.95.
joint (bool) – Indicates whether joint confidence intervals are computed. Default is True.
figsize (tuple) – Figure size as (width, height). Default is (12, 8).
color_palette (str) – Name of seaborn color palette to use for distinguishing pre and post treatment effects. Default is "colorblind".
date_format (str) – Format string for date ticks if x-axis contains datetime values. Default is None.
y_label (str) – Label for y-axis. Default is "Effect".
title (str) – Title for the entire plot. Default is "Estimated ATTs by Group".
jitter_value (float) – Amount of jitter to apply to points. Default is None.
default_jitter (float) – Default amount of jitter to apply to points. Default is 0.1.

Returns:

fig (matplotlib.figure.Figure) – The created figure object
axes (list) – List of matplotlib axis objects for further customization

Notes

If joint=True and bootstrapping hasn’t been performed, this method will automatically perform bootstrapping with default parameters and issue a warning.

DoubleMLDIDMulti.sensitivity_analysis(cf_y=0.03, cf_d=0.03, rho=1.0, level=0.95, null_hypothesis=0.0)#

Performs a sensitivity analysis to account for unobserved confounders. The evaluated scenario is stored as a dictionary in the property sensitivity_params.

Parameters:

cf_y (float) – Percentage of the residual variation of the outcome explained by latent/confounding variables. Default is 0.03.
cf_d (float) – Percentage gains in the variation of the Riesz representer generated by latent/confounding variables. Default is 0.03.
rho (float) – The correlation between the differences in short and long representations in the main regression and Riesz representer. Has to be in [-1,1]. The absolute value determines the adversarial strength of the confounding (maximizes at 1.0). Default is 1.0.
level (float) – The confidence level. Default is 0.95.
null_hypothesis (float or numpy.ndarray) – Null hypothesis for the effect. Determines the robustness values. If it is a single float uses the same null hypothesis for all estimated parameters. Else the array has to be of shape (n_coefs,). Default is 0.0.

Returns:

self

Return type:

object

DoubleMLDIDMulti.sensitivity_benchmark(benchmarking_set, fit_args=None)#

Computes a benchmark for a given set of features. Returns a DataFrame containing the corresponding values for cf_y, cf_d, rho and the change in estimates.

Returns:: benchmark_results – Benchmark results.
Return type:: pandas.DataFrame

DoubleMLDIDMulti.sensitivity_plot(idx_treatment=0, value='theta', rho=1.0, level=0.95, null_hypothesis=0.0, include_scenario=True, benchmarks=None, fill=True, grid_bounds=(0.15, 0.15), grid_size=100)#

Contour plot of the sensivity with respect to latent/confounding variables.

Parameters:

idx_gt_atte (int) – Index of the treatment to perform the sensitivity analysis. Default is 0.
value (str) – Determines which contours to plot. Valid values are 'theta' (refers to the bounds) and 'ci' (refers to the bounds including statistical uncertainty). Default is 'theta'.
rho (float) – The correlation between the differences in short and long representations in the main regression and Riesz representer. Has to be in [-1,1]. The absolute value determines the adversarial strength of the confounding (maximizes at 1.0). Default is 1.0.
level (float) – The confidence level. Default is 0.95.
null_hypothesis (float) – Null hypothesis for the effect. Determines the direction of the contour lines.
include_scenario (bool) – Indicates whether to highlight the scenario from the call of sensitivity_analysis(). Default is True.
benchmarks (dict or None) – Dictionary of benchmarks to be included in the plot. The keys are cf_y, cf_d and name. Default is None.
fill (bool) – Indicates whether to use a heatmap style or only contour lines. Default is True.
grid_bounds (tuple) – Determines the evaluation bounds of the grid for cf_d and cf_y. Has to contain two floats in [0, 1). Default is (0.15, 0.15).
grid_size (int) – Determines the number of evaluation points of the grid. Default is 100.

Returns:

fig – Plotly figure of the sensitivity contours.

Return type:

object