# `causalis.dgp.causaldata.functional`

## Notes

Use this module when you want a ready-made synthetic dataset without specifying every structural component manually. For finer control over the DGP, instantiate `CausalDatasetGenerator` directly instead.

## Examples

> > > from causalis.dgp.causaldata.functional import generate_rct, obs_linear_effect rct = generate_rct(n=500, outcome_type=”normal”, return_causal_data=True) rct.outcome, rct.treatment (‘y’, ‘d’) obs = obs_linear_effect(n=500, theta=1.0, target_d_rate=0.3) {“y”, “d”}.issubset(obs.columns) True

High-level helpers for single-treatment synthetic causal datasets.

This module provides convenient wrappers around :class:`causalis.dgp.causaldata.base.CausalDatasetGenerator` for common benchmarking setups such as classic A/B tests, observational confounding, and CUPED-oriented examples with pre-period covariates.

## Module Contents

### Functions

`generate_rct` | Generate an RCT dataset with randomized treatment assignment.
`generate_classic_rct` | Generate a classic RCT dataset with three binary confounders: platform_ios, country_usa, and source_paid.
`classic_rct_gamma` | Generate a classic RCT dataset with three binary confounders and a gamma outcome.
`obs_linear_effect` | Generate an observational dataset with linear effects of confounders and a constant treatment effect.
`make_cuped_tweedie` | Tweedie-like DGP with mixed marginals and structured HTE. Features many zeros and a heavy right tail. Suitable for CUPED benchmarking.
`generate_cuped_binary` | Binary CUPED-oriented DGP with richer confounders and structured HTE.
`make_gold_linear` | A standard linear benchmark with moderate confounding. Based on the benchmark scenario in docs/research/dgp_benchmarking.ipynb.

### API

causalis.dgp.causaldata.functional.generate_rct(n: int = 20000, split: float = 0.5, random_state: Optional[int] = 42, outcome_type: str = 'binary', outcome_params: Optional[Dict] = None, confounder_specs: Optional[List[Dict[str, Any]]] = None, k: int = 0, x_sampler: Optional[Callable[[int, int, int], numpy.ndarray]] = None, add_ancillary: bool = True, deterministic_ids: bool = False, add_pre: bool = True, pre_name: str = 'y_pre', pre_corr: float = 0.7, prognostic_scale: float = 1.0, beta_y: Optional[Union[List[float], numpy.ndarray]] = None, g_y: Optional[Callable[[numpy.ndarray], numpy.ndarray]] = None, use_prognostic: Optional[bool] = None, include_oracle: bool = True, return_causal_data: bool = False) → Union[pandas.DataFrame, causalis.dgp.causaldata.CausalData]

  Generate an RCT dataset with randomized treatment assignment.

  Uses `CausalDatasetGenerator` internally, ensuring treatment is independent of X. Specifically designed for benchmarking variance reduction techniques like CUPED.

  Notes on effect scale

  How `outcome_params` maps into the structural effect:

  - outcome_type=”normal”: treatment shifts the mean by (mean[“B”] - mean[“A”]) on the outcome scale.

  - outcome_type=”binary”: treatment shifts the log-odds by (logit(p_B) - logit(p_A)).

  - outcome_type=”poisson” or “gamma”: treatment shifts the log-mean by log(lam_B / lam_A).

  Ancillary columns (if add_ancillary=True) are generated from baseline confounders X only, avoiding outcome leakage and post-treatment adjustment issues.

  Parameters

  n : int, default=20_000 Number of samples to generate. split : float, default=0.5 Proportion of samples assigned to the treatment group. random_state : int, optional Random seed for reproducibility. outcome_type : {“binary”, “normal”, “poisson”, “gamma”}, default=”binary” Distribution family of the outcome. outcome_params : dict, optional Parameters defining baseline rates/means and treatment effects. e.g., {“p”: {“A”: 0.1, “B”: 0.12}} for binary, or {“shape”: 2.0, “scale”: {“A”: 1.0, “B”: 1.1}} for poisson/gamma. confounder_specs : list of dict, optional Schema for confounder distributions. k : int, default=0 Number of confounders if specs not provided. x_sampler : callable, optional Custom sampler for confounders. add_ancillary : bool, default=True Whether to add descriptive columns like ‘age’, ‘platform’, etc. deterministic_ids : bool, default=False Whether to generate deterministic user IDs. add_pre : bool, default=True Whether to generate a pre-period covariate (`y_pre`). pre_name : str, default=”y_pre” Name of the pre-period covariate column. pre_corr : float, default=0.7 Target correlation between `y_pre` and the outcome Y in the control group. prognostic_scale : float, default=1.0 Scale of the prognostic signal derived from confounders. include_oracle : bool, default=True Whether to include oracle ground-truth columns like ‘cate’, ‘m’, etc. return_causal_data : bool, default=False Whether to return a `CausalData` object instead of a `pandas.DataFrame`.

  Returns

  pandas.DataFrame or CausalData Synthetic RCT dataset.

  Examples

  > > > from causalis.dgp.causaldata.functional import generate_rct data = generate_rct( … n=1000, … outcome_type=”binary”, … outcome_params={“p”: {“A”: 0.10, “B”: 0.12}}, … add_pre=True, … return_causal_data=True, … ) data.treatment, data.outcome (‘d’, ‘y’) “y_pre” in data.df.columns True {“g0”, “g1”, “cate”}.issubset(data.df.columns) True

