causalis.dgp.causaldata.base

Notes

This module is the lowest-level tabular DGP layer used by higher-level helpers in :mod:causalis.dgp.causaldata.functional and scenario-specific wrappers. Reach for it when you want direct control over the structural equations rather than a pre-packaged example dataset.

Examples

import numpy as np from causalis.dgp.causaldata.base import CausalDatasetGenerator gen = CausalDatasetGenerator( … theta=1.5, … beta_y=np.array([0.7, -0.4]), … beta_d=np.array([1.0, 0.5]), … target_d_rate=0.35, … seed=3141, … include_oracle=True, … k=2, … ) df = gen.generate(200) sorted(col for col in [“y”, “d”, “m”, “cate”] if col in df.columns) [‘cate’, ‘d’, ‘m’, ‘y’]

Low-level generators for single-treatment synthetic causal datasets.

The central class in this module is :class:CausalDatasetGenerator, which builds observational or randomized-style data with binary treatment and optionally exposes oracle quantities such as propensities and potential-outcome means.

Module Contents

Classes

CausalDatasetGenerator

Generate synthetic causal inference datasets with controllable confounding, treatment prevalence, noise, and (optionally) heterogeneous treatment effects.

API

class causalis.dgp.causaldata.base.CausalDatasetGenerator

Generate synthetic causal inference datasets with controllable confounding, treatment prevalence, noise, and (optionally) heterogeneous treatment effects.

Data model (high level)

• confounders X ∈ R^k are drawn from user-specified distributions.

• Binary treatment D is assigned by a logistic model: D ~ Bernoulli( sigmoid(alpha_d + f_d(X) + u_strength_d * U) ), where f_d(X) = (X @ beta_d + g_d(X)) * propensity_sharpness, and U ~ N(0,1) is an optional unobserved confounder.

• Outcome Y depends on treatment and confounders with link determined by outcome_type: outcome_type = “continuous”: Y = alpha_y + f_y(X) + u_strength_y * U + T * tau(X) + ε, ε ~ N(0, sigma_y^2) outcome_type = “binary”: logit P(Y=1|T,X,U) = alpha_y + f_y(X) + u_strength_y * U + T * tau(X) outcome_type = “poisson”: log E[Y|T,X,U] = alpha_y + f_y(X) + u_strength_y * U + T * tau(X) outcome_type = “gamma”: log E[Y|T,X,U] = alpha_y + f_y(X) + u_strength_y * U + T * tau(X) where f_y(X) = X @ beta_y + g_y(X), and tau(X) is either constant theta or a user function.

Returned columns

• y: outcome

• d: binary treatment (0/1)

• x1..xk (or user-provided names)

• m: true propensity P(T=1 | X) marginalized over U

• m_obs: realized propensity P(T=1 | X, U)

• tau_link: tau(X) on the structural (link) scale

• g0: E[Y | X, T=0] on the natural outcome scale marginalized over U .,9

• g1: E[Y | X, T=1] on the natural outcome scale marginalized over U

• cate: g1 - g0 (conditional average treatment effect on the natural outcome scale)

Notes on effect scale:

• For “continuous”, theta (or tau(X)) is an additive mean difference, so tau_link == cate.

• For “binary”, tau acts on the log-odds scale. cate is reported as a risk difference.

• For “poisson” and “gamma”, tau acts on the log-mean scale. cate is reported on the mean scale.

Parameters

theta : float, default=1.0 Constant treatment effect used if tau is None. tau : callable, optional Function tau(X) -> array-like shape (n,) for heterogeneous effects. beta_y : array-like, optional Linear coefficients of confounders in the outcome baseline f_y(X). beta_d : array-like, optional Linear coefficients of confounders in the treatment score f_d(X). g_y : callable, optional Nonlinear/additive function g_y(X) -> (n,) added to the outcome baseline. g_d : callable, optional Nonlinear/additive function g_d(X) -> (n,) added to the treatment score. alpha_y : float, default=0.0 Outcome intercept (natural scale for continuous; log-odds for binary; log-mean for Poisson/Gamma). alpha_d : float, default=0.0 Treatment intercept (log-odds). If target_d_rate is set, alpha_d is auto-calibrated. sigma_y : float, default=1.0 Std. dev. of the Gaussian noise for continuous outcomes. outcome_type : {“continuous”, “binary”, “poisson”, “gamma”, “tweedie”}, default=”continuous” Outcome family and link as defined above. confounder_specs : list of dict, optional Schema for generating confounders. See _gaussian_copula for details. k : int, default=5 Number of confounders when confounder_specs is None. Defaults to independent N(0,1). x_sampler : callable, optional Custom sampler (n, k, seed) -> X ndarray of shape (n,k). Overrides confounder_specs. use_copula : bool, default=False If True and confounder_specs provided, use Gaussian copula for X. copula_corr : array-like, optional Correlation matrix for copula. target_d_rate : float, optional Target treatment prevalence (propensity mean). Calibrates alpha_d. u_strength_d : float, default=0.0 Strength of the unobserved confounder U in treatment assignment. u_strength_y : float, default=0.0 Strength of the unobserved confounder U in the outcome. propensity_sharpness : float, default=1.0 Scales the X-driven treatment score to adjust positivity difficulty. seed : int, optional Random seed for reproducibility.

