causalis.dgp.rct_causal_data

Synthetic randomized experiments for RctCausalData and CUPED benchmarks.

Module Contents

Functions

generate_rct_causal_data

Generate multiple outcomes under a shared randomized assignment.

API

causalis.dgp.rct_causal_data.generate_rct_causal_data(n: int = 10000, *, n_treatments: int = 3, n_outcomes: int = 3, outcome_specs: list[dict[str, Any]] | None = None, k: int = 2, confounder_specs: list[dict[str, Any]] | None = None, target_d_rate: list[float] | numpy.ndarray | None = None, treatment_encoding: Literal[one_hot, binary] = 'one_hot', d_names: list[str] | None = None, seed: int | None = 42, include_user_id: bool = True, include_oracle: bool = False, return_causal_data: bool = True) → causalis.data_contracts.rct_causal_data.RctCausalData | pandas.DataFrame

Generate multiple outcomes under a shared randomized assignment.

Reuses MultiCausalDatasetGenerator’s covariate sampling, effect normalization, outcome-family sampling, and natural-scale oracle methods. Covariates are generated before treatment and are suitable for CUPED. Assignment is independent of covariates and outcome noise. Separate RNG streams keep assignment/covariates unchanged when outcome settings change. Outcomes are conditionally independent given covariates and assignment.

Parameters

n : int, default 10000 Number of observations. Must be at least n_treatments. n_treatments : int, default 3 Number of arms including control, at least two. n_outcomes : int, default 3 Number of default continuous outcomes, named y1, y2, … . Ignored when outcome_specs is provided; its length determines the outcome count. outcome_specs : list of dict, optional One configuration per outcome. Supported keys (internal DGP meanings): name (default y1, y2, …), outcome_type (continuous, binary, poisson, gamma; normal aliases continuous), alpha_y (default 0), beta_y (one coefficient per expanded covariate; defaults to 0.5 / sqrt(number of covariates)), theta (default 0.5), sigma_y (default 1), and gamma_shape (default 2). theta is scalar for all active arms, a length K-1 active-arm vector, or a length K vector including control. Effects are additive on the identity/logit/log link, not necessarily on the natural outcome scale. Covariate distributions use the internal confounder_specs schema. k : int, default 2 Number of standard normal covariates when no specs are supplied. confounder_specs : list of dict, optional Internal DGP distribution specs (normal, uniform, bernoulli, gamma, categorical, etc.). Categorical covariates expand into dummy columns. target_d_rate : array-like, optional Strictly positive allocation weights of length K, normalized to sum 1. Defaults to equal probabilities. Assignments are IID, not forced to exact counts. A missing arm raises an error; increase n or its weight. treatment_encoding : {“one_hot”, “binary”}, default “one_hot” Full one-hot encoding with first column as control, or a single 0/1 column for a two-arm experiment. Binary requires n_treatments=2. d_names : list of str, optional Treatment columns, default d_0, d_1, … (one-hot), or [“d”] (binary). seed : int or None, default 42 Seed for reproducible independent random streams. include_user_id : bool, default True Include a unique int64 user_id column. include_oracle : bool, default False Add m_, g_, and cate_<active_arm> columns to DataFrame output. g is the conditional potential-outcome mean on the natural scale; cate is its difference from control. Binary oracle arm labels are 0 and 1. Contract output excludes oracle columns, as required by RctCausalData’s selected-column policy. return_causal_data : bool, default True Return RctCausalData; False returns a DataFrame. Both retain small df.attrs["rct"] metadata with allocation probabilities, arm labels, outcome families, and link-scale effects relative to control.

Notes

Samples that have constant or identical columns can fail contract validation, especially tiny samples with discrete outcomes. No outcomes are redrawn to force validation. DataFrame output can be used to inspect such samples. Generation uses column arrays and one assignment vector; it does not create a rows-by-outcomes-by-arms potential-outcome tensor. Oracle columns are optional because they can be much larger than the observed dataset.

Examples

data = generate_rct_causal_data(n=1000, seed=7) data.Y.shape, data.D.shape ((1000, 3), (1000, 3)) from causalis.scenarios.cuped import CUPEDModel model = CUPEDModel().fit(data, covariates=[“x1”, “x2”], run_checks=False) estimates = model.estimate() estimates[“y1”][“d_1”].treatment ‘d_1’