causalis.scenarios.did.refutation.diagnostics

Module Contents

Functions

did_support_table	Return Callaway & Sant’Anna ATT(g,t) support under the requested model policy.
raw_did_event_study_table	Return unadjusted DID event-study cells from the validated panel.
did_covariate_balance_table	Return unweighted base-period covariate balance for Callaway & Sant’Anna cells.
did_base_design_table	Return base-period control-design rank diagnostics for Callaway & Sant’Anna cells.
run_did_diagnostics	Run compact pre-fit diagnostics for Callaway & Sant’Anna estimation readiness.

Data

BasePeriod
__all__

API

causalis.scenarios.did.refutation.diagnostics.BasePeriod

None

causalis.scenarios.did.refutation.diagnostics.did_support_table(data: causalis.data_contracts.PanelDataDID, *, control_group: causalis.data_contracts.panel_data_did.ComparisonGroup = 'not_yet_or_never', anticipation: int = 0, base_period: causalis.scenarios.did.refutation.diagnostics.BasePeriod = 'universal', include_pre_periods: bool = False) → pandas.DataFrame

Return Callaway & Sant’Anna ATT(g,t) support under the requested model policy.

This function identifies the available cohort-time cells for estimation and verifies if there are enough units to form complete treated/control pairs. A unit is “complete” if it is observed in both the base period and the target period.

Parameters

data : PanelDataDID The validated panel data object. control_group : {“not_yet_or_never”, “never_treated”}, default “not_yet_or_never” The definition of the comparison group. anticipation : int, default 0 Number of periods before treatment to exclude from the control group due to potential anticipation effects. base_period : {“universal”, “varying”}, default “universal” Whether to use a fixed base period (universal) or a period-specific one (varying) for each target period. include_pre_periods : bool, default False Whether to include pre-treatment periods (useful for placebo tests).

Returns

pd.DataFrame A table of support metrics for each cohort-time cell: - cohort: The treatment group. - time: The calendar period. - base_time: The period used as a baseline for the difference. - is_supported: Whether the cell has sufficient data for estimation. - n_treated_complete: Number of treated units observed in both periods. - n_control_complete: Number of control units observed in both periods. - treated_completion_rate: Share of cohort units that are complete. - control_completion_rate: Share of control units that are complete.

Notes

The Callaway & Sant’Anna (2021) estimator requires that for each target parameter :math:ATT(g,t), there exists a set of units in the comparison group that are also observed in the base period :math:g-1 (or :math:t-1 for varying base periods).

Examples

from causalis.scenarios.did import generate_did_gamma_26 from causalis.scenarios.did.refutation import did_support_table data = generate_did_gamma_26(n_units=100, n_periods=5, seed=42) support = did_support_table(data, control_group=”never_treated”) support[[“cohort”, “time”, “is_supported”, “n_treated_complete”]].head()

causalis.scenarios.did.refutation.diagnostics.raw_did_event_study_table(data: causalis.data_contracts.PanelDataDID, *, control_group: causalis.data_contracts.panel_data_did.ComparisonGroup = 'not_yet_or_never', anticipation: int = 0, base_period: causalis.scenarios.did.refutation.diagnostics.BasePeriod = 'varying', include_pre_periods: bool = True) → pandas.DataFrame

Return unadjusted DID event-study cells from the validated panel.

This function calculates simple mean differences between treated and control groups across different event-time periods. These are “raw” estimates without covariate adjustment or IPW/DR weighting.

Parameters

data : PanelDataDID The validated panel data object. control_group : {“not_yet_or_never”, “never_treated”}, default “not_yet_or_never” The definition of the comparison group. anticipation : int, default 0 Number of periods before treatment to exclude. base_period : {“varying”, “universal”}, default “varying” The base period policy for the event study. include_pre_periods : bool, default True Whether to include pre-treatment (placebo) periods.

Returns

