# `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