| Type: | Package |
| Title: | Double Machine Learning for Static Panel Models with Fixed Effects |
| Version: | 0.1.8 |
| Date: | 2025-11-06 |
| Maintainer: | Annalivia Polselli <apolselli.econ@gmail.com> |
| Description: | The 'xtdml' package implements partially linear panel regression (PLPR) models with high-dimensional confounding variables and an exogenous treatment variable within the double machine learning framework. The package is used to estimate the structural parameter (treatment effect) in static panel data models with fixed effects using the approaches established in Clarke and Polselli (2025) <doi:10.1093/ectj/utaf011>. 'xtdml' is built on the object-oriented package 'DoubleML' (Bach et al., 2024) <doi:10.18637/jss.v108.i03> using the 'mlr3' ecosystem. |
| License: | GPL-2 | GPL-3 |
| Encoding: | UTF-8 |
| Depends: | R (≥ 3.5.0) |
| Imports: | R6 (≥ 2.4.1), data.table (≥ 1.12.8), mlr3 (≥ 0.19.0), mlr3tuning (≥ 0.20.0), mlr3learners (≥ 0.3.0), mlr3misc (≥ 0.19.0), mvtnorm, utils, clusterGeneration, readstata13, magrittr, dplyr, stats, MLmetrics, checkmate |
| RoxygenNote: | 7.3.2 |
| Suggests: | rpart, mlr3pipelines, bbotk (≥ 1.6.0) |
| NeedsCompilation: | no |
| Packaged: | 2025-11-06 17:23:39 UTC; annal |
| Author: | Annalivia Polselli
|
| Repository: | CRAN |
| Date/Publication: | 2025-11-06 17:40:02 UTC |
Generates data from a partially linear panel regression (PLPR) model
Description
Generates data from a partially linear regression model for panel data with fixed effects similar to DGP3 (highly nonlinear) in Clarke and Polselli (2025).
The data generating process is defined as
Y_{it} = \theta D_{it} + g_0(X_{it}) + \alpha_i + U_{it},
D_{it} = m_0(X_{it}) + \gamma_i + V_{it},
where U_{it} \sim \mathcal{N}(0,1), V_{it} \sim \mathcal{N}(0,1),
\alpha_i = \rho A_i + \sqrt{1-\rho^2} B_i with
A_i\sim \mathcal{N}(3,3), B_i\sim \mathcal{N}(0,1), and \gamma_i\sim \mathcal{N}(0,5).
The covariates are distributed as X_{it,p} \sim A_i + \mathcal{N}(0, 5),
where p is the number of covariates.
The nuisance functions are given by
m_0(X_{it}) = a_1 [X_{it,1} \times 1(X_{it,1}>0)] + a_2 [X_{it,1} \times X_{it,3}],
g_0(X_{it}) = b_1 [X_{it,1} \times X_{it,3}] + b_2 [X_{it,3} \times 1(X_{it,3}>0)],
with a_1=b_2=0.25 and a_2=b_1=0.5.
Usage
make_plpr_data(n_obs = 500, t_per = 10, dim_x = 20, theta = 0.5, rho = 0.8)
Arguments
n_obs |
( |
t_per |
( |
dim_x |
( |
theta |
( |
rho |
( |
Value
A data object.
References
Clarke, P. S. and Polselli, A. (2025). Double Machine Learning for Static Panel Models with Fixed Effects. Econometrics Journal. DOI: 10.1093/ectj/utaf011.
Examples
df = make_plpr_data(n_obs = 500, t_per = 10, dim_x = 20, theta = 0.5, rho=0.8)
Abstract class xtdml
Description
Abstract base class that cannot be initialized.
xtdml estimates the structural parameter (treatment effect)
in partially linear panel regression models with fixed effects
using double machine learning (Clarke and Polselli, 2025).
xtdml allows the estimation of the nuisance functions in the model by machine
learning methods based on the panel data approach chosen by the user,
and computation of the Neyman-orthogonal score functions.
xtdml builds on the object-oriented architecture of DoubleML (Bach et al., 2024), using
the 'mlr3' ecosystem and the 'R6' package. xtdml follows most of the notation of DoubleML.
Format
R6::R6Class object.
Active bindings
all_coef_theta(
matrix())
Estimates of the causal parameter(s)"theta"for then_repdifferent sample splits after callingfit().all_dml1_coef_theta(
array())
Estimates of the causal parameter(s)"theta"for then_repdifferent sample splits after callingfit()withdml_procedure = "dml1".all_se_theta(
matrix())
Standard errors of the causal parameter(s)"theta"for then_repdifferent sample splits after callingfit().all_model_rmse(
matrix())
Model root-mean-squared-error.apply_cross_fitting(
logical(1))
Indicates whether cross-fitting should be applied. Default isTRUE.coef_theta(
numeric())
Estimates for the causal parameter(s)"theta"after callingfit().data(
data.table)
Data object.dml_procedure(
character(1))
Acharacter()("dml1"or"dml2") specifying the double machine learning algorithm. Default is"dml2".draw_sample_splitting(
logical(1))
Indicates whether the sample splitting should be drawn during initialization of the object. Default isTRUE.learner(named
list())
The machine learners for the nuisance functions.n_folds(
integer(1))
Number of folds. Default is5.n_rep(
integer(1))
Number of repetitions for the sample splitting. Default is1.params(named
list())
The hyperparameters of the learners.psi_theta(
array())
Value of the score function\psi(W;\theta_0,\eta_0)=-\psi_a(W;\eta_0) \theta_0 + \psi_b(W;\eta_0)after callingfit().psi_theta_a(
array())
Value of the score function component\psi_a(W;\eta_0)after callingfit().psi_theta_b(
array())
Value of the score function component\psi_b(W;\eta_0)after callingfit().res_y(
array())
Residual of output equationres_d(
array())
Residual of treatment equationpredictions(
array())
Predictions of the nuisance models after callingfit(store_predictions=TRUE).targets(
array())
Targets of the nuisance models after callingfit(store_predictions=TRUE).rmses(
array())
The root-mean-squared-errors of the nuisance parametersall_model_mse(
array())
Collection of all mean-squared-errors of the modelmodel_rmse(
array())
The root-mean-squared-errors of the modelmodels(
array())
The fitted nuisance models after callingfit(store_models=TRUE).pval_theta(
numeric())
p-values for the causal parameter(s)"theta"after callingfit().score(
character(1))
Acharacter(1)specifying the score function among"orth-PO","orth-IV". Default is "orth-PO".se_theta(
numeric())
Standard errors for the causal parameter(s)"theta"after callingfit().smpls(
list())
The partition used for cross-fitting.smpls_cluster(
list())
The partition used for cross-fitting. smpl is at cluster-vart_stat_theta(
numeric())
t-statistics for the causal parameter(s)"theta"after callingfit().tuning_res_theta(named
list())
Results from hyperparameter tuning.
Methods
Public methods
Method new()
DML with FE is an abstract class that can't be initialized.
Usage
xtdml$new()
Method print()
Print 'DML with FE' objects.
Usage
xtdml$print()
Method fit()
Estimate DML models with FE.
Usage
xtdml$fit(store_predictions = FALSE, store_models = FALSE)
Arguments
store_predictions(
logical(1))
Indicates whether the predictions for the nuisance functions should be stored in fieldpredictions. Default isFALSE.store_models(
logical(1))
Indicates whether the fitted models for the nuisance functions should be stored in fieldmodelsif you want to analyze the models or extract information like variable importance. Default isFALSE.
Returns
self
Method split_samples()
Draw sample splitting for Double ML models with FE.
The samples are drawn according to the attributes n_folds, n_rep
and apply_cross_fitting.
Usage
xtdml$split_samples()
Returns
self
Method tune()
Hyperparameter tuning for Double Machine Learning (DML) models with fixed effects.
The hyperparameter tuning is performed using the tuning methods provided in the mlr3tuning package. For more information on tuning in mlr3, see the chapter on hyperparameter optimization in the mlr3 book.
Usage
xtdml$tune(
param_set,
tune_settings = list(n_folds_tune = 5, rsmp_tune = mlr3::rsmp("cv", folds = 5), measure
= NULL, terminator = mlr3tuning::trm("evals", n_evals = 20), tuner =
mlr3tuning::tnr("grid_search", resolution = 10)),
tune_on_folds = FALSE
)Arguments
param_set(named
list())
A namedlistwith a parameter grid for each nuisance model/learner (see methodlearner_names()). Each element must be a ParamSet object.tune_settings(named
list())
A namedlist()of settings controlling the hyperparameter tuning process. Each entry is passed to the corresponding components from mlr3tuning:-
terminator([bbotk::Terminator])
A Terminator object specifying when the tuning process should stop (e.g.,trm("evals", n_evals = 20)). -
tuner— a Tuner object created with tnr(), which defines the optimization algorithm. (e.g.,tnr("grid_search")ortnr("random_search")). If set to"grid_search", then additional argument"resolution"is required. -
rsmp_tune— a Resampling object or a key passed to rsmp(). Defines the resampling strategy used during tuning (default:"cv"). -
n_folds_tune— an integer scalar (optional). Number of folds used ifrsmp_tune = "cv". Default is5. -
measure— a namedlist()(optional). Contains the performance measures used for tuning. Each element must be either a Measure object or a key to msr(). Names must match the learner names (seelearner_names()). If omitted, default measures are used ("regr.rmse"for regression and"classif.ce"for classification).
-
tune_on_folds(
logical(1))
Indicates whether the tuning should be performed separately for each cross-fitting fold (TRUE) or globally across all folds (FALSE, default).
Returns
self
Examples
tune_settings = list(
n_folds_tune = 5,
rsmp_tune = mlr3::rsmp("cv", folds = 5),
terminator = mlr3tuning::trm("evals", n_evals = 20),
tuner = mlr3tuning::tnr("grid_search", resolution = 10))
Method summary()
Summary for DML models with FE after calling fit().
Usage
xtdml$summary(digits = max(3L, getOption("digits") - 3L))Arguments
digits(
integer(1))
The number of significant digits to use when printing.
Method confint()
Confidence intervals for DML models with FE.
Usage
xtdml$confint(parm, joint = FALSE, level = 0.95)
Arguments
parm(
numeric()orcharacter())
A specification of which parameters are to be given confidence intervals among the variables for which inference was done, either a vector of numbers or a vector of names. If missing, all parameters are considered (default).joint(
logical(1))
Indicates whether joint confidence intervals are computed. Default isFALSE.level(
numeric(1))
The confidence level. Default is0.95.
Returns
A matrix() with the confidence interval(s).
Method learner_names()
Returns the names of the learners.
Usage
xtdml$learner_names()
Returns
character() with names of learners.
Method params_names()
Returns the names of the nuisance models with hyperparameters.
Usage
xtdml$params_names()
Returns
character() with names of nuisance models with hyperparameters.
Method set_ml_nuisance_params()
Set hyperparameters for the nuisance models of DML models with FE.
Note that in the current implementation, either all parameters have to be set globally or all parameters have to be provided fold-specific.
Usage
xtdml$set_ml_nuisance_params( learner = NULL, treat_var = NULL, params, set_fold_specific = FALSE )
Arguments
learner(
character(1))
The nuisance model/learner (see methodparams_names).treat_var(
character(1))
The treatment variAble (hyperparameters can be set treatment-variable specific).params(named
list())
A namedlist()with estimator parameters for time-varying covariates. Parameters are used for all folds by default. Alternatively, parameters can be passed in a fold-specific way if optionfold_specificisTRUE. In this case, the outer list needs to be of lengthn_repand the inner list of lengthn_folds_per_cluster.set_fold_specific(
logical(1))
Indicates if the parameters passed inparamsshould be passed in fold-specific way. Default isFALSE. IfTRUE, the outer list needs to be of lengthn_repand the inner list of lengthn_folds_per_cluster. Note that in the current implementation, either all parameters have to be set globally or all parameters have to be provided fold-specific.
Returns
self
Method get_params()
Get hyper-parameters for the nuisance model of xtdml models.
Usage
xtdml$get_params(learner)
Arguments
learner(
character(1))
The nuisance model/learner (see methodparams_names())
Returns
named list()with paramers for the nuisance model/learner.
Method clone()
The objects of this class are cloneable with this method.
Usage
xtdml$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
See Also
Other xtdml:
xtdml_plr
Examples
## ------------------------------------------------
## Method `xtdml$tune`
## ------------------------------------------------
tune_settings = list(
n_folds_tune = 5,
rsmp_tune = mlr3::rsmp("cv", folds = 5),
terminator = mlr3tuning::trm("evals", n_evals = 20),
tuner = mlr3tuning::tnr("grid_search", resolution = 10))
Set up for data for panel data approaches and up two cluster variables
Description
Double machine learning (DML) data-backend for data with cluster variables.
xtdml_data sets up the data environment for panel data analysis with transformed variables.
xtdml_data objects can be initialized from a
data.table. The following functions can be used to create a new
instance of xtdml_data.
-
xtdml_data$new()for initialization from adata.table. -
xtdml_data_from_data_frame()for initialization from adata.frame.
Active bindings
all_variables(
character())
All variables available in the data frame.d_cols(
character())
The treatment variable.dbar_col(
NULL, character()')
The individual mean of the treatment variable.data(
data.table)
Data object.data_model(
data.table)
Internal data object that implements the causal panel model as specified by the user viay_col,d_cols,x_cols,dbar_col.n_obs(
integer(1))
The number of observations.n_treat(
integer(1))
The number of treatment variables.treat_col(
character(1))
"Active" treatment variable in the multiple-treatment case.x_cols(
character())
The covariates.y_col(
character(1))
The outcome variable.panel_id(
character())
The panel identifier.time_id(
character())
The time identifier.cluster_cols(
character())
The cluster variable(s).n_cluster_vars(
integer(1))
The number of cluster variables.approach(
character(1))
Acharacter()("fd-exact","wg-approx"or"cre") specifying the panel data technique to apply to estimate the causal model. Default is"fd-exact".transformX(
character(1))
Acharacter()("no","minmax"or"poly") specifying the type of transformation to apply to the X data."no"does not transform the covariatesXand is recommended for tree-based learners."minmax"applies the Min-Max normalizationx' = (x-x_{min})/(x_{max}-x_{min})to the covariates and is recommended with neural networks."poly"add polynomials up to order three and interactions between all possible combinations of two and three variables; this is recommended for Lasso. Default is"no".
Methods
Public methods
Method new()
Creates a new instance of this R6 class.
Usage
xtdml_data$new( data = NULL, x_cols = NULL, y_col = NULL, d_cols = NULL, dbar_col = NULL, panel_id = NULL, time_id = NULL, cluster_cols = NULL, approach = NULL, transformX = NULL )
Arguments
data(
data.table,data.frame())
Data object.x_cols(
character())y_col(
character(1))
The outcome variable.d_cols(
character(1))
The treatment variable.dbar_col(
NULL, character()) \cr Individual mean of the treatment variable (used for the CRE approach). Default is NULL'.panel_id(
character())
The panel identifier.time_id(
character())
The time identifier.cluster_cols(
character())
The cluster variable(s).approach(
character(1))
Acharacter()("fd-exact","wg-approx"or"cre") specifying the panel data technique to apply to estimate the causal model. Default is"fd-exact".transformX(
character(1))
Acharacter()("no","minmax"or"poly") specifying the type of transformation to apply to the X data."no"does not transform the covariatesXand is recommended for tree-based learners."minmax"applies the Min-Max normalizationx' = (x-x_{min})/(x_{max}-x_{min})to the covariates and is recommended with neural networks."poly"add polynomials up to order three and interactions between all possible combinations of two and three variables; this is recommended for Lasso. Default is"no".
Method print()
Print xtdml_data objects.
Usage
xtdml_data$print()
Method set_data_model()
Setter function for data_model. The function implements the causal model
as specified by the user via y_col, d_cols, x_cols, panel_id, time_id and
cluster_cols and assigns the role for the treatment variables in the
multiple-treatment case.
Usage
xtdml_data$set_data_model(treatment_var)
Arguments
treatment_var(
character())
Active treatment variable that will be set totreat_col.
Method clone()
The objects of this class are cloneable with this method.
Usage
xtdml_data$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Wrapper for Double machine learning data-backend initialization from data.frame.
Description
Initalization of DoubleMLData from data.frame.
Usage
xtdml_data_from_data_frame(
df,
x_cols = NULL,
y_col = NULL,
d_cols = NULL,
panel_id = NULL,
time_id = NULL,
cluster_cols = NULL,
approach = NULL,
transformX = NULL
)
Arguments
df |
( |
x_cols |
( |
y_col |
( |
d_cols |
( |
panel_id |
( |
time_id |
( |
cluster_cols |
( |
approach |
( |
transformX |
( |
Value
Creates a new instance of class xtdml_data.
Examples
# Generate simulated panel dataset from `xtdml`
data = make_plpr_data(n_obs = 500, t_per = 10, dim_x = 30, theta = 0.5, rho=0.8)
# Set up DML data environment
x_cols = paste0("X", 1:30)
obj_xtdml_data = xtdml_data_from_data_frame(data,
x_cols = x_cols, y_col = "y", d_cols = "d",
panel_id = "id",
time_id = "time",
cluster_cols = "id",
approach = "fd-exact",
transformX = "no")
obj_xtdml_data$print()
Routine to estimate partially linear panel regression models with fixed effects within double machine learning.
Description
Routine to estimate partially linear panel regression models with fixed effects within double machine learning.
Format
R6::R6Class object inheriting from xtdml.
Details
Consider partially linear panel regression (PLR) model of form
Y_{it} = \theta_0 D_{it} + g_0(x_{it}) + \alpha_i + U_{it}
D_{it} = m_0(x_{it}) + \gamma_i + V_{it}
where (1) is the outcome equation and (2) is the treatment equation.
Super class
xtdml::xtdml -> xtdml_plr
Methods
Public methods
Inherited methods
Method new()
Creates a new instance of this R6 class.
Usage
xtdml_plr$new( data, ml_l, ml_m, ml_g = NULL, n_folds = 5, n_rep = 1, score = "orth-PO", dml_procedure = "dml2", draw_sample_splitting = TRUE, apply_cross_fitting = TRUE )
Arguments
data(
xtdml_data)
Thextdml_dataobject providing the data and specifying the variables of the causal model.ml_l(
LearnerRegr,Learner,character(1))
A learner of the classLearnerRegr, which is available from mlr3 or its extension packages mlr3learners or mlr3extralearners. Alternatively, aLearnerobject with public fieldtask_type = "regr"can be passed, for example of classGraphLearner. The learner can possibly be passed with specified parameters, for examplelrn("regr.cv_glmnet", s = "lambda.min").
ml_lrefers to the nuisance functionl_0(X) = E[Y|X].ml_m(
LearnerRegr,LearnerClassif,Learner,character(1))
A learner of the classLearnerRegr, which is available from mlr3 or its extension packages mlr3learners or mlr3extralearners. For binary treatment variables, an object of the classLearnerClassifcan be passed, for examplelrn("classif.cv_glmnet", s = "lambda.min"). Alternatively, aLearnerobject with public fieldtask_type = "regr"ortask_type = "classif"can be passed, respectively, for example of classGraphLearner.
ml_mrefers to the nuisance functionm_0(X) = E[D|X].ml_g(
LearnerRegr,Learner,character(1))
A learner of the classLearnerRegr, which is available from mlr3 or its extension packages mlr3learners or mlr3extralearners. Alternatively, aLearnerobject with public fieldtask_type = "regr"can be passed, for example of classGraphLearner. The learner can possibly be passed with specified parameters, for examplelrn("regr.cv_glmnet", s = "lambda.min").
ml_grefers to the nuisance functiong_0(X) = E[Y - D\theta_0|X]. Note: The learnerml_gis only required for the score'IV-type'. Optionally, it can be specified and estimated for callable scores.n_folds(
integer(1))
Number of folds. Default is5.n_rep(
integer(1))
Number of repetitions for the sample splitting. Default is1.score(
character(1))
Acharacter(1)("orth-PO"or"orth-IV")."orth-PO"is Neyman-orthogonal score with the partialling-out formula."orth-IV"is Neyman-orthogonal score with the IV-type formula. Default is"orth-PO".dml_procedure(
character(1))
Acharacter(1)("dml1"or"dml2") specifying the double machine learning algorithm. Default is"dml2".draw_sample_splitting(
logical(1))
Indicates whether the sample splitting should be drawn during initialization of the object. Default isTRUE.apply_cross_fitting(
logical(1))
Indicates whether cross-fitting should be applied. Default isTRUE.
Method set_ml_nuisance_params()
Set hyperparameters for the nuisance models of DML models with FE.
Usage
xtdml_plr$set_ml_nuisance_params( learner = NULL, treat_var = NULL, params, set_fold_specific = FALSE )
Arguments
learner(
character(1))
The nuisance model/learner (see methodparams_names).treat_var(
character(1))
The treatment varaible (hyperparameters can be set treatment-variable specific).params(named
list())
A namedlist()with estimator parameters. Parameters are used for all folds by default. Alternatively, parameters can be passed in a fold-specific way if optionfold_specificisTRUE. In this case, the outer list needs to be of lengthn_repand the inner list of lengthn_folds.set_fold_specific(
logical(1))
Indicates if the parameters passed inparams_thetashould be passed in fold-specific way. Default isFALSE. IfTRUE, the outer list needs to be of lengthn_repand the inner list of lengthn_folds.
Returns
self
Method tune()
Hyperparameter-tuning within double machine learning.
The hyperparameter-tuning is performed using the tuning methods provided in the mlr3tuning package. For more information on tuning in mlr3, we refer to the section on parameter tuning in the mlr3 book.
Usage
xtdml_plr$tune(
param_set,
tune_settings = list(n_folds_tune = 5, rsmp_tune = mlr3::rsmp("cv", folds = 5), measure
= NULL, terminator = mlr3tuning::trm("evals", n_evals = 20), algorithm =
mlr3tuning::tnr("grid_search"), resolution = 10),
tune_on_folds = FALSE
)Arguments
param_set(named
list())
A namedlistwith a parameter grid for each nuisance model/learner (see methodlearner_names()). The parameter grid must be an object of class ParamSet.tune_settings(named
list())
A named list of settings that control the hyperparameter tuning performed via mlr3tuning. These settings are used to construct TuningInstanceSingleCrit objects. The list can contain the following elements:-
terminator([bbotk::Terminator], required)
A Terminator object specifying when the tuning process should stop (e.g.,trm("evals", n_evals = 20)). -
algorithm(Tuner orcharacter(1))
A Tuner object (recommended) or key passed to the respective dictionary to specify the tuning algorithm used in tnr().algorithmis passed as an argument to tnr(). Ifalgorithmis not specified by the users, default is set to"grid_search". If set to"grid_search", then additional argument"resolution"is required. -
rsmp_tune([mlr3::Resampling]orcharacter(1))
A resampling strategy used during tuning. Can be given either as a Resampling object or a key passed to rsmp() (e.g.,"cv"for cross-validation). The default is 5-fold cross-validation. -
n_folds_tune(integer(1))
Number of folds to use whenrsmp_tune = "cv". Default is5. -
measure(NULLor namedlist())
A named list specifying performance measures for each learner. Each element must be either a Measure object or a key passed to msr(). The names of the list elements must match the learner names (seelearner_names()). IfNULL, default measures are used:"regr.mse"for regression and"classif.ce"for classification. -
resolution(character(1))
The key passed to the respective dictionary to specify the tuning algorithm used in tnr().resolutionis passed as an argument to tnr().
-
tune_on_folds(
logical(1))
Indicates whether the tuning should be done fold-specific or globally. Default isFALSE.
Returns
self
Method clone()
The objects of this class are cloneable with this method.
Usage
xtdml_plr$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
See Also
Other xtdml:
xtdml
Examples
# An illustrative example using a regression tree (`rpart`)
library(mlr3)
library(rpart)
# Generate simulated dataset
data = make_plpr_data(n_obs = 500, t_per = 10, dim_x = 30, theta = 0.5, rho=0.8)
x_cols = paste0("X", 1:30)
obj_xtdml_data = xtdml_data_from_data_frame(data,
x_cols = x_cols, y_col = "y", d_cols = "d",
panel_id = "id",
time_id = "time",
cluster_cols = "id",
approach = "fd-exact",
transformX = "no")
# Set up DML estimation environment
learner = lrn("regr.rpart")
ml_l = learner$clone()
ml_m = learner$clone()
obj_xtdml = xtdml_plr$new(obj_xtdml_data,
ml_l = ml_l, ml_m = ml_m,
score = "orth-PO", n_folds = 3)
obj_xtdml$fit()