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’]