diff_diff.plot_pretrends_power

diff_diff.plot_pretrends_power(results=None, *, M_values=None, powers=None, mdv=None, target_power=0.8, figsize=(10, 6), title='Pre-Trends Test Power Curve', xlabel='Violation Magnitude (M)', ylabel='Power', color='#2563eb', mdv_color='#dc2626', target_color='#22c55e', linewidth=2.0, show_mdv_line=True, show_target_line=True, show_grid=True, ax=None, show=True)[source]

Plot pre-trends test power curve.

Visualizes how the power to detect parallel trends violations changes with the violation magnitude (M). This helps understand what violations your pre-trends test is capable of detecting.

Parameters:

results (PreTrendsPowerResults, PreTrendsPowerCurve, or DataFrame, optional) – Results from PreTrendsPower.fit() or power_curve(), or a DataFrame with columns ‘M’ and ‘power’. If None, must provide M_values and powers.
M_values (list of float, optional) – Violation magnitudes (x-axis). Required if results is None.
powers (list of float, optional) – Power values (y-axis). Required if results is None.
mdv (float, optional) – Minimum detectable violation to mark on the plot.
target_power (float, default=0.80) – Target power level to show as horizontal line.
figsize (tuple, default=(10, 6)) – Figure size (width, height) in inches.
title (str) – Plot title.
xlabel (str) – X-axis label.
ylabel (str) – Y-axis label.
color (str, default="#2563eb") – Color for the power curve line.
mdv_color (str, default="#dc2626") – Color for the MDV vertical line.
target_color (str, default="#22c55e") – Color for the target power horizontal line.
linewidth (float, default=2.0) – Line width for the power curve.
show_mdv_line (bool, default=True) – Whether to show vertical line at MDV.
show_target_line (bool, default=True) – Whether to show horizontal line at target power.
show_grid (bool, default=True) – Whether to show grid lines.
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.

Returns:

The axes object containing the plot.

Return type:

matplotlib.axes.Axes

Examples

From PreTrendsPower results:

>>> from diff_diff import MultiPeriodDiD
>>> from diff_diff.pretrends import PreTrendsPower
>>> from diff_diff.visualization import plot_pretrends_power
>>>
>>> mp_did = MultiPeriodDiD()
>>> event_results = mp_did.fit(data, outcome='y', treatment='treated',
...                            time='period', post_periods=[4, 5, 6, 7])
>>>
>>> pt = PreTrendsPower()
>>> curve = pt.power_curve(event_results)
>>> plot_pretrends_power(curve)

From manual data:

>>> plot_pretrends_power(
...     M_values=[0, 0.5, 1, 1.5, 2],
...     powers=[0.05, 0.3, 0.6, 0.85, 0.95],
...     mdv=1.2,
...     target_power=0.80
... )

Notes

The power curve shows how likely you are to reject the null hypothesis of parallel trends given a true violation of magnitude M. Key points:

At M=0: Power equals alpha (size of the test).
At MDV: Power equals target power (default 80%).
Beyond MDV: Power increases toward 100%.

A steep power curve indicates a sensitive pre-trends test. A flat curve indicates the test has limited ability to detect violations, suggesting you should use HonestDiD sensitivity analysis for robust inference.