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