diff_diff.plot_event_study#

diff_diff.plot_event_study(results=None, *, effects=None, se=None, periods=None, reference_period=None, pre_periods=None, post_periods=None, alpha=0.05, figsize=(10, 6), title='Event Study', xlabel='Period Relative to Treatment', ylabel='Treatment Effect', color='#2563eb', marker='o', markersize=8, linewidth=1.5, capsize=4, show_zero_line=True, show_reference_line=True, shade_pre=True, shade_color='#f0f0f0', ax=None, show=True, use_cband=True, backend='matplotlib')[source]

Create an event study plot showing treatment effects over time.

This function creates a coefficient plot with point estimates and confidence intervals for each time period, commonly used to visualize dynamic treatment effects and assess pre-trends.

Parameters:

  • results (MultiPeriodDiDResults, CallawaySantAnnaResults, or DataFrame, optional) – Results object from MultiPeriodDiD, CallawaySantAnna, or a DataFrame with columns ‘period’, ‘effect’, ‘se’ (and optionally ‘conf_int_lower’, ‘conf_int_upper’). If None, must provide effects and se directly.

  • effects (dict, optional) – Dictionary mapping periods to effect estimates. Used if results is None.

  • se (dict, optional) – Dictionary mapping periods to standard errors. Used if results is None.

  • periods (list, optional) – List of periods to plot. If None, uses all periods from results.

  • reference_period (any, optional) – The reference period to highlight. When explicitly provided, effects are normalized (ref effect subtracted) and ref SE is set to NaN. When None and auto-inferred from results, only hollow marker styling is applied (no normalization). If None, tries to infer from results.

  • pre_periods (list, optional) – List of pre-treatment periods. Used for shading.

  • post_periods (list, optional) – List of post-treatment periods. Used for shading.

  • alpha (float, default=0.05) – Significance level for confidence intervals.

  • figsize (tuple, default=(10, 6)) – Figure size (width, height) in inches.

  • title (str, default="Event Study") – Plot title.

  • xlabel (str, default="Period Relative to Treatment") – X-axis label.

  • ylabel (str, default="Treatment Effect") – Y-axis label.

  • color (str, default="#2563eb") – Color for points and error bars.

  • marker (str, default="o") – Marker style for point estimates.

  • markersize (int, default=8) – Size of markers.

  • linewidth (float, default=1.5) – Width of error bar lines.

  • capsize (int, default=4) – Size of error bar caps.

  • show_zero_line (bool, default=True) – Whether to show a horizontal line at y=0.

  • show_reference_line (bool, default=True) – Whether to show a vertical line at the reference period.

  • shade_pre (bool, default=True) – Whether to shade the pre-treatment region.

  • shade_color (str, default="#f0f0f0") – Color for pre-treatment shading.

  • ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, creates new figure.

  • show (bool, default=True) – Whether to call plt.show() at the end.

  • use_cband (bool, default=True) – Whether to use simultaneous confidence band CIs when available from CallawaySantAnna results. When False, pointwise CIs from alpha are used regardless.

  • backend (str, default="matplotlib") – Plotting backend: "matplotlib" for static plots or "plotly" for interactive plots.

Returns:

The axes object (matplotlib) or figure (plotly) containing the plot.

Return type:

matplotlib.axes.Axes or plotly.graph_objects.Figure

Examples

Using with MultiPeriodDiD results:

>>> from diff_diff import MultiPeriodDiD, plot_event_study
>>> did = MultiPeriodDiD()
>>> results = did.fit(data, outcome='y', treatment='treated',
...                   time='period', post_periods=[3, 4, 5])
>>> plot_event_study(results)

Using with a DataFrame:

>>> df = pd.DataFrame({
...     'period': [-2, -1, 0, 1, 2],
...     'effect': [0.1, 0.05, 0.0, 0.5, 0.6],
...     'se': [0.1, 0.1, 0.0, 0.15, 0.15]
... })
>>> plot_event_study(df, reference_period=0)

Using with manual effects:

>>> effects = {-2: 0.1, -1: 0.05, 0: 0.0, 1: 0.5, 2: 0.6}
>>> se = {-2: 0.1, -1: 0.1, 0: 0.0, 1: 0.15, 2: 0.15}
>>> plot_event_study(effects=effects, se=se, reference_period=0)

Notes

Event study plots are a standard visualization in difference-in-differences analysis. They show:

  1. Pre-treatment periods: Effects should be close to zero if parallel trends holds. Large pre-treatment effects suggest the assumption may be violated.

  2. Reference period: Usually the last pre-treatment period (t=-1). When explicitly specified via reference_period, effects are normalized to zero at this period. When auto-inferred, shown with hollow marker only.

  3. Post-treatment periods: The treatment effects of interest. These show how the outcome evolved after treatment.

The confidence intervals help assess statistical significance. Effects whose CIs don’t include zero are typically considered significant.