causalis.shared.rct_design.design

Normal-approximation RCT planning, with optional historical-control CUPED fits.

Module Contents

Functions

calculate_sample_size	Plan separate experiments for target MDEs of one outcome.
calculate_mde	Calculate absolute and relative MDE for a fixed total future sample size.

API

causalis.shared.rct_design.design.calculate_sample_size(data: causalis.data_contracts.rct_causal_data.RctCausalData, *, outcome: str, covariates: collections.abc.Sequence[str] | None = None, scenario: Literal[default, user] = 'default', mde_type: Literal[absolute, relative] | None = None, mde: collections.abc.Sequence[float] | None = None, allocation: collections.abc.Mapping[str, float] | None = None, alpha: float = 0.05, power: float = 0.8, include_details: bool = False) → pandas.DataFrame

Plan separate experiments for target MDEs of one outcome.

Parameters

data : RctCausalData Past RCT. Only control rows estimate the baseline and residual variance; all declared groups define the future experiment. outcome : str Required name of one declared outcome. covariates : Sequence[str], optional Explicit pre-treatment confounders for CUPED. Omitted, None, or [] uses unadjusted sample variance, even if data declares confounders. scenario : {“default”, “user”} Default plans relative targets [0.5, 1, 5, 10, 20] percent and rejects custom mde or mde_type. User requires both arguments explicitly. mde_type : {“relative”, “absolute”}, optional In user mode, percentages (1 means 1%) or differences in outcome units. Relative targets require a positive historical control mean. mde : Sequence[float], optional In user mode, non-empty finite positive targets. Order and duplicates are preserved. Each target defines a separate candidate experiment. allocation : Mapping[str, float], optional Positive shares summing to one for every group; defaults to equal shares. Keys are one-hot column names or ‘=0’ / ‘=1’ for binary treatment. Historical allocation is never reused implicitly. alpha, power : float Per-comparison significance and target power; require 0 < alpha < power < 1. include_details : bool Append historical fit diagnostics and achieved power. Defaults to False.

Returns

pandas.DataFrame One row per target and active arm, in input target and contract arm order. Compact columns: outcome, control, treatment, mde_relative, mde_absolute, n_control, n_treatment, n_total. Both MDE columns describe the requested target; relative values are percentages, or NaN for nonpositive baselines in absolute mode. Sizes are integers and other values are not rounded. Details append baseline_mean, variance_raw, variance_used, variance_reduction_pct, n_reference, alpha, power, achieved_power. Within each target, all rows share one experiment sized to meet every arm’s target power. n_total counts the shared control once; do not sum rows.

Notes

Estimates historical-control variance once for all targets. Without covariates, uses sample variance (ddof=1) without regression. With covariates, uses CUPED residual variance SSE / (n_reference - design rank). The two-sided normal approximation assumes independent randomization units and the same variance in all future groups. Binary outcomes also use this fixed-variance approximation. This is a planning estimate, not an exact finite-sample power guarantee for CUPEDModel. There is no multiple-testing correction or joint-power calculation. Each group’s continuous size is rounded up; this is conservative, not a search for the smallest integer allocation. Control-constant covariates are dropped with a warning; singular designs, non-positive residual degrees of freedom, and zero residual variance raise ValueError. Negative estimated variance reduction is retained.

causalis.shared.rct_design.design.calculate_mde(data: causalis.data_contracts.rct_causal_data.RctCausalData, *, outcome: str, sample_size: int, covariates: collections.abc.Sequence[str] | None = None, allocation: collections.abc.Mapping[str, float] | None = None, alpha: float = 0.05, power: float = 0.8, include_details: bool = False) → pandas.DataFrame

Calculate absolute and relative MDE for a fixed total future sample size.

Parameters

data : RctCausalData Historical RCT. Only control rows estimate the baseline and variance. outcome : str Required name of one declared outcome. sample_size : int Positive integer total across all future groups, at most 2**53. Allocate by largest remainders; ties follow contract order, control first. Every group must receive at least one participant. covariates : Sequence[str], optional Explicit pre-treatment confounders for CUPED. Omitted, None, or [] uses unadjusted sample variance, even if data declares confounders. allocation : Mapping[str, float], optional Positive shares summing to one for every declared group; defaults to equal shares. Keys are one-hot names or ‘=0’ / ‘=1’ for binary treatment. Historical allocation is never reused implicitly. alpha, power : float Per-comparison significance and target power; require 0 < alpha < power < 1. include_details : bool Append historical fit and design diagnostics. Defaults to False.

Returns

pandas.DataFrame One row per active arm in contract order. Compact columns: outcome, control, treatment, mde_relative, mde_absolute, n_control, n_treatment, n_total. Absolute MDE uses outcome units; relative MDE is a percentage (1 means 1%) of the raw historical control mean, or NaN if it is <= 0. Sizes are integers and other values are not rounded. Details append baseline_mean, variance_raw, variance_used, variance_reduction_pct, n_reference, alpha, power. All rows describe the same experiment; n_total counts shared control once and must not be summed across rows.

Notes

Uses the same deterministic, two-sided normal power calculation and historical variance assumptions as calculate_sample_size. With no covariates, classic planning uses sample variance (ddof=1) without regression. With covariates, CUPED uses residual variance SSE / (n_reference - design rank). Future arms share that variance, including for binary outcomes. Power is per comparison, without multiple-testing correction or a joint detection guarantee. Constant control covariates are dropped with a warning; invalid fits raise ValueError.