Power planning

Switchback users can obtain a fitted baseline with source.planning_baseline(metric) and pass it to the three switchback_* solvers. No manually supplied reference effect, covariance, or population certificate is required. The result remains a model-conditioned moment-t approximation; see switchback planning.

Complete-law simulation declarations and oracle solvers remain in increment.semantics.unit_cycle and increment.power.unit_cycle, outside the package-root and ordinary power-planning exports.

ArmPlanningProcedure

ArmPlanningProcedure

No docstring.

SummaryStats

SummaryStats

Canonical reduction of one arm’s raw moments.

var is ALWAYS ddof=1 (unbiased variance of the unit-level values).

Baseline

Baseline

Control-arm assumptions.

Parameters

mean : float Control mean; relative lift is expressed against this. var : float Per-unit outcome variance (control arm, ddof=1 scale). cuped_rho : float |correlation| with a pre-period covariate; reduces variance by (1 - rho^2). Default 0.0. compliance : float Expected first-stage uptake lift under encouragement, in (0, 1]; inflates required n by 1 / compliance**2 since the ITT machinery must detect delta * compliance. Default 1.0. icc : float Intraclass correlation of a factor absorbed via absorb_one_way (categorical CUPED); reduces variance by (1 - icc). See from_absorption. Opposite direction from cluster_icc, which inflates variance. Default 0.0. cluster_icc : float Intraclass correlation of the analyzed score within contributing analyzed clusters; inflates variance through the design effect. avg_cluster_size : float Expected assigned units per randomized cluster; drives recruitment counts. Triggered analyses convert this to an analyzed mean size using avg_cluster_size * trigger_rate / cluster_participation. cluster_size_cv : float Coefficient of variation of analyzed sizes among contributing clusters. cluster_participation : float | None Pilot fraction of recruited clusters contributing analyzed observations. Required for clustered triggered planning, and defaults to 1.0 only for untriggered baselines. trigger_rate : float Share of assigned units expected to become treatment-eligible, in (0, 1]; inflates required n by 1 / trigger_rate. Distinct from compliance, which inflates by the square - use compliance for a diluted-effect readout instead. Default 1.0.

PowerDesign

PowerDesign

Numeric solver controls; policy belongs to ArmPlanningProcedure.

required_sample_size

required_sample_size(relative_lift, baseline, procedure, design, planned_looks)

Compute the sample size needed to detect relative_lift with the given baseline assumptions and design parameters.

n_per_arm is the treatment arm size after ceiling to whole units; power is the actual (slightly >= target) power at that integer size, with the treatment arm’s variance evaluated at relative_lift. mde_relative is the companion minimum detectable effect at that size, None with mde_unavailable_reason when none exists at design.power.

GaussianScoreMixture computes the always-valid Gaussian-model planning approximation the runtime’s asymptotic_mean boundary executes; equal-look batches default to 14 looks. Its crossing enclosures do not certify power for Beta/NIG/NIW runtime likelihood evidence. Registered runtime policies are refused.

For triggered experiments, sequential looks count analyzed units: configure the planning maximum from PowerResult.n_triggered_total, not the assigned-unit n_total.

A relative_lift exactly at the null boundary raises ValueError instead of returning a degenerate sentinel: no finite sample size reaches above-alpha power at zero distance. A one-sided design whose relative_lift lies on the wrong side of the null boundary is refused too - the closed form squares the distance, so it would otherwise size for the reflected effect at ~alpha power.

For a cluster-randomized design, set baseline.cluster_icc and baseline.avg_cluster_size: the design effect inflates effective_var, so the solved n_total is already cluster-corrected, and n_clusters_per_arm/n_clusters_total report the clusters to recruit. Triggered designs also require baseline.cluster_participation: contributing analyzed pilot clusters divided by recruited pilot clusters. Analysis.planning_baseline derives it from the source; manual baselines use those pilot counts. Omitting clustering is anticonservative by the design effect — at ICC 0.05 and 50 units per cluster it under-sizes by 3.45x.

A supplied planned_looks must be a positive integer, validated even when inference is fixed.

achieved_power

achieved_power(n_per_arm, relative_lift, baseline, procedure, design, planned_looks)

Compute achieved power at a fixed arm size under a planning procedure.

power describes the supplied relative_lift: for a plan the runtime decides with the exact binomial risk-ratio test (a conversion or retention metric, unadjusted, unclustered, fixed horizon) it is that decision’s rejection probability at the analyzed integer counts (power_basis "exact" or "approximate"); otherwise the log-ratio planning model with the treatment arm’s variance evaluated at that alternative ("asymptotic"). mde_relative is the companion minimum detectable effect at the same size and target under the same model; when none exists there it is None with mde_unavailable_reason set, and the supplied-effect answer stands. The look schedule resolves as in required_sample_size.

minimum_detectable_effect

minimum_detectable_effect(n_per_arm, baseline, procedure, design, planned_looks)

Compute the minimum detectable relative effect at a fixed arm size.

