diff_diff.HeterogeneousAdoptionDiDEventStudyResults#

class diff_diff.HeterogeneousAdoptionDiDEventStudyResults[source]#

Bases: object

Event-study results for HeterogeneousAdoptionDiD (Phase 2b).

Per-horizon arrays align with event_times by index; all per-horizon arrays have shape (n_horizons,). The anchor horizon e = -1 (i.e., t = F - 1) is NOT included because Y_{g, F-1} - Y_{g, F-1} = 0 trivially and the WAS is not identified there.

Per-horizon inference fields (t_stat, p_value, conf_int_low, conf_int_high) are NaN-coupled to the per-horizon se via diff_diff.utils.safe_inference(); att and se themselves are raw estimator outputs from the chosen design path on each horizon’s first differences.

Design resolution is SHARED across horizons: the design, d_lower, target_parameter, and inference_method are single scalars determined once from the post-period dose distribution D_{g, F} (paper Appendix B.2 convention — the dose regressor is invariant across event-time horizons).

event_times#

Integer event-time labels e = t - F, sorted ascending. Excludes e = -1 (the anchor). Post-period horizons have e >= 0; pre-period placebos have e <= -2.

Type:: np.ndarray, shape (n_horizons,)

att#

Per-horizon WAS point estimate on the beta-scale (see HeterogeneousAdoptionDiDResults.att for the per-design formula, applied to ΔY_t = Y_{g,t} - Y_{g,F-1}).

Type:: np.ndarray, shape (n_horizons,)

se#

Per-horizon standard error on the beta-scale. Three regimes:

Unweighted: per-horizon INDEPENDENT analytical sandwich (continuous: CCT-2014 weighted-robust divided by |den|; mass-point: structural-residual 2SLS sandwich via _fit_mass_point_2sls). No cross-horizon covariance.
``weights=`` shortcut: continuous paths still use the CCT-2014 weighted-robust SE from lprobust (bc_fit.se_robust / |den|); mass-point uses the analytical weighted 2SLS pweight sandwich (HC1 / classical / CR1 depending on vcov_type + cluster=). No Binder-TSL composition on this path — inference is Normal (df=None).
``survey=``: each horizon composes Binder (1983) Taylor-series linearization via compute_survey_if_variance() on the per-unit β̂-scale IF (continuous + mass-point both route through the same helper). df_survey threads into safe_inference for t-inference.

Pointwise CIs are always populated; a simultaneous confidence band is available only on the weighted path via cband_* below. Joint cross-horizon analytical covariance is not computed in this release (tracked in TODO.md).

Type:: np.ndarray, shape (n_horizons,)

t_stat, p_value

Per-horizon inference triple element.

Type:: np.ndarray, shape (n_horizons,)

conf_int_low, conf_int_high

Per-horizon CI endpoints at level alpha.

Type:: np.ndarray, shape (n_horizons,)

n_obs_per_horizon#

Per-horizon sample size (units contributing at that event time). In Phase 2b this equals n_units for every horizon because the validator rejects NaN in outcome / dose / unit columns upstream; tracked as a field for future flexibility (e.g., per-period missingness).

Type:: np.ndarray, shape (n_horizons,)

alpha#

CI level used at fit time (0.05 for a 95% CI).

Type:: float

design#

Resolved design mode, shared across horizons: "continuous_at_zero", "continuous_near_d_lower", or "mass_point".

Type:: str

target_parameter#

Estimand label: "WAS" for Design 1’ (continuous_at_zero), "WAS_d_lower" for the other two.

Type:: str

d_lower#

Support infimum used for all horizons. 0.0 for Design 1’; float(d.min()) otherwise.

Type:: float

dose_mean#

D_bar = (1/G) * sum(D_{g,F}) computed on the fit sample (after the staggered last-cohort filter, if applied).

Type:: float

F#

First-treatment period label (arbitrary dtype — int, str, datetime). Identified by the multi-period dose invariant from the fitted data.

Type:: object

n_units#

Number of unique units contributing to the fit. After staggered auto-filter: last-cohort units PLUS never-treated (first_treat = 0) units retained as the untreated-group comparison per paper Appendix B.2. Only earlier-treated cohorts are dropped.

Type:: int

inference_method#

"analytical_nonparametric" (continuous designs) or "analytical_2sls" (mass-point). Shared across horizons.

Type:: str

vcov_type#

Effective variance-covariance family used on the mass-point path ("classical", "hc1", or "cr1" when cluster supplied). None on the continuous paths (they use CCT-2014 robust SE).

Type:: str or None

cluster_name#

Column name of the cluster variable when cluster-robust SE is requested. None otherwise.

Type:: str or None

survey_metadata#

Repo-standard survey metadata dataclass from diff_diff.survey.SurveyMetadata. None when fit() was called without survey= or weights=; populated on the weighted event-study path (Phase 4.5 B). See HeterogeneousAdoptionDiDResults.survey_metadata for the attribute contract.

Type:: SurveyMetadata or None

variance_formula#

