# `causalis.scenarios.did.model`

## Module Contents

### Classes

`CallawaySantAnnaDID` | Callaway-Sant’Anna staggered-adoption DID estimator.

### Data

`Estimator` |
`AggregateKind` |
`BasePeriod` |
`__all__` |

### API

causalis.scenarios.did.model.Estimator

  None

causalis.scenarios.did.model.AggregateKind

  None

causalis.scenarios.did.model.BasePeriod

  None

class causalis.scenarios.did.model.CallawaySantAnnaDID(*, estimator: causalis.scenarios.did.model.Estimator = 'dr', control_group: causalis.data_contracts.panel_data_did.ComparisonGroup = 'not_yet_or_never', anticipation: int = 0, base_period: causalis.scenarios.did.model.BasePeriod = 'universal', include_pre_periods: bool = False, alpha: float = 0.05, diagnostic_data: bool = True, propensity_clip: float = _DEFAULT_PROPENSITY_CLIP, logit_ridge: float = _DEFAULT_LOGIT_RIDGE, optimizer_tol: float = _DEFAULT_OPTIMIZER_TOL, optimizer_maxiter: int = _DEFAULT_OPTIMIZER_MAXITER, min_treated_per_cell: int = 30, min_control_per_cell: int = 30, min_control_ess: float = 20.0, max_propensity_clip_share: float = 0.05, max_condition_number: float = _DEFAULT_MAX_CONDITION_NUMBER, bootstrap_replications: int = 0, random_state: Optional[int] = None)

  Callaway-Sant’Anna staggered-adoption DID estimator.

  The model estimates group-time average treatment effects :math:`ATT(g,t)` for cohorts (groups) first treated in period :math:`g` and calendar times :math:`t`. Estimation is performed using the doubly robust or inverse-probability weighting methods proposed by Callaway and Sant’Anna (2021).

  Parameters

  estimator : {“dr”, “ipw”}, default “dr” The estimator to use for :math:`ATT(g,t)` cells. - “dr”: Doubly robust AIPW-style estimator. - “ipw”: Inverse probability weighting estimator. control_group : {“not_yet_or_never”, “never_treated”}, default “not_yet_or_never” Which units to use as the comparison group. - “not_yet_or_never”: Includes units not yet treated by time :math:`t` and never-treated units. - “never_treated”: Includes only never-treated units. anticipation : int, default 0 Number of periods before actual treatment start where units are considered treated (e.g., due to announcement effects). base_period : {“universal”, “varying”}, default “universal” Definition of the ‘before’ period in the DID comparison. - “universal”: Uses :math:`g - 1 - \text{anticipation}` as the base for all :math:`t`. - “varying”: Uses :math:`t - 1` as the base for all :math:`t`. include_pre_periods : bool, default False Whether to estimate :math:`ATT(g,t)` for :math:`t < g` (pre-treatment testing). alpha : float, default 0.05 Significance level for confidence intervals. diagnostic_data : bool, default True Whether to store diagnostic information (overlap, balance, etc.). propensity_clip : float, default 1e-4 Clipping threshold for propensity scores to avoid division by zero. logit_ridge : float, default 1e-4 L2 regularization strength for the logistic propensity score model. optimizer_tol : float, default 1e-8 Tolerance for the propensity score optimizer. optimizer_maxiter : int, default 1000 Maximum iterations for the propensity score optimizer. min_treated_per_cell : int, default 30 Minimum number of treated units required in a :math:`(g,t)` cell. min_control_per_cell : int, default 30 Minimum number of control units required in a :math:`(g,t)` cell. min_control_ess : float, default 20.0 Minimum effective sample size for control units in a :math:`(g,t)` cell. max_propensity_clip_share : float, default 0.05 Maximum fraction of units that can be clipped before skipping a cell. max_condition_number : float, default 1e5 Maximum condition number for covariate matrices. bootstrap_replications : int, default 0 Number of multiplier bootstrap replications for simultaneous confidence bands. If 0, uses asymptotic normal approximation for pointwise intervals. random_state : int, optional, default None Random seed for bootstrap multipliers.

  Examples

  > > > from causalis.scenarios.did.dgp import generate_did_gamma_26 from causalis.scenarios.did.model import CallawaySantAnnaDID

  > > > Generate synthetic staggered-adoption panel data

  > > > data = generate_did_gamma_26( … n_treated_units=50, … n_control_units=100, … seed=42, … )

  > > > Initialize and fit the model

  > > > model = CallawaySantAnnaDID(estimator=”dr”, control_group=”not_yet_or_never”) model.fit(data) # doctest: +ELLIPSIS CallawaySantAnnaDID(status=’fitted’, …)

  > > > Estimate effects and aggregate

  > > > results = model.estimate() results.summary() # doctest: +SKIP

  > > > Access specific aggregations

  > > > event_study = results.event_study() event_study.head() # doctest: +SKIP

  Notes

  In a staggered adoption design, units :math:`i` are treated at different times :math:`G_i \in \{g_1, \dots, g_K, \infty\}`. The group-time average treatment effect is defined as:

  .. math::

      ATT(g,t) = \mathbb{E}[Y_t(g) - Y_t(\infty) \mid G=g]

  where :math:`Y_t(g)` is the potential outcome at time :math:`t` if treated at time :math:`g`, and :math:`Y_t(\infty)` is the potential outcome if never treated.

  This implementation follows Callaway and Sant’Anna (2021) and uses logistic regression for propensity scores and linear regression for outcome models (in “dr” mode). The doubly robust estimator for :math:`ATT(g,t)` is:

  .. math::

      \theta_{DR}(g,t) = \mathbb{E} \left[ \left( \frac{G_g}{\mathbb{E}[G_g]} - \frac{\frac{p_g(X) C}{1-p_g(X)}}{\mathbb{E}[\frac{p_g(X) C}{1-p_g(X)}]} \right) (Y_t - Y_{base} - m_{g,t}(X)) \right]

  where :math:`G_g = \mathbb{1}\{G=g\}`, :math:`C` is the control group indicator, :math:`p_g(X)` is the propensity score, and :math:`m_{g,t}(X)` is the outcome regression.

  Simultaneous confidence bands are computed using the multiplier bootstrap on the influence functions of the :math:`ATT(g,t)` estimates.

  Initialization

  fit(data: causalis.data_contracts.panel_data_did.PanelDataDID) → causalis.scenarios.did.model.CallawaySantAnnaDID

    Fit all supported :math:`ATT(g,t)` cells on a validated :class:`PanelDataDID`.

    This method prepares the panel data, identifies valid comparison groups for each cohort-time cell, and estimates the group-time average treatment effects.

    Parameters

    data : PanelDataDID The validated panel data container.

    Returns

    CallawaySantAnnaDID The fitted model instance.

  estimate(*, alpha: Optional[float] = None, diagnostic_data: Optional[bool] = None, bootstrap_replications: Optional[int] = None, random_state: Optional[int] = None) → causalis.data_contracts.panel_did_estimate.CallawaySantAnnaDIDEstimate

    Aggregate group-time effects and perform inference.

    This method computes simple, cohort, calendar, and event-study aggregations from the fitted :math:`ATT(g,t)` cells. It also performs inference using either asymptotic normal approximation or the multiplier bootstrap.

    Parameters

    alpha : float, optional Significance level. If None, uses the value from `__init__`. diagnostic_data : bool, optional Whether to include diagnostic data in the result. If None, uses the value from `__init__`. bootstrap_replications : int, optional Number of multiplier bootstrap replications. If None, uses the value from `__init__`. random_state : int, optional Random seed for bootstrap. If None, uses the value from `__init__`.

    Returns

    CallawaySantAnnaDIDEstimate The estimation results including aggregations and inference.

  property is_fitted: bool

    Whether the model has been fitted on data.

  property support_: pandas.DataFrame

    A table of units and their inclusion status in various :math:`ATT(g,t)` cells.

  property skipped_cells_: pandas.DataFrame

    A table of cohort-time cells that were skipped due to insufficient data or quality issues.

  property cell_diagnostics_: pandas.DataFrame

    Detailed diagnostic information for each :math:`ATT(g,t)` cell.

  __repr__() → str

causalis.scenarios.did.model.__all__

  [‘AggregateKind’, ‘BasePeriod’, ‘CallawaySantAnnaDID’, ‘CallawaySantAnnaDIDEstimate’, ‘Estimator’]