causalis.scenarios.synthetic_control.dgp

Module Contents

Functions

generate_scm_gamma_26

Generate realistic Gamma synthetic-control panel data.

generate_scm_poisson_26

Generate realistic Poisson synthetic-control panel data.

Data

PanelOutput

API

causalis.scenarios.synthetic_control.dgp.PanelOutput

None

causalis.scenarios.synthetic_control.dgp.generate_scm_gamma_26(seed: int = 42, return_panel_data: bool = True, include_oracles: bool = False, n_donors: int = 40, n_pre_periods: Optional[int] = 36, n_post_periods: Optional[int] = 6, treatment_effect_rate: float = 0.1, treatment_effect_slope: float = 0.002, **advanced_params) → causalis.scenarios.synthetic_control.dgp.PanelOutput

Generate realistic Gamma synthetic-control panel data.

Parameters

seed : int, default=42 Random seed. return_panel_data : bool, default=True If True, return a :class:~causalis.data_contracts.panel_data_scm.PanelDataSCM object. If False, return a pandas DataFrame. include_oracles : bool, default=False Whether to include oracle truth columns in the returned data: is_treated_unit, y_cf, tau_realized_true, mu_cf, mu_treated, tau_mean_true. Scenario-level outputs always exclude synthetic covariates exposure, macro_index, seasonality_index. n_donors : int, default=40 Number of donor units. n_pre_periods : int or None, default=36 Number of pre-treatment periods. Preferred explicit horizon control. When both n_pre_periods and n_post_periods are omitted, scenario defaults are used (36 pre, 6 post). The generated panel includes one explicit intervention-anchor period, so each unit has n_pre_periods + 1 + n_post_periods rows. n_post_periods : int or None, default=6 Number of post-treatment periods. Must be provided together with n_pre_periods when using explicit horizon control. treatment_effect_rate : float, default=0.10 Long-run post-treatment relative effect scale. The first post period is attenuated by a ramp factor 1 - exp(-1 / 2.5) (about 0.33x when slope is zero). treatment_effect_slope : float, default=0.002 Linear slope of the post-treatment relative effect path. **advanced_params Forwarded to :func:causalis.dgp.panel_data_scm.generate_scm_gamma_data. Common advanced knobs include time_start, calendar_start, and latent-factor configuration. Defaults used by this wrapper are gamma_shape=120, donor_noise_std_log=0.03, common_factor_std_log=0.03, latent_factor_std_log=0.0, and prefit_mismatch_std_log=0.0.

Returns

pandas.DataFrame or PanelDataSCM Long panel data for SCM experiments.

Notes

DGP Math: The data follows a hierarchical log-linear model for the mean: math:\mu. For each donor unit :math:j at time :math:t, the mean is :math:\mu_{tj} = E_{tj} \cdot \exp(\eta_{tj}) where :math:E_{tj} is exposure (with growth and noise) and :math:\eta_{tj} includes seasonality, common factors (macro index), latent factors, and unit-specific noise. Outcomes are sampled as :math:y_{tj} \sim \text{Gamma}(k, \mu_{tj}/k), where :math:k is gamma_shape.

The treated unit’s counterfactual mean :math:\mu_{t, cf} is a weighted combination of donors (via Dirichlet weights) with a potential pre-fit mismatch. The realized treated outcome is :math:y_{t, treated} = y_{t, cf} \cdot (1 + \tau_t^{rate}), where :math:\tau_t^{rate} is the relative treatment effect.

Time-axis semantics:

  • n_pre_periods: number of periods strictly before the intervention anchor.

  • One explicit intervention-anchor period is included in the output.

  • n_post_periods: number of periods strictly after the intervention anchor.

  • time_start: offset for the first calendar_time period relative to calendar_start (default calendar_start="2000-01" and time_start=1).

  • treated_time: explicit 0/1 treatment-assignment indicator in returned data (1 only for treated-unit rows at/after the first treated period; 0 otherwise).

  • PanelDataSCM is built with required fields only: df, y, unit_col, time_col, treated_time.

  • When return_panel_data=True, all contract metadata is derived from the final treated_time path. Because this scenario keeps one explicit anchor period in the panel, contract-level pre periods are n_pre_periods + 1 and post periods are n_post_periods.

  • With this function’s default arguments, the explicit values are: n_pre_periods=36, n_post_periods=6, calendar_start='2000-01', time_start=1, first treated period at Period('2003-02', 'M'), and intervention anchor at Period('2003-01', 'M').

