Package 'xtdml'

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

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)

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

Methods

Public methods

• xtdml$new()

• xtdml$print()

• xtdml$fit()

• xtdml$split_samples()

• xtdml$tune()

• xtdml$summary()

• xtdml$plot()

• xtdml$predict()

• xtdml$confint()

• xtdml$learner_names()

• xtdml$params_names()

• xtdml$set_ml_nuisance_params()

• xtdml$get_params()

• xtdml$get_panel_info()

• xtdml$clone()

Method new()

xtdml is an abstract class that can't be initialized.

Usage

xtdml$new()

Method print()

Prints xtdml objects.

Usage

xtdml$print()

Method fit()

Estimates model.

Usage

xtdml$fit(store_predictions = FALSE, store_models = FALSE)

Arguments

Returns

self

Method split_samples()

Draws sample splitting for DML procedure.

The samples are drawn according to the attributes n_folds, n_rep and apply_cross_fitting.

Usage

xtdml$split_samples()

Returns

self

Method tune()

Conducts hyperparameter tuning.

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

Returns

self

Method summary()

Summary for estimated model after calling fit().

Usage

xtdml$summary(digits = max(3L, getOption("digits") - 3L))

Arguments

Method plot()

Plots nuisance-function diagnostics after calling fit(store_predictions = TRUE).

Produces a 2x2 panel with the following diagnostic plots for each nuisance parameter:

• fitted vs residual(top-right)

• fitted vs target (top-left)

• fitted vs target (bottom-left)

• Q-Q plot of residuals

For score "orth-PO", the nuisance parameters are l and m. For score "orth-IV", the nuisance parameters are g and m.

Usage

xtdml$plot(i_rep = 1L, i_treat = 1L, ask = interactive(), title = NULL, ...)

Arguments

Returns

Invisibly returns NULL.

Method predict()

Computes predicted outcomes for specified values of the treatment variable.

Usage

xtdml$predict(d)

Arguments

Returns

An array() of predicted outcomes with dimensions ⁠(n_obs, n_d, n_rep, n_treat)⁠, where n_d is the number of treatment-value specifications.

Method confint()

Confidence intervals for estimated model.

Usage

xtdml$confint(parm, joint = FALSE, level = 0.95)

Arguments

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

Sets hyperparameters for the nuisance models of estimated model.

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

Returns

self

Method get_params()

Gets hyper-parameters for the nuisance model.

Usage

xtdml$get_params(learner)

Arguments

Returns

named list()with paramers for the nuisance model/learner.

Method get_panel_info()

Gets panel information for estimation models.

Usage

xtdml$get_panel_info()

Returns

named list()with panel information for the model.

Method clone()

The objects of this class are cloneable with this method.

Usage

xtdml$clone(deep = FALSE)

Arguments

See Also

Other xtdml: xtdml_plr

Description

Data-backed environment for Double machine learning (DML) that cannot be initialized. xtdml_data sets up the data environment for panel data analysis with transformed variables. The xtdml_data_from_data_frame() function can be used to create a new instance of xtdml_data from a data.frame.

Active bindings

Methods

Public methods

• xtdml_data$new()

• xtdml_data$print()

• xtdml_data$plot()

• xtdml_data$set_data_model()

• xtdml_data$clone()

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

Method print()

Print xtdml_data objects.

Usage

xtdml_data$print()

Method plot()

Plotting method, which is not implemented for xtdml objects.

Attempting to call it returns an informative message. Use the print() method to view xtdml_data objects.

Usage

xtdml_data$plot()

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

Method clone()

The objects of this class are cloneable with this method.

Usage

xtdml_data$clone(deep = FALSE)

Arguments

Description

Wrapper for data-backed initialization 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

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

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}$.

Super class

xtdml::xtdml -> xtdml_plr

Methods

Public methods

• xtdml_plr$new()

• xtdml_plr$set_ml_nuisance_params()

• xtdml_plr$tune()

• xtdml_plr$clone()

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

Method set_ml_nuisance_params()

Sets hyperparameters for the nuisance models.

Usage

xtdml_plr$set_ml_nuisance_params(
  learner = NULL,
  treat_var = NULL,
  params,
  set_fold_specific = FALSE
)

Arguments

Returns

self

Method tune()

Conducts hyperparameter-tuning.

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 = 5),
  tune_on_folds = FALSE
)

Arguments

Returns

self

Method clone()

The objects of this class are cloneable with this method.

Usage

xtdml_plr$clone(deep = FALSE)

Arguments

See Also

Other xtdml: xtdml

Examples

# An illustrative example using a regression tree (`rpart`)
library(mlr3)
library(rpart)
library(mlr3tuning)
set.seed(1234)

# Generate simulated dataset
data = make_plpr_data(n_obs = 100, t_per = 5, dim_x = 10, theta = 0.5, rho=0.8)

x_cols  = paste0("X", 1:10)

# Set up DML data environment
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",
                approach = "fd-exact")

# 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)
# Set up a list of parameter grids
param_grid = list("ml_l" = ps(cp = p_dbl(lower = 0.01, upper = 0.02),
                            maxdepth = p_int(lower = 2, upper = 10)),
                  "ml_m" = ps(cp = p_dbl(lower = 0.01, upper = 0.02),
                            maxdepth = p_int(lower = 2, upper = 10)))

tune_settings = list(n_folds_tune = 3,
                   rsmp_tune = mlr3::rsmp("cv", folds = 3),
                   terminator = mlr3tuning::trm("evals", n_evals = 5),
                   tuner = tnr("grid_search", resolution = 10))

obj_xtdml$tune(param_set = param_grid, tune_settings = tune_settings)
obj_xtdml$fit()