# `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’]