causalis.scenarios.did.dgp

Module Contents

Functions

generate_did_gamma_26

Generate a staggered-adoption Gamma DID panel for CSA estimators.

Data

PanelOutput
generate_staggered_did_gamma_26
__all__

API

causalis.scenarios.did.dgp.PanelOutput

None

causalis.scenarios.did.dgp.generate_did_gamma_26(*, seed: int = 42, return_panel_data: bool = True, include_oracles: bool = True, n_treated_units: int = 200, n_control_units: int = 600, n_pre_periods: Optional[int] = None, n_post_periods: Optional[int] = None, n_cohorts: int = _DEFAULT_N_COHORTS, treatment_effect_rate: float = 0.08, treatment_effect_slope: float = 0.0, treatment_effect_heterogeneity_std: float = 0.025, parallel_trend_violation: float = 0.0, calendar_start: str = '2021-01', time_freq: str = 'M', treated_prefix: str = 'treated_market_', control_prefix: str = 'control_market_', **advanced_params) → causalis.scenarios.did.dgp.PanelOutput

Generate a staggered-adoption Gamma DID panel for CSA estimators.

The returned panel is long-format with absorbing treatment, multiple first-treatment cohorts, never-treated controls, baseline-compatible covariates, contextual time indices, cluster labels, and optional oracle counterfactual/effect columns. It is intended to be consumed directly by :class:causalis.scenarios.did.model.CallawaySantAnnaDID.

Parameters

seed : int, default 42 Random seed for reproducibility. return_panel_data : bool, default True If True, returns a :class:PanelDataDID contract; if False, returns a raw :class:pd.DataFrame. include_oracles : bool, default True Whether to include ground-truth columns (e.g., y_cf, tau_mean_true). n_treated_units : int, default 20 Number of units that will eventually receive treatment. n_control_units : int, default 60 Number of never-treated units. n_pre_periods : int, optional Number of periods before any treatment starts. Defaults to 24. n_post_periods : int, optional Number of periods after the first treatment cohort starts. Defaults to 8. n_cohorts : int, default 4 Number of distinct treatment-start times (cohorts) among treated units. treatment_effect_rate : float, default 0.08 Base treatment effect as a fraction of the counterfactual outcome. treatment_effect_slope : float, default 0.0 The rate at which the treatment effect grows or decays per period after start. treatment_effect_heterogeneity_std : float, default 0.025 Standard deviation of unit-level treatment effect multipliers. parallel_trend_violation : float, default 0.0 Strength of a differential trend between treated and control units (0 = parallel). calendar_start : str, default “2021-01” The starting period string for the pandas index. time_freq : str, default “M” The pandas frequency alias (e.g., “M”, “W”, “D”). treated_prefix : str, default “treated_market_” Prefix for treated unit IDs. control_prefix : str, default “control_market_” Prefix for control unit IDs. **advanced_params : dict Reserved for future parameters.

Returns

PanelDataDID or pd.DataFrame The generated panel dataset.

Examples

from causalis.scenarios.did.dgp import generate_did_gamma_26

Generate default panel data

data = generate_did_gamma_26(n_treated_units=10, n_control_units=30, seed=123) type(data) <class ‘causalis.data_contracts.panel_data_did.PanelDataDID’>

Access the underlying dataframe

df = data.df df[[‘unit_id’, ‘calendar_time’, ‘y’, ‘treated_time’]].head() … # doctest: +SKIP

Notes

The DGP simulates a complex business environment where the outcome :math:Y_{it} (e.g., revenue) follows a Gamma distribution:

.. math::

Y_{it} \sim \text{Gamma}\left( \text{shape}=\kappa, \text{scale}=\frac{\mu_{it}}{\kappa} \right)

The mean :math:\mu_{it} is decomposed into a counterfactual :math:\mu_{it}(0) and a treatment effect :math:\tau_{it}:

.. math::

\mu_{it}(1) = \mu_{it}(0) \cdot (1 + \tau_{it})

The counterfactual mean :math:\mu_{it}(0) is modeled as a product of market traffic, conversion rate, and average order value (AOV), each subject to macro-economic cycles, seasonality, and unit-level trends:

.. math::

\ln \mu_{it}(0) = \ln(\text{Exposure}_{it}) + \ln(\text{ConvRate}_{it}) + \ln(\text{AOV}_{it})

where each component follows an AR(1) process with latent confounding. The generated dataframe keeps macro_index and seasonality_index as contextual time indices, but the returned :class:PanelDataDID contract uses only unit-varying covariates for DID adjustment. The treatment effect :math:\tau_{it} for a unit :math:i treated at time :math:G_i is:

.. math::

\tau_{it} = (\theta_{rate} + \theta_{slope} \cdot (t - G_i)) \cdot \text{Ramp}(t - G_i) \cdot \eta_i

where :math:\text{Ramp}(\cdot) is an exponential adoption curve and :math:\eta_i is unit-level heterogeneity. Parallel trend violations are introduced by adding a differential linear trend to treated units’ counterfactuals.

causalis.scenarios.did.dgp.generate_staggered_did_gamma_26

None

causalis.scenarios.did.dgp.__all__

[‘generate_did_gamma_26’, ‘generate_staggered_did_gamma_26’]