causalis.scenarios.synthetic_control.dgp.generate_scm_poisson_26(seed: int = 42, return_panel_data: bool = True, include_oracles: bool = False, n_donors: int = 20, n_pre_periods: Optional[int] = 180, n_post_periods: Optional[int] = 4, treatment_effect_rate: float = 0.15, treatment_effect_slope: float = 0.0005, **advanced_params) → causalis.scenarios.synthetic_control.dgp.PanelOutput

Generate realistic Poisson synthetic-control panel data.

Parameters

seed : int, default=42 Random seed. return_panel_data : bool, default=True If True, return a :class:~causalis.data_contracts.panel_data_scm.PanelDataSCM object. If False, return a pandas DataFrame. include_oracles : bool, default=False Whether to include oracle truth columns in the returned data: is_treated_unit, y_cf, tau_realized_true, mu_cf, mu_treated, tau_mean_true. Scenario-level outputs always exclude synthetic covariates exposure, macro_index, seasonality_index. n_donors : int, default=20 Number of donor units. n_pre_periods : int or None, default=180 Number of pre-treatment periods. Preferred explicit horizon control. When both n_pre_periods and n_post_periods are omitted, scenario defaults are used (36 pre, 6 post). The generated panel includes one explicit intervention-anchor period, so each unit has n_pre_periods + 1 + n_post_periods rows. n_post_periods : int or None, default=4 Number of post-treatment periods. Must be provided together with n_pre_periods when using explicit horizon control. treatment_effect_rate : float, default=0.15 Long-run post-treatment relative effect scale. The first post period is attenuated by a ramp factor 1 - exp(-1 / 2.5) (about 0.33x when slope is zero). treatment_effect_slope : float, default=0.0005 Linear slope of the post-treatment relative effect path. **advanced_params Forwarded to :func:causalis.dgp.panel_data_scm.generate_scm_poisson_data. Common advanced knobs include time_start, calendar_start, and latent-factor configuration. Defaults used by this wrapper are donor_noise_std_log=0.02, common_factor_std_log=0.02, latent_factor_std_log=0.0, and prefit_mismatch_std_log=0.0.

Returns

pandas.DataFrame or PanelDataSCM Long panel data for SCM experiments.

Notes

DGP Math: The data follows a hierarchical log-linear model for the mean :math:\mu. For each donor unit :math:j at time :math:t, the mean is :math:\mu_{tj} = E_{tj} \cdot \exp(\eta_{tj}) where :math:E_{tj} is exposure and :math:\eta_{tj} includes seasonality, common factors, latent factors, and unit-specific noise. Outcomes are sampled as :math:y_{tj} \sim \text{Poisson}(\mu_{tj}).

The treated unit’s counterfactual mean :math:\mu_{t, cf} is a weighted combination of donors. The realized treated outcome :math:y_{t, treated} is sampled from a Poisson distribution coupled with the counterfactual :math:y_{t, cf} via a thinning/superposition property to maintain exact marginals while ensuring the realized effect is driven by the multiplier.

Time-axis semantics:

  • n_pre_periods: number of periods strictly before the intervention anchor.

  • One explicit intervention-anchor period is included in the output.

  • n_post_periods: number of periods strictly after the intervention anchor.

  • time_start: offset for the first calendar_time period relative to calendar_start (default calendar_start="2000-01" and time_start=1).

  • treated_time: explicit 0/1 treatment-assignment indicator in returned data (1 only for treated-unit rows at/after the first treated period; 0 otherwise).

  • PanelDataSCM is built with required fields only: df, y, unit_col, time_col, treated_time.

  • When return_panel_data=True, all contract metadata is derived from the final treated_time path. Because this scenario keeps one explicit anchor period in the panel, contract-level pre periods are n_pre_periods + 1 and post periods are n_post_periods.

  • With this function’s default arguments, the explicit values are: n_pre_periods=180, n_post_periods=4, calendar_start='2000-01', time_start=1, first treated period at Period('2003-02', 'M'), and intervention anchor at Period('2003-01', 'M').