diff_diff.EventStudyResults#

class diff_diff.EventStudyResults[source]#

Bases: BaseResults

Unified event-study representation (spec section 5, row M-092).

ONE representation for per-event-time effects across all estimators. Columnar numpy arrays index-aligned to event_time (the HeterogeneousAdoptionDiDEventStudyResults precedent). Values are copied bit-exactly from each estimator’s native surface - never recomputed - except the mandated reference-row normalization (att=0.0, inference NaN).

Parameters:

  • event_time (np.ndarray) – Sorted estimator-native event-time labels, NEVER renumbered. Relative producers use their own origin (see event_time_convention); the pre-4.0 MultiPeriodDiD surface is calendar-keyed (time_scale="calendar") and may carry object dtype (str/datetime period labels).

  • att (np.ndarray) – Canonical per-event-time inference columns. On the reference row (if any): att == 0.0 and se/t_stat/p_value are NaN.

  • se (np.ndarray) – Canonical per-event-time inference columns. On the reference row (if any): att == 0.0 and se/t_stat/p_value are NaN.

  • t_stat (np.ndarray) – Canonical per-event-time inference columns. On the reference row (if any): att == 0.0 and se/t_stat/p_value are NaN.

  • p_value (np.ndarray) – Canonical per-event-time inference columns. On the reference row (if any): att == 0.0 and se/t_stat/p_value are NaN.

  • conf_int_lower (np.ndarray) – Confidence-interval bounds at alpha (NaN on the reference row).

  • conf_int_upper (np.ndarray) – Confidence-interval bounds at alpha (NaN on the reference row).

  • is_reference (np.ndarray) – Boolean; the EXPLICIT reference-period marking. This column - not any count sentinel - is the sole consumer-facing signal. Usually one True entry, but MULTIPLE are legal (CallawaySantAnna universal base on a gapped grid carries one per cohort’s positional base), and ZERO when the estimator omits no baseline (e.g. HAD, Wooldridge). Use reference_periods for the general case; reference_period is the single-reference convenience scalar.

  • n (np.ndarray) – Per-event-time count as float, NaN where the producer records none (and on the reference row - no estimation happened there).

  • n_kind (str or None) – Semantic of n for this producer, drawn from the shared N_KIND_VOCABULARY: "groups" (a group-level count - cohorts for CallawaySantAnna/SunAbraham, eligible switcher groups per horizon for de Chaisemartin-D’Haultfoeuille with L_max >= 1), "switcher_cells" (dCDH legacy L_max is None path: switching (g, t) cells, where one group may contribute several), "cells" ((g, t) cells generally - what CallawaySantAnna’s "group" aggregation counts), "units" (distinct units, as in the overall/simple aggregation), "obs" (observations), "clusters", or None when no count is recorded. Never conflate these units.

  • reference_period (Any or None) – Convenience scalar echo of the marked row’s event_time label when there is EXACTLY ONE reference row; None when there are zero or several. Use is_reference (or the reference_periods property) for the general case - some estimators (CallawaySantAnna universal base on a gapped grid) carry multiple reference-only horizons.

  • time_scale (str) – "relative" or "calendar".

  • event_time_convention (str or None) – Origin documentation for relative scales: "e0_first_treated" (e = t - g; first treated period at e=0) or "l1_first_switch" (de Chaisemartin-D’Haultfoeuille: instantaneous effect at l=1, placebos at negative keys). Horizons are documented, not renumbered. (EfficientDiD buckets fractional-period horizons by int(t - g) — see its REGISTRY truncation Note.)

  • vcov (np.ndarray or None) – Full event-study variance-covariance matrix where the RESULT CONTAINER exposes one (e.g. CallawaySantAnna, SunAbraham, MultiPeriodDiD, StackedDiD, and TwoStageDiD’s analytical modes), ordered by vcov_index. None when the producer records no matrix or when the stored SEs are no longer its diagonal (bootstrap and replicate-weight overrides clear it rather than ship an inconsistent matrix).

  • vcov_index (np.ndarray or None) – event_time labels labelling vcov’s rows/columns (explicit ordering for HonestDiD / PreTrendsPower consumption).

  • cband_lower (np.ndarray or None) – Simultaneous confidence-band bounds where computed; None when the producer has none (to_dataframe then emits NaN columns - the schema never changes).

  • cband_upper (np.ndarray or None) – Simultaneous confidence-band bounds where computed; None when the producer has none (to_dataframe then emits NaN columns - the schema never changes).

  • cband_crit_value (float or None) – Critical value of the simultaneous band, where computed.

  • alpha (float) – Significance level of the stored intervals.

  • source (str or None) – Producing results-class name (provenance).

  • df (float, np.ndarray, or None) – Per-row inference degrees of freedom: df[i] is the df ACTUALLY passed to safe_inference for row i’s stored p-value/CI, threaded from the producer. Accepts None (no df exposed -> all-NaN column), a scalar (broadcast to every row - e.g. CallawaySantAnna, whose explicit-survey event study applies ONE conservative df, the minimum per-horizon effective df, to all rows; or de Chaisemartin-D’Haultfoeuille, whose effect and placebo rows share one design df), or a length-n array (per-row producers: StackedDiD and SunAbraham hc2_bm per-event Bell-McCaffrey df, LPDiD per-horizon cluster df, MultiPeriodDiD hc2_bm per-period df). NaN on any row means normal-theory inference, an undefined df, bootstrap-overridden inference, or a producer that records none; reference rows and rows with NaN p-values are always NaN.

  • base_period (str or None) – Producer provenance: the fit’s base-period regime where the producer has one (CallawaySantAnna vocabulary: "varying" or "universal"). None when the producer has no such notion. HonestDiD reads this for its universal-base interpretation warning.

  • anticipation (int or None) – Producer provenance: the fit’s anticipation window in periods, where the producer has one. None when the producer has no such notion. PreTrendsPower reads this to exclude anticipation-window rows (event_time >= -anticipation) from the pre-trend set.

  • df_survey (float or None) – Producer provenance: the fit’s resolved SCALAR inference df, with the established semantics of the fit-time consumers - survey_metadata.df_survey where present (0.0 = replicate design with an undefined df, which fails closed to NaN critical values downstream), else df_inference (the bare-cluster= carrier), else None (no scalar df notion). Exists beside the per-row df column because that column CANNOT encode the replicate-undefined sentinel: __post_init__ forces per-row df to NaN wherever the p-value is non-finite.

  • reference_event_times (tuple or None) – Producer provenance: the DISTINCT per-cohort normalization-base event times (CallawaySantAnna base_period="universal": each cohort’s positional base period minus its cohort, deduplicated, sorted). More than one entry means the coefficients were normalized against DIFFERENT bases (gapped time grid) - and on such grids a cohort’s base can OVERLAP another cohort’s estimated horizon, where NO reference-only row exists to mark it, so this field (not is_reference) is the authoritative common-reference signal. HonestDiD and PreTrendsPower fail closed when it carries more than one entry. None when the producer records no such notion (varying base, non-CS producers, hand-built surfaces).

Methods

__init__(event_time, att, se, t_stat, ...[, ...])

summary([alpha])

Return a formatted event-study table.

to_dataframe()

Return the pinned per-event-time table (EVENT_STUDY_SCHEMA).

to_dict()

Return a JSON-friendly dict (columns as lists, plus metadata).

Attributes

alpha

anticipation

base_period

cband_crit_value

cband_lower

cband_upper

df

df_survey

estimand

The estimand label for the att column when the producer's per-horizon estimand is NOT an ATT - HeterogeneousAdoptionDiD's per-horizon "WAS"/"WAS_d_lower" (row M-027; _from_had relays target_parameter).

estimation_spec

TWFE event-study design provenance (M-092 amendment #5, with row M-010): "within" (unit + time FE) or "pooled" (the MultiPeriodDiD design - treatment-group dummy + period dummies, no unit FE).

event_time_convention

n_kind

post_periods

Calendar-partition provenance (M-092 pre-cut amendment #5, with row M-010): the producer's AUTHORITATIVE post-treatment period labels.

reference_event_times

reference_period

reference_periods

All reference-row event_time labels (JSON-safe scalars).

source

time_scale

vcov

vcov_index

event_time

att

se

t_stat

p_value

conf_int_lower

conf_int_upper

is_reference

n

__init__(event_time, att, se, t_stat, p_value, conf_int_lower, conf_int_upper, is_reference, n, n_kind=None, reference_period=None, time_scale='relative', event_time_convention=None, vcov=None, vcov_index=None, cband_lower=None, cband_upper=None, cband_crit_value=None, alpha=0.05, source=None, df=None, base_period=None, anticipation=None, df_survey=None, reference_event_times=None, estimand=None, post_periods=None, estimation_spec=None)#
Parameters:
Return type:

None

classmethod __new__(*args, **kwargs)#