causalis.dgp.causaldata_instrumental.base

Examples

from causalis.dgp.causaldata_instrumental.base import InstrumentalGenerator gen = InstrumentalGenerator(k=2, first_stage=1.5, seed=3141) df = gen.generate(500) {“y”, “d”, “z”, “x1”, “x2”}.issubset(df.columns) True

Low-level generators for instrumental-variable synthetic causal datasets.

The central class in this module is :class:InstrumentalGenerator, which builds cross-sectional datasets with one binary instrument, one binary endogenous treatment, optional observed confounders, and optional latent confounding between treatment and outcome.

Module Contents

Classes

InstrumentalGenerator

Generate synthetic datasets for binary instrumental-variable estimation.

Data

IVCausalDatasetGenerator

API

class causalis.dgp.causaldata_instrumental.base.InstrumentalGenerator

Bases: causalis.dgp.causaldata.base.CausalDatasetGenerator

Generate synthetic datasets for binary instrumental-variable estimation.

The generated structural system is:

  • X is sampled with the same confounder machinery as :class:~causalis.dgp.causaldata.base.CausalDatasetGenerator.

  • Z is a binary instrument generated from P(Z=1|X).

  • D is a binary endogenous treatment generated from P(D=1|Z,X,U).

  • Y depends on D, X, and optionally the latent U, but has no direct dependence on Z.

Parameters inherited from CausalDatasetGenerator keep their usual meaning for the outcome equation and the non-instrument part of the treatment equation. In particular, beta_d, g_d, alpha_d, target_d_rate, and u_strength_d affect treatment assignment.

Parameters

instrument_name : str, default=”z” Column name for the binary instrument. first_stage : float, default=1.25 Additive log-odds effect of Z on treatment assignment. Positive values make the instrument encourage treatment. beta_z : array-like, optional Linear coefficients of confounders in the instrument propensity. g_z : callable, optional Nonlinear instrument score g_z(X) -> shape (n,). alpha_z : float, default=0.0 Instrument propensity intercept. If target_z_rate is set, this is calibrated on each generated sample. target_z_rate : float, optional Target marginal instrument rate. Defaults to 0.5. instrument_sharpness : float, default=1.0 Multiplier on the X-driven instrument score. include_oracle : bool, default=True Whether to include oracle columns for IV nuisance functions and treatment potential-outcome means.

Notes

With include_oracle=True, returned oracle columns include:

  • m: instrument propensity P(Z=1|X).

  • r_z0 and r_z1: first-stage nuisances P(D=1|Z=0,X) and P(D=1|Z=1,X).

  • g_z0 and g_z1: reduced-form nuisances E[Y|Z=0,X] and E[Y|Z=1,X).

  • iv_first_stage and iv_reduced_form: conditional differences in the first stage and reduced form.

  • late_x and late: conditional and sample-average Wald ratios.

  • g_d0, g_d1, and cate: treatment potential-outcome means and their natural-scale contrast.

instrument_name: str

‘z’

first_stage: float

1.25

beta_z: Optional[numpy.ndarray]

None

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

None

alpha_z: float

0.0

target_z_rate: Optional[float]

0.5

instrument_sharpness: float

1.0

__post_init__() → None

Initialize RNG and validate IV-specific configuration.

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

Draw a synthetic IV dataset of size n.

Parameters

n : int Number of samples to generate. U : numpy.ndarray, optional Latent confounder. If omitted, sampled from N(0, 1).

Returns

pandas.DataFrame Generated dataset with outcome y, treatment d, instrument z (or instrument_name), confounders, and optional oracle columns.

to_iv_causal_data(n: int, confounders: Optional[Union[str, List[str]]] = None) → causalis.data_contracts.iv_causal_data.IVCausalData

Generate a dataset and convert it to :class:IVCausalData.

Oracle columns are intentionally not included as confounders when confounders is omitted.

causalis.dgp.causaldata_instrumental.base.IVCausalDatasetGenerator

None