pd.DataFrame A table of raw DID estimates: - event_time: Periods relative to treatment (:math:t - g). - raw_did: The unadjusted Difference-in-Differences estimate. - se: Naive standard error of the mean difference. - t_stat: t-statistic for the null of zero difference. - n_treated, n_control: Sample sizes in the cell.

Notes

The raw DID for a cohort-time cell :math:(g, t) is calculated as:

.. math:: \Delta_{raw}(g,t) = [E[Y_t | G=g] - E[Y_{base} | G=g]] - [E[Y_t | C] - E[Y_{base} | C]]

where :math:C is the comparison group. These are useful for visual inspection of parallel trends before applying more complex estimators.

Examples

from causalis.scenarios.did import generate_did_gamma_26 from causalis.scenarios.did.refutation import raw_did_event_study_table data = generate_did_gamma_26(n_units=200, n_periods=5, seed=42) event_table = raw_did_event_study_table(data) event_table[[“event_time”, “raw_did”, “t_stat”]].head()

causalis.scenarios.did.refutation.diagnostics.did_covariate_balance_table(data: causalis.data_contracts.PanelDataDID, *, control_group: causalis.data_contracts.panel_data_did.ComparisonGroup = 'not_yet_or_never', anticipation: int = 0, base_period: causalis.scenarios.did.refutation.diagnostics.BasePeriod = 'universal', include_pre_periods: bool = False, post_only: bool = True) → pandas.DataFrame

Return unweighted base-period covariate balance for Callaway & Sant’Anna cells.

Calculates the standardized mean difference (SMD) for each covariate between the treated and control groups in the base period.

Parameters

data : PanelDataDID The validated panel data object. control_group : {“not_yet_or_never”, “never_treated”}, default “not_yet_or_never” The definition of the comparison group. anticipation : int, default 0 Anticipation periods to exclude. base_period : {“universal”, “varying”}, default “universal” Base period policy. include_pre_periods : bool, default False Whether to include pre-treatment cells. post_only : bool, default True If True, only checks balance for cells used in post-treatment estimation.

Returns

pd.DataFrame A balance table with columns: - covariate: Name of the covariate. - treated_mean: Average value in the treated group. - control_mean: Average value in the control group. - smd: Standardized Mean Difference. - abs_smd: Absolute value of the SMD.

Notes

The Standardized Mean Difference is defined as:

.. math:: SMD = \frac{\bar{X}{treated} - \bar{X}{control}}{\sqrt{(s^2_{treated} + s^2_{control}) / 2}}

Values of :math:|SMD| > 0.1 or :math:0.25 are often used as thresholds to indicate potential imbalance that requires adjustment.

Examples

from causalis.scenarios.did import generate_did_gamma_26 from causalis.scenarios.did.refutation import did_covariate_balance_table data = generate_did_gamma_26(n_units=200, n_periods=5, seed=42) balance = did_covariate_balance_table(data) balance[[“covariate”, “treated_mean”, “control_mean”, “abs_smd”]].head()

causalis.scenarios.did.refutation.diagnostics.did_base_design_table(data: causalis.data_contracts.PanelDataDID, *, control_group: causalis.data_contracts.panel_data_did.ComparisonGroup = 'not_yet_or_never', anticipation: int = 0, base_period: causalis.scenarios.did.refutation.diagnostics.BasePeriod = 'universal', include_pre_periods: bool = False, post_only: bool = True) → pandas.DataFrame

Return base-period control-design rank diagnostics for Callaway & Sant’Anna cells.

Checks the numerical stability of the propensity score and outcome regression designs in the comparison group. High condition numbers or rank deficiency indicate potential multicollinearity or insufficient variation in covariates.

Parameters

data : PanelDataDID The validated panel data object. control_group : {“not_yet_or_never”, “never_treated”}, default “not_yet_or_never” The definition of the comparison group. anticipation : int, default 0 Anticipation periods to exclude. base_period : {“universal”, “varying”}, default “universal” Base period policy. include_pre_periods : bool, default False Whether to include pre-treatment cells. post_only : bool, default True If True, only checks cells used in post-treatment estimation.

