# `causalis.dgp.causaldata_instrumental.functional`

High-level helpers for instrumental-variable synthetic datasets.

Use this module when you want a ready-made binary-instrument, binary-treatment dataset compatible with :class:`causalis.data_contracts.iv_causal_data.IVCausalData`. For lower-level structural control, instantiate :class:`causalis.dgp.causaldata_instrumental.base.InstrumentalGenerator` directly.

## Module Contents

### Functions

`generate_iv_data` | Generate a synthetic instrumental-variable dataset.

### API

causalis.dgp.causaldata_instrumental.functional.generate_iv_data(n: int = 1000, *, outcome_type: str = 'continuous', theta: float = 1.0, tau: Optional[Callable[[numpy.ndarray], numpy.ndarray]] = None, sigma_y: float = 1.0, alpha_y: float = 0.0, gamma_shape: float = 2.0, first_stage: float = 1.25, alpha_d: float = -0.2, alpha_z: float = 0.0, target_d_rate: Optional[float] = None, target_z_rate: Optional[float] = 0.5, confounder_specs: Optional[List[Dict[str, Any]]] = None, beta_y: Optional[Union[List[float], numpy.ndarray]] = None, beta_d: Optional[Union[List[float], numpy.ndarray]] = None, beta_z: Optional[Union[List[float], numpy.ndarray]] = None, g_y: Optional[Callable[[numpy.ndarray], numpy.ndarray]] = None, g_d: Optional[Callable[[numpy.ndarray], numpy.ndarray]] = None, g_z: Optional[Callable[[numpy.ndarray], numpy.ndarray]] = None, u_strength_d: float = 0.8, u_strength_y: float = 0.8, propensity_sharpness: float = 1.0, instrument_sharpness: float = 1.0, random_state: Optional[int] = 42, k: int = 2, x_sampler: Optional[Callable[[int, int, int], numpy.ndarray]] = None, use_copula: bool = False, copula_corr: Optional[numpy.ndarray] = None, include_oracle: bool = True, return_causal_data: bool = False, instrument_name: str = 'z', add_ancillary: bool = False, deterministic_ids: bool = False) → Union[pandas.DataFrame, causalis.data_contracts.iv_causal_data.IVCausalData]

  Generate a synthetic instrumental-variable dataset.

  Parameters

  n : int, default=1000 Number of samples. outcome_type : {“continuous”, “binary”, “poisson”, “gamma”}, default=”continuous” Outcome family. theta : float, default=1.0 Constant treatment effect on the structural outcome scale. first_stage : float, default=1.25 Additive log-odds effect of the instrument on treatment. target_z_rate : float, optional Target marginal instrument rate. target_d_rate : float, optional Target marginal treatment rate after instrument assignment. u_strength_d, u_strength_y : float, default=0.8 Latent confounding strengths in treatment and outcome. return_causal_data : bool, default=False If True, return a validated :class:`IVCausalData` object. instrument_name : str, default=”z” Instrument column name.

  Returns

  pandas.DataFrame or IVCausalData Synthetic IV dataset or validated IV data contract.

  Examples

  > > > from causalis.dgp.causaldata_instrumental import generate_iv_data data = generate_iv_data(n=500, return_causal_data=True) data.instruments [‘z’]