PlaceboInTime#

class causalpy.checks.placebo_in_time.PlaceboInTime[source]#

Placebo-in-time sensitivity check with hierarchical null model.

Shifts the treatment time backward into the pre-intervention period to create n_folds placebo experiments. Extracts the posterior cumulative impact from each fold, then fits a hierarchical Bayesian model to characterise the “status quo” distribution of effects when no intervention occurred. The actual intervention’s cumulative effect is compared against this learned null.

When expected_effect_prior and rope_half_width are provided, additionally computes Bayesian assurance (operating characteristics) via simulation.

Parameters:

  • n_folds (int) – Number of placebo folds to create. Must be >= 1.

  • experiment_factory (Any | None) – Custom factory (data, treatment_time) -> BaseExperiment. If None (default), the factory is derived from the pipeline’s experiment_config. Required for standalone (non-pipeline) use.

  • sample_kwargs (dict[str, Any] | None) – MCMC settings for the hierarchical status-quo model. Defaults to {"draws": 1000, "chains": 4, "target_accept": 0.97}.

  • threshold (float) – Probability cutoff. Used both for passed (P(actual effect outside null) must exceed this) and for the ROPE decision rule when computing assurance.

  • prior_scale (float) – Multiplier for auto-computed prior widths on the hierarchical model. The priors are mu ~ Normal(center, 5 * prior_scale * data_scale) and tau ~ HalfNormal(2 * prior_scale * data_scale).

  • expected_effect_prior (Any | None) – Prior belief about the true total effect under the alternative hypothesis. Accepts any object with an .rvs(n) method (PreliZ, scipy) or a numpy array of pre-drawn samples. When provided together with rope_half_width, assurance analysis runs automatically.

  • rope_half_width (float | None) – Half-width of the ROPE interval [-rope, +rope]. Required when expected_effect_prior is provided.

  • n_design_replications (int | None) – Number of simulation replications for assurance. Defaults to min(theta_new.size, expected_effect_samples.size).

  • random_seed (int | None) – RNG seed for the assurance simulation.

Examples

>>> import causalpy as cp
>>> check = cp.checks.PlaceboInTime(n_folds=3)

Methods

PlaceboInTime.__init__([n_folds, ...])

PlaceboInTime.bayesian_rope_decision(...)

Apply a ROPE-based Bayesian decision rule.

PlaceboInTime.run(experiment[, context])

Run placebo-in-time analysis with hierarchical null model.

PlaceboInTime.validate(experiment)

Check the experiment is compatible with PlaceboInTime.

Attributes

applicable_methods

__init__(n_folds=3, experiment_factory=None, sample_kwargs=None, threshold=0.95, prior_scale=1.0, expected_effect_prior=None, rope_half_width=None, n_design_replications=None, random_seed=None)[source]#
Parameters:

  • n_folds (int)

  • experiment_factory (Any | None)

  • sample_kwargs (dict[str, Any] | None)

  • threshold (float)

  • prior_scale (float)

  • expected_effect_prior (Any | None)

  • rope_half_width (float | None)

  • n_design_replications (int | None)

  • random_seed (int | None)

Return type:

None

classmethod __new__(*args, **kwargs)#