Per-horizon variance family (applied uniformly across horizons). "pweight" / "pweight_2sls" on the weights= shortcut, "survey_binder_tsl" / "survey_binder_tsl_2sls" on the survey= path. None on unweighted fits.

Type:: str or None

effective_dose_mean#

Weighted denominator used by the β̂-scale rescaling (continuous paths: weighted sample mean of d or d - d_lower; mass-point: weighted Wald-IV dose gap). None on unweighted fits.

Type:: float or None

cband_low, cband_high

Simultaneous confidence-band endpoints constructed by the multiplier-bootstrap sup-t procedure. None on unweighted fits and when fit(..., cband=False) is passed. Horizons with se <= 0 or non-finite se are NaN (matches the pointwise inference gate from safe_inference).

Type:: np.ndarray or None, shape (n_horizons,)

cband_crit_value#

Sup-t multiplier-bootstrap critical value at level 1 - alpha. Under a trivial resolved design (no strata / PSU / FPC) at H=1 reduces to Φ⁻¹(1 − alpha/2) ≈ 1.96 up to Monte Carlo error; under stratified designs the helper applies PSU-aggregation + stratum-demeaning + sqrt(n_h / (n_h - 1)) small-sample correction so the bootstrap variance matches the analytical Binder-TSL target term-for- term.

Type:: float or None

cband_method#

"multiplier_bootstrap" on the weighted event-study path with cband=True, else None.

Type:: str or None

cband_n_bootstrap#

Number of multiplier-bootstrap replicates used to compute the sup-t critical value.

Type:: int or None

bandwidth_diagnostics#

Per-horizon bandwidth diagnostics on the continuous paths; None on the mass-point path. When non-None, aligned with event_times by index.

Type:: list[BandwidthResult] or None

bias_corrected_fit#

Per-horizon bias-corrected fit on the continuous paths; None on the mass-point path. When non-None, aligned with event_times by index.

Type:: list[BiasCorrectedFit] or None

filter_info#

Populated when the staggered-timing last-cohort auto-filter fires. Keys: "F_last" (kept cohort label), "n_kept" (units retained), "n_dropped" (units dropped), "dropped_cohorts" (list of dropped cohort labels). None when no filter was applied.

Type:: dict or None

Methods

`__init__`(event_times, att, se, t_stat, ...)
`print_summary`()	Print the summary to stdout.
`summary`()	Formatted per-horizon summary table.
`to_dataframe`()	Return a tidy per-horizon DataFrame.
`to_dict`()	Return results as a dict with per-horizon arrays and scalars.

Attributes

`cband_crit_value`	Sup-t multiplier-bootstrap critical value at level `1 - alpha`.
`cband_high`	Simultaneous confidence-band upper endpoints, shape `(n_horizons,)`.
`cband_low`	Simultaneous confidence-band lower endpoints, shape `(n_horizons,)`.
`cband_method`	`"multiplier_bootstrap"` on the weighted event-study path with `cband=True`, else `None`.
`cband_n_bootstrap`	Number of multiplier-bootstrap replicates used to compute the sup-t critical value.
`effective_dose_mean`	Weighted denominator used by the β̂-scale rescaling.
`variance_formula`	Per-horizon variance family label (applied uniformly across all horizons in the fit).
`event_times`
`att`
`se`
`t_stat`
`p_value`
`conf_int_low`
`conf_int_high`
`n_obs_per_horizon`
`alpha`
`design`
`target_parameter`
`d_lower`
`dose_mean`
`F`
`n_units`
`inference_method`
`vcov_type`
`cluster_name`
`survey_metadata`
`bandwidth_diagnostics`
`bias_corrected_fit`
`filter_info`

__init__(event_times, att, se, t_stat, p_value, conf_int_low, conf_int_high, n_obs_per_horizon, alpha, design, target_parameter, d_lower, dose_mean, F, n_units, inference_method, vcov_type, cluster_name, survey_metadata, bandwidth_diagnostics, bias_corrected_fit, filter_info, variance_formula=None, effective_dose_mean=None, cband_low=None, cband_high=None, cband_crit_value=None, cband_method=None, cband_n_bootstrap=None)#

Parameters:

event_times (ndarray)
att (ndarray)
se (ndarray)
t_stat (ndarray)
p_value (ndarray)
conf_int_low (ndarray)
conf_int_high (ndarray)
n_obs_per_horizon (ndarray)
alpha (float)
design (str)
target_parameter (str)
d_lower (float)
dose_mean (float)
F (Any)
n_units (int)
inference_method (str)
vcov_type (str | None)
cluster_name (str | None)
survey_metadata (SurveyMetadata | None)
bandwidth_diagnostics (List[BandwidthResult | None] | None)
bias_corrected_fit (List[BiasCorrectedFit | None] | None)
filter_info (Dict[str, Any] | None)
variance_formula (str | None)
effective_dose_mean (float | None)
cband_low (ndarray | None)
cband_high (ndarray | None)
cband_crit_value (float | None)
cband_method (str | None)
cband_n_bootstrap (int | None)

Return type:

None

classmethod __new__(*args, **kwargs)#