The answer is the first admissible complier-scale effect reaching design.power under the planning model named by power_basis (see achieved_power); power is that effect’s own power, which exceeds the target when the answer is the admissible interval’s lower endpoint. For a runtime-binomial plan every earlier candidate is excluded by its own failing power or by the monotone closure of the decision’s rejection set, a bound on the runtime’s rejection probability over the whole interval. A target no admissible alternative reaches, or whose answer has no float64 representation, is refused with a power.minimum_detectable_effect.* code. The look schedule resolves as in required_sample_size. For fixed-horizon inference, a target at or below the null’s own crossing probability is also refused: zero distance already qualifies, so no strictly nonzero minimum detectable effect exists.

power_curve

power_curve(n_per_arm, baseline, procedure, relative_lift, target_power, design, units_per_week, planned_looks, max_workers)

Evaluate an ordered fixed-horizon or sequential power or MDE grid.

Provide exactly one of relative_lift and target_power; the omitted quantity is solved per row. procedure may be a sequence to evaluate multiple compiled decision policies while retaining product order. PowerCurvePoint.alpha records each procedure’s derived decision alpha. Each sequential procedure’s look schedule resolves as in required_sample_size and is validated before the grid is built.

SwitchbackBaseline

SwitchbackBaseline

Centered (A, G) SD/correlation summary at the independent planning grain.

A is the contribution at delta_ref; G is its additive-shift slope, with E[G]=1. sd_a**2, sd_g**2, and rho*sd_a*sd_g encode VarA, VarG, CovAG exactly. PSD, including rho=+/-1, is valid. A zero SD requires rho=0 because correlation is then unidentified.

Independent-order summaries average a fixed cycles_per_unit within each unit. Shared-schedule summaries average the fixed shared_roster within each block. These fields are mutually exclusive. Changing assignment, window, cycles, roster, or effect model requires newly derived summaries.

Pilot-estimated moments and reference effects are plug-in estimates. Planning conditions on that fitted baseline, not known population moments.

UnitCycleReference

UnitCycleReference

No docstring.

UnitCycleTApproximation

UnitCycleTApproximation

Explicit historical approximation, without finite-sample calibration.

UnitCycleVarianceEnvelope is an optional prospective declaration, not a variance estimate fitted from the observed experiment. It asserts E[A - delta G] = 0 and Var(mean(A - delta G)) <= V0 / N for the declared independent unit population. See switchback contrasts for the assumptions and the ordinary pilot-fitted alternative.

Field	Contract
kind	"unit_cycle_residual_variance_v1" (default).
assignment	A SwitchbackAssignment with independent Bernoulli orders.
metric	Nonempty metric name.
control_group, treatment_group	Nonempty, distinct group names.
aggregation	"sum" (default).
response_meaning	"retained_total" or "pre_normalized_retained_mean".
estimand	"mean_unit_retained_window_difference" (default).
cycles_per_unit	Strict integer, at least one.
target_population	"independent_unit_population" (default).
effect_model	"additive_retained_aggregate_shift" (default).
residual_variance_upper	Finite, nonnegative V0.
provenance	A ProspectiveAssumptionProvenance; records the declaration, not proof of its truth.

switchback_achieved_power

switchback_achieved_power(n, delta, baseline, procedure)

Noncentral-t planning power at SE=sqrt(V(delta)/n), df=n-1.

A true zero variance is unavailable. Positive variance below float range remains positive for power calculation; only an unrepresentable SE is null. Effects are normalized to binary64 before calculation and recording.

switchback_minimum_detectable_effect

switchback_minimum_detectable_effect(n, baseline, procedure, target_power)

First favorable absolute effect attaining target_power, analytically inverted.

Write delta=null_abs+signx, x>=0, and V=ax²+2bx+c. The derivative of x/sqrt(V) has sign b*x+c. For b<0 the maximum is at -c/b; otherwise the curve increases to sqrt(n/a) (or infinity when a=0). A zero-variance maximum is excluded. c=0 is a constant positive half-line; a=c=0 is wholly degenerate. Asymptote equality is unattained.

switchback_required_blocks_or_units

switchback_required_blocks_or_units(delta, baseline, procedure, target_power)

Smallest integer independent N>=2 meeting target, with df=N-1 each time.

For fixed delta, V(delta)>0 is fixed and the reference is the one-sample Gaussian t experiment with noncentrality sqrt(N)*(delta-null)/sqrt(V). Its one-sided invariant test (two-sided symmetric unbiased test) is most powerful in its class. Ignoring the added observation gives an admissible test at N+1 with the old power; optimality therefore proves nondecreasing power. This argument is for the planning reference, not the branch law. Doubling and integer bisection use that property only for favorable effects. The exact-integer float reference range is capped at 2**53.

unit_cycle_power_lower_bound

unit_cycle_power_lower_bound(envelope, procedure, n, effect_delta)

Supplementary Cantelli bound; zero is not an unattainability claim.