causalis.dgp.causaldata.functional.generate_classic_rct(n: int = 10000, split: float = 0.5, random_state: Optional[int] = 42, outcome_params: Optional[Dict] = None, add_pre: bool = False, beta_y: Optional[Union[List[float], numpy.ndarray]] = None, outcome_depends_on_x: bool = True, prognostic_scale: float = 1.0, pre_corr: float = 0.7, return_causal_data: bool = False, add_ancillary: bool = False, deterministic_ids: bool = False, include_oracle: bool = True, **kwargs) → Union[pandas.DataFrame, causalis.dgp.causaldata.CausalData]

  Generate a classic RCT dataset with three binary confounders: platform_ios, country_usa, and source_paid.

  Parameters

  n : int, default=10_000 Number of samples to generate. split : float, default=0.5 Proportion of samples assigned to the treatment group. random_state : int, optional Random seed for reproducibility. outcome_params : dict, optional Parameters defining baseline rates/means and treatment effects. e.g., {“p”: {“A”: 0.1, “B”: 0.15}} for binary. add_pre : bool, default=False Whether to generate a pre-period covariate (`y_pre`). beta_y : array-like, optional Linear coefficients for confounders in the outcome model. outcome_depends_on_x : bool, default=True Whether to add default effects for confounders if beta_y is None. prognostic_scale : float, default=1.0 Scale of nonlinear prognostic signal (passed to generate_rct). pre_corr : float, default=0.7 Target correlation for y_pre (passed to generate_rct). return_causal_data : bool, default=False Whether to return a `CausalData` object instead of a `pandas.DataFrame`. add_ancillary : bool, default=False Whether to add standard ancillary columns (age, platform, etc.). deterministic_ids : bool, default=False Whether to generate deterministic user IDs. include_oracle : bool, default=True Whether to include oracle ground-truth columns like ‘cate’, ‘propensity’, etc. **kwargs : Additional arguments passed to `generate_rct`.

  Returns

  pandas.DataFrame or CausalData Synthetic classic RCT dataset.

causalis.dgp.causaldata.functional.classic_rct_gamma(n: int = 10000, split: float = 0.5, random_state: Optional[int] = 42, outcome_params: Optional[Dict] = None, add_pre: bool = False, beta_y: Optional[Union[List[float], numpy.ndarray]] = None, outcome_depends_on_x: bool = True, prognostic_scale: float = 1.0, pre_corr: float = 0.7, add_ancillary: bool = True, deterministic_ids: bool = False, include_oracle: bool = True, return_causal_data: bool = False, **kwargs) → Union[pandas.DataFrame, causalis.dgp.causaldata.CausalData]

  Generate a classic RCT dataset with three binary confounders and a gamma outcome.

  The gamma outcome uses a log-mean link, so treatment effects are multiplicative on the mean scale. The default parameters are chosen to resemble a skewed real-world metric (e.g., spend or revenue).

  Parameters

  n : int, default=10_000 Number of samples to generate. split : float, default=0.5 Proportion of samples assigned to the treatment group. random_state : int, optional Random seed for reproducibility. outcome_params : dict, optional Gamma parameters, e.g. {“shape”: 2.0, “scale”: {“A”: 15.0, “B”: 16.5}}. Mean = shape * scale. add_pre : bool, default=False Whether to generate a pre-period covariate (`y_pre`). beta_y : array-like, optional Linear coefficients for confounders in the log-mean outcome model. outcome_depends_on_x : bool, default=True Whether to add default effects for confounders if beta_y is None. prognostic_scale : float, default=1.0 Scale of nonlinear prognostic signal. pre_corr : float, default=0.7 Target correlation for y_pre with post-outcome in control group. add_ancillary : bool, default=True Whether to add standard ancillary columns (age, platform, etc.). deterministic_ids : bool, default=False Whether to generate deterministic user IDs. include_oracle : bool, default=True Whether to include oracle ground-truth columns like ‘cate’, ‘propensity’, etc. return_causal_data : bool, default=False Whether to return a `CausalData` object instead of a `pandas.DataFrame`. **kwargs : Additional arguments passed to `generate_rct` (e.g., pre_name, g_y, use_prognostic).

  Returns

  pandas.DataFrame or CausalData Synthetic classic RCT dataset with gamma outcome.