Returns

pd.DataFrame A table of design diagnostics: - n_control: Number of units in the control pool for the cell. - n_parameters: Number of covariates including the intercept. - control_design_rank: Matrix rank of the covariate design. - condition_number: The L2 condition number of the design matrix. - is_rank_deficient: Whether the matrix is not full rank.

Examples

from causalis.scenarios.did import generate_did_gamma_26 from causalis.scenarios.did.refutation import did_base_design_table data = generate_did_gamma_26(n_units=200, n_periods=5, seed=42) design = did_base_design_table(data) design[[“n_control”, “condition_number”, “is_rank_deficient”]].head()

causalis.scenarios.did.refutation.diagnostics.run_did_diagnostics(data: causalis.data_contracts.PanelDataDID, *, control_group: causalis.data_contracts.panel_data_did.ComparisonGroup = 'not_yet_or_never', anticipation: int = 0, base_period: causalis.scenarios.did.refutation.diagnostics.BasePeriod = 'universal', include_pre_periods: bool = False, min_treated_per_cell: int = 30, min_control_per_cell: int = 30, min_control_to_treated_ratio: float = 1.0, min_pair_completion_rate: float = 0.8, min_control_pool_retention: float = 0.25, max_unsupported_cell_share: float = 0.25, min_pre_periods: int = 2, max_abs_pretrend_t_stat: float = 2.0, max_abs_covariate_smd: float = 0.25, max_condition_number: float = _DEFAULT_MAX_CONDITION_NUMBER, min_clusters: int = 2) → pandas.DataFrame

Run compact pre-fit diagnostics for Callaway & Sant’Anna estimation readiness.

This function performs a battery of “smoke tests” on the data before fitting the model. It checks for sufficient sample size, parallel trends in pre-treatment periods, covariate balance, and numerical stability of the design.

Parameters

data : PanelDataDID The validated panel data object. control_group : {“not_yet_or_never”, “never_treated”}, default “not_yet_or_never” The definition of the comparison group. anticipation : int, default 0 Anticipation periods to exclude. base_period : {“universal”, “varying”}, default “universal” Base period policy. include_pre_periods : bool, default False Whether to include pre-treatment cells in the diagnostics. min_treated_per_cell : int, default 30 Minimum number of treated units required in each ATT(g,t) cell. min_control_per_cell : int, default 30 Minimum number of control units required in each ATT(g,t) cell. min_control_to_treated_ratio : float, default 1.0 Minimum ratio of control units to treated units. min_pair_completion_rate : float, default 0.80 Minimum share of units that must be observed in both base and target periods. min_control_pool_retention : float, default 0.25 Minimum share of the original control pool that must be available for estimation. max_unsupported_cell_share : float, default 0.25 Maximum allowable share of cohort-time cells that cannot be estimated. min_pre_periods : int, default 2 Minimum number of pre-treatment periods required for placebo tests. max_abs_pretrend_t_stat : float, default 2.0 Maximum absolute t-statistic allowed for raw pre-treatment differences. max_abs_covariate_smd : float, default 0.25 Maximum allowable absolute SMD for covariates in the base period. max_condition_number : float, default 1e6 Maximum allowable condition number for the control design matrix. min_clusters : int, default 2 Minimum number of clusters required if clustering is used.

Returns

pd.DataFrame A diagnostic report with columns: - test: Name of the diagnostic check. - flag: Status (GREEN, YELLOW, RED). - value: Observed value of the metric. - threshold: The threshold used for the check. - message: Descriptive result message.

Examples

from causalis.scenarios.did import generate_did_gamma_26 from causalis.scenarios.did.refutation import run_did_diagnostics data = generate_did_gamma_26(n_units=300, n_periods=5, seed=42) report = run_did_diagnostics(data) report[[“test”, “flag”, “value”]]

causalis.scenarios.did.refutation.diagnostics.__all__

[‘did_support_table’, ‘raw_did_event_study_table’, ‘did_covariate_balance_table’, ‘did_base_design_t…