power_analysis#

causalpy.checks.power_analysis(pit_result, effect_sizes=None, n_simulations=200, strategy='grid', n_evaluation_points=5, power_threshold=0.8, n_posterior_samples=1000, random_seed=None)[source]#

Compute a power curve from a completed PlaceboInTime check.

Uses the learned null distribution to simulate what the decision rule would conclude at each hypothetical effect size. Two modes:

  • "grid" — brute-force evaluation at every requested point.

  • "sigmoid" — evaluate at a few points, fit a logistic, and read off the MDE. Faster when you only need the MDE.

Parameters:

  • pit_result (CheckResult) – A completed PlaceboInTime check result containing the learned null distribution in its metadata (keys: "null_samples", "fold_sds", "rope_half_width", "threshold").

  • effect_sizes (list[float] | ndarray | None) – For strategy="grid": the exact effect sizes to evaluate. For strategy="sigmoid": a two-element [min, max] range within which evaluation points are placed. If None, defaults to np.linspace(0, max(4*tau, 3*rope), 8) for grid or [0, max(4*tau, 3*rope)] for sigmoid, where tau is the null SD and rope is the ROPE half-width.

  • n_simulations (int) – Number of Monte Carlo replications per evaluation point.

  • strategy (Literal['grid', 'sigmoid']) – Estimation strategy.

  • n_evaluation_points (int) – Number of evaluation points for the sigmoid strategy.

  • power_threshold (float) – Power level for MDE extraction (sigmoid strategy).

  • n_posterior_samples (int) – Number of posterior draws per simulated experiment.

  • random_seed (int | None) – RNG seed for reproducibility.

Returns:

Contains evaluated points, optional fitted curve, and MDE.

Return type:

PowerCurveResult

Raises:

ValueError – If pit_result does not contain the required metadata.

Notes

At each effect size the function runs n_simulations Monte Carlo replications. Each replication draws a null component from the status-quo posterior, adds the hypothetical effect, simulates a posterior around that total (using the observed fold SDs), and applies the ROPE rule. The fraction of replications that trigger a positive decision is the estimated power.

For the sigmoid strategy a two-parameter logistic is fitted:

\[P(\text{detect} \mid x) = \frac{1}{1 + \exp(-k(x - x_0))}\]

and the MDE is obtained by inverting at the desired power level.

Examples

>>> import causalpy as cp
>>> # After running a PlaceboInTime check:
>>> # result = pipeline.run()
>>> # pit_check = result.sensitivity_results[0]
>>> # curve = cp.checks.power_analysis(pit_check, strategy="sigmoid")
>>> # curve.mde  # Minimum Detectable Effect at 80% power
>>> # curve.plot()