diff_diff.plot_power_curve#

diff_diff.plot_power_curve(results=None, *, effect_sizes=None, powers=None, mde=None, target_power=0.8, plot_type='effect', figsize=(10, 6), title=None, xlabel=None, ylabel='Power', color='#2563eb', mde_color='#dc2626', target_color='#22c55e', linewidth=2.0, show_mde_line=True, show_target_line=True, show_grid=True, ax=None, show=True, backend='matplotlib')[source]

Create a power curve visualization.

Shows how statistical power changes with effect size or sample size, helping researchers understand the trade-offs in study design.

Parameters:

  • results (PowerResults, SimulationPowerResults, or DataFrame, optional) – Results object from PowerAnalysis or simulate_power(), or a DataFrame with columns ‘effect_size’ and ‘power’ (or ‘sample_size’ and ‘power’). If None, must provide effect_sizes and powers directly.

  • effect_sizes (list of float, optional) – Effect sizes (x-axis values). Required if results is None.

  • powers (list of float, optional) – Power values (y-axis values). Required if results is None.

  • mde (float, optional) – Minimum detectable effect to mark on the plot.

  • target_power (float, default=0.80) – Target power level to show as horizontal line.

  • plot_type (str, default="effect") – Type of power curve: “effect” (power vs effect size) or “sample” (power vs sample size).

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

  • title (str, optional) – Plot title. If None, uses a sensible default.

  • xlabel (str, optional) – X-axis label. If None, uses a sensible default.

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

  • color (str, default="#2563eb") – Color for the power curve line.

  • mde_color (str, default="#dc2626") – Color for the MDE 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_mde_line (bool, default=True) – Whether to show vertical line at MDE.

  • 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.

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

Returns:

The axes object (matplotlib) or figure (plotly).

Return type:

matplotlib.axes.Axes or plotly.graph_objects.Figure

Examples

From PowerAnalysis results:

>>> from diff_diff import PowerAnalysis, plot_power_curve
>>> pa = PowerAnalysis(power=0.80)
>>> curve_df = pa.power_curve(n_treated=50, n_control=50, sigma=5.0)
>>> mde_result = pa.mde(n_treated=50, n_control=50, sigma=5.0)
>>> plot_power_curve(curve_df, mde=mde_result.mde)

From simulation results:

>>> from diff_diff import simulate_power, DifferenceInDifferences
>>> results = simulate_power(
...     DifferenceInDifferences(),
...     effect_sizes=[1, 2, 3, 5, 7, 10],
...     n_simulations=200
... )
>>> plot_power_curve(results)

Manual data:

>>> plot_power_curve(
...     effect_sizes=[1, 2, 3, 4, 5],
...     powers=[0.2, 0.5, 0.75, 0.90, 0.97],
...     mde=2.5,
...     target_power=0.80
... )