causalis.dgp.causaldata.functional.obs_linear_effect(n: int = 10000, theta: float = 1.0, outcome_type: str = 'continuous', sigma_y: float = 1.0, target_d_rate: Optional[float] = None, confounder_specs: Optional[List[Dict[str, Any]]] = None, beta_y: Optional[numpy.ndarray] = None, beta_d: Optional[numpy.ndarray] = None, random_state: Optional[int] = 42, k: int = 0, x_sampler: Optional[Callable[[int, int, int], numpy.ndarray]] = None, include_oracle: bool = True, add_ancillary: bool = False, deterministic_ids: bool = False) → pandas.DataFrame

  Generate an observational dataset with linear effects of confounders and a constant treatment effect.

  Parameters

  n : int, default=10_000 Number of samples to generate. theta : float, default=1.0 Constant treatment effect. outcome_type : {“continuous”, “binary”, “poisson”, “gamma”}, default=”continuous” Family of the outcome distribution. sigma_y : float, default=1.0 Noise level for continuous outcomes. target_d_rate : float, optional Target treatment prevalence (propensity mean). confounder_specs : list of dict, optional Schema for confounder distributions. beta_y : array-like, optional Linear coefficients for confounders in the outcome model. beta_d : array-like, optional Linear coefficients for confounders in the treatment model. random_state : int, optional Random seed for reproducibility. k : int, default=0 Number of confounders if specs not provided. x_sampler : callable, optional Custom sampler for confounders. include_oracle : bool, default=True Whether to include oracle ground-truth columns like ‘cate’, ‘m’, etc. add_ancillary : bool, default=False If True, adds standard ancillary columns (age, platform, etc.). deterministic_ids : bool, default=False If True, generates deterministic user IDs.

  Returns

  pandas.DataFrame Synthetic observational dataset.

  Notes

  This helper is a lightweight observational benchmark:

  - treatment is not randomized unless `beta_d` is zero and `target_d_rate` forces a near-constant propensity;

  - oracle columns such as `m` and `cate` are available when `include_oracle=True`;

  - the treatment effect is constant on the structural link scale, so heterogeneity only enters through the outcome family transformation.

  Examples

  > > > from causalis.dgp.causaldata.functional import obs_linear_effect df = obs_linear_effect( … n=1000, … theta=1.0, … target_d_rate=0.35, … k=3, … random_state=3141, … ) sorted(col for col in [“y”, “d”, “m”, “cate”] if col in df.columns) [‘cate’, ‘d’, ‘m’, ‘y’]

causalis.dgp.causaldata.functional.make_cuped_tweedie(n: int = 10000, seed: int = 42, add_pre: bool = True, pre_name: str = 'y_pre', pre_target_corr: float = 0.6, pre_spec: Optional[causalis.dgp.causaldata.preperiod.PreCorrSpec] = None, include_oracle: bool = False, return_causal_data: bool = True, theta_log: float = 0.2) → Union[pandas.DataFrame, causalis.dgp.causaldata.CausalData]

  Tweedie-like DGP with mixed marginals and structured HTE. Features many zeros and a heavy right tail. Suitable for CUPED benchmarking.

  Parameters

  n : int, default=10000 Number of samples to generate. seed : int, default=42 Random seed. add_pre : bool, default=True Whether to add a pre-period covariate ‘y_pre’. pre_name : str, default=”y_pre” Name of the pre-period covariate column. pre_target_corr : float, default=0.6 Target correlation between y_pre and post-outcome y in control group. pre_spec : PreCorrSpec, optional Detailed specification for pre-period calibration (transform, method, etc.). If provided, `pre_target_corr` is ignored in favor of `pre_spec.target_corr`. include_oracle : bool, default=False Whether to include oracle ground-truth columns like ‘cate’, ‘propensity’, etc. return_causal_data : bool, default=True Whether to return a CausalData object. theta_log : float, default=0.2 The log-uplift theta parameter for the treatment effect.

  Returns

  pd.DataFrame or CausalData

causalis.dgp.causaldata.functional.generate_cuped_binary(n: int = 10000, seed: int = 42, add_pre: bool = True, pre_name: str = 'y_pre', pre_target_corr: float = 0.65, pre_spec: Optional[causalis.dgp.causaldata.preperiod.PreCorrSpec] = None, include_oracle: bool = True, return_causal_data: bool = True, theta_logit: float = 0.38) → Union[pandas.DataFrame, causalis.dgp.causaldata.CausalData]

  Binary CUPED-oriented DGP with richer confounders and structured HTE.

  Designed for CUPED benchmarking with randomized treatment and a calibrated pre-period covariate while preserving exact oracle cate under include_oracle.

  Parameters

  n : int, default=10000 Number of samples to generate. seed : int, default=42 Random seed. add_pre : bool, default=True Whether to add a pre-period covariate. pre_name : str, default=”y_pre” Name of the pre-period covariate column. pre_target_corr : float, default=0.65 Target correlation between y_pre and post-outcome y in the control group. pre_spec : PreCorrSpec, optional Detailed specification for pre-period calibration. If provided, `pre_target_corr` is ignored in favor of `pre_spec.target_corr`. include_oracle : bool, default=True Whether to include oracle columns like m, g0, g1, cate. return_causal_data : bool, default=True Whether to return a CausalData object. theta_logit : float, default=0.38 Baseline log-odds uplift scale for heterogeneous treatment effects.

  Returns

  pd.DataFrame or CausalData

causalis.dgp.causaldata.functional.make_gold_linear(n: int = 10000, seed: int = 42) → causalis.dgp.causaldata.CausalData

  A standard linear benchmark with moderate confounding. Based on the benchmark scenario in docs/research/dgp_benchmarking.ipynb.