Attributes

rng : numpy.random.Generator Internal RNG seeded from seed.

Notes

Oracle outputs are reported on the natural outcome scale:

• m is the treatment propensity marginalized over latent noise.

• g0 and g1 are mean potential outcomes on the observed outcome scale.

• cate is always g1 - g0 on that same natural scale, even when the structural treatment effect is specified on a link scale such as log-odds or log-mean.

Examples

import numpy as np gen = CausalDatasetGenerator( … theta=0.8, … beta_y=np.array([0.5, -0.2, 0.1]), … beta_d=np.array([0.8, 0.4, -0.3]), … target_d_rate=0.4, … outcome_type=”continuous”, … seed=123, … k=3, … ) df = gen.generate(1000) float(df[“d”].mean()) > 0.0 True “cate” in df.columns True

theta: float

1.0

tau: Optional[Callable[[numpy.ndarray], numpy.ndarray]]

None

beta_y: Optional[numpy.ndarray]

None

beta_d: Optional[numpy.ndarray]

None

g_y: Optional[Callable[[numpy.ndarray], numpy.ndarray]]

None

g_d: Optional[Callable[[numpy.ndarray], numpy.ndarray]]

None

alpha_y: float

0.0

alpha_d: float

0.0

sigma_y: float

1.0

outcome_type: str

‘continuous’

confounder_specs: Optional[List[Dict[str, Any]]]

None

k: int

5

x_sampler: Optional[Callable[[int, int, int], numpy.ndarray]]

None

use_copula: bool

False

copula_corr: Optional[numpy.ndarray]

None

target_d_rate: Optional[float]

None

u_strength_d: float

0.0

u_strength_y: float

0.0

propensity_sharpness: float

1.0

score_bounding: Optional[float]

None

alpha_zi: float

None

beta_zi: Optional[numpy.ndarray]

None

g_zi: Optional[Callable[[numpy.ndarray], numpy.ndarray]]

None

u_strength_zi: float

0.0

tau_zi: Optional[Callable[[numpy.ndarray], numpy.ndarray]]

None

pos_dist: str

‘gamma’

gamma_shape: float

2.0

lognormal_sigma: float

1.0

include_oracle: bool

True

seed: Optional[int]

None

rng: numpy.random.Generator

‘field(…)’

__post_init__()

Initialize RNG and validate configuration.

generate(n: int, U: Optional[numpy.ndarray] = None) → pandas.DataFrame

Draw a synthetic dataset of size n.

Parameters

n : int Number of samples to generate. U : numpy.ndarray, optional Unobserved confounder. If None, generated from N(0,1).

Returns

pandas.DataFrame The generated dataset with outcome ‘y’, treatment ‘d’, confounders, and oracle ground-truth columns.

to_causal_data(n: int, confounders: Optional[Union[str, List[str]]] = None) → causalis.dgp.causaldata.CausalData

Generate a dataset and convert it to a CausalData object.

Parameters

n : int Number of samples to generate. confounders : str or list of str, optional List of confounder column names to include. If None, automatically detects numeric confounders.

Returns

CausalData A CausalData object containing the generated dataset.

oracle_nuisance(num_quad: int = 21)

Return nuisance functions (m(x), g0(x), g1(x)) compatible with IRM.

Parameters

num_quad : int, default=21 Number of quadrature points for marginalizing over U.

Returns

dict Dictionary of callables mapping X to nuisance values.