causalis.scenarios.cuped.dgp

Data Generating Processes (DGPs) for the CUPED scenario.

This module provides pre-configured synthetic datasets for testing CUPED and other regression-adjusted estimators. It includes complex, skewed outcomes (Tweedie) and binary outcomes, both featuring pre-treatment covariates calibrated to specific target correlations.

Module Contents

Functions

generate_cuped_tweedie_26	Gold standard Tweedie-like DGP with mixed marginals and structured HTE.
make_cuped_binary_26	Binary CUPED benchmark with richer confounders and structured HTE.

API

causalis.scenarios.cuped.dgp.generate_cuped_tweedie_26(n: int = 20000, seed: int = 42, add_pre: bool = True, pre_name: str = 'y_pre', pre_name_2: Optional[str] = None, pre_target_corr: float = 0.82, pre_target_corr_2: Optional[float] = None, pre_spec: Optional[causalis.dgp.causaldata.preperiod.PreCorrSpec] = None, include_oracle: bool = False, return_causal_data: bool = True, theta_log: float = 0.38) → Union[pandas.DataFrame, causalis.dgp.causaldata.CausalData]

Gold standard Tweedie-like DGP with mixed marginals and structured HTE.

This DGP generates a dataset representing a typical e-commerce scenario with many zeros and a heavy right tail (e.g., revenue). It features pre-treatment covariates (‘y_pre’, ‘y_pre_2’) that are calibrated to have a specific correlation with the post-treatment outcome.

Notes

The outcome $Y$ follows a Tweedie-like distribution where the mean is a function of treatment $D$ and latent factors $A$ and $X$:

.. math::

E[Y | D, A, X] = \exp(\alpha + \theta D + \beta X + \gamma D X + A)

The pre-period covariate $X_{pre}$ (e.g., y_pre) is generated to satisfy:

.. math::

Corr(X_{pre}, Y | D=0) \approx \rho

where $\rho$ is the pre_target_corr. This allows for realistic testing of variance reduction techniques.

Examples

from causalis.scenarios.cuped.dgp import generate_cuped_tweedie_26

Generate data with two pre-period covariates

data = generate_cuped_tweedie_26(n=1000, seed=42, return_causal_data=False) print(data.columns.tolist()) [‘y’, ‘d’, ‘tenure_months’, ‘avg_sessions_week’, ‘spend_last_month’, ‘discount_rate’, ‘platform_ios’, ‘platform_web’, ‘y_pre’, ‘y_pre_2’]

Parameters

n : int, default=10000 Number of samples to generate. seed : int, default=42 Random seed. add_pre : bool, default=True Whether to add pre-period covariates. pre_name : str, default=”y_pre” Name of the first pre-period covariate column. pre_name_2 : str, optional Name of the second pre-period covariate column. Defaults to f"{pre_name}_2". pre_target_corr : float, default=0.82 Target correlation between the first pre covariate and post-outcome y in control group. pre_target_corr_2 : float, optional Target correlation for the second pre covariate. Defaults to a moderate value based on pre_target_corr to reduce collinearity. pre_spec : PreCorrSpec, optional Detailed specification for pre-period calibration (transform, method, etc.). include_oracle : bool, default=False Whether to include oracle ground-truth columns like ‘cate’, ‘propensity’, etc. return_causal_data : bool, default=True Whether to return a CausalData object. theta_log : float, default=0.38 The log-uplift theta parameter for the treatment effect.

Returns

pd.DataFrame or CausalData

causalis.scenarios.cuped.dgp.make_cuped_binary_26(n: int = 10000, seed: int = 42, add_pre: bool = True, pre_name: str = 'y_pre', pre_target_corr: float = 0.65, pre_spec: Optional[causalis.dgp.causaldata.preperiod.PreCorrSpec] = None, include_oracle: bool = True, return_causal_data: bool = True, theta_logit: float = 0.38) → Union[pandas.DataFrame, causalis.dgp.causaldata.CausalData]

Binary CUPED benchmark with richer confounders and structured HTE.

This DGP generates a binary outcome (e.g., conversion) with a calibrated pre-period covariate.

Notes

The outcome $Y$ is binary and follows:

.. math::

P(Y=1 | D, X) = \text{logit}^{-1}(\alpha + \theta D + \beta X)

The pre-period covariate is calibrated such that its correlation with $Y$ in the control group matches pre_target_corr.

Examples

from causalis.scenarios.cuped.dgp import make_cuped_binary_26 data = make_cuped_binary_26(n=1000, seed=42, return_causal_data=False) print(data.columns.tolist()[:7]) [‘y’, ‘d’, ‘tenure_months’, ‘spend_last_month’, ‘discount_rate’, ‘support_tickets’, ‘email_open_rate’]

Parameters

n : int, default=10000 Number of samples to generate. seed : int, default=42 Random seed. add_pre : bool, default=True Whether to add a pre-period covariate ‘y_pre’. pre_name : str, default=”y_pre” Name of the pre-period covariate column. pre_target_corr : float, default=0.65 Target correlation between y_pre and post-outcome y in the control group. pre_spec : PreCorrSpec, optional Detailed specification for pre-period calibration (transform, method, etc.). include_oracle : bool, default=True Whether to include oracle columns like ‘cate’, ‘g0’, and ‘g1’. return_causal_data : bool, default=True Whether to return a CausalData object. theta_logit : float, default=0.38 Baseline log-odds uplift scale for heterogeneous treatment effects.

Returns

pd.DataFrame or CausalData