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: "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), "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.

  • 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 a length-n array (per-row producers: StackedDiD 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.

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

cband_crit_value

cband_lower

cband_upper

df

event_time_convention

n_kind

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)#
Parameters:
Return type:

None

classmethod __new__(*args, **kwargs)#