InstrumentalVariable#

class causalpy.experiments.instrumental_variable.InstrumentalVariable[source]#

A class to analyse instrumental variable style experiments.

Parameters:

  • instruments_data (DataFrame) – A pandas dataframe of instruments for our treatment variable. Should contain instruments Z, and treatment t.

  • data (DataFrame) – A pandas dataframe of covariates for fitting the focal regression of interest. Should contain covariates X including treatment t and outcome y.

  • instruments_formula (str) – A statistical model formula for the instrumental stage regression, e.g. t ~ 1 + z1 + z2 + z3.

  • formula (str) – A statistical model formula for the focal regression, e.g. y ~ 1 + t + x1 + x2 + x3.

  • model (InstrumentalVariableRegression | None) – A PyMC model. Defaults to InstrumentalVariableRegression.

  • priors (dict | None) – Dictionary of priors for the mus and sigmas of both regressions. If priors are not specified we will substitute MLE estimates for the beta coefficients. Example: priors = {"mus": [0, 0], "sigmas": [1, 1], "eta": 2, "lkj_sd": 2}.

  • vs_prior_type (str or None, default=None) – Type of variable selection prior: ‘spike_and_slab’, ‘horseshoe’, or None. If None, uses standard normal priors.

  • vs_hyperparams (dict, optional) – Hyperparameters for variable selection priors. Only used if vs_prior_type is not None.

  • binary_treatment (bool, default=False) – A indicator for whether the treatment to be modelled is binary or not. Determines which PyMC model we use to model the joint outcome and treatment.

  • **kwargs (Any) – Additional keyword arguments forwarded to BaseExperiment.

Notes

Estimate extraction

The class computes naive OLS and two-stage least-squares reference fits, then fits a joint Bayesian model for the treatment and outcome equations. Under the instrumental-variable assumptions, the causal quantity is read from the outcome-stage coefficient associated with the instrumented treatment; no counterfactual prediction or population standardization is performed. For binary treatments, its LATE interpretation applies to the complier population induced by the instrument; continuous treatments require the corresponding structural IV interpretation.

Examples

>>> import pandas as pd
>>> import causalpy as cp
>>> from causalpy.pymc_models import InstrumentalVariableRegression
>>> import numpy as np
>>> N = 100
>>> e1 = np.random.normal(0, 3, N)
>>> e2 = np.random.normal(0, 1, N)
>>> Z = np.random.uniform(0, 1, N)
>>> ## Ensure the endogeneity of the the treatment variable
>>> X = -1 + 4 * Z + e2 + 2 * e1
>>> y = 2 + 3 * X + 3 * e1
>>> test_data = pd.DataFrame({"y": y, "X": X, "Z": Z})
>>> sample_kwargs = {
...     "tune": 1,
...     "draws": 5,
...     "chains": 1,
...     "cores": 4,
...     "target_accept": 0.95,
...     "progressbar": False,
... }
>>> instruments_formula = "X  ~ 1 + Z"
>>> formula = "y ~  1 + X"
>>> instruments_data = test_data[["X", "Z"]]
>>> data = test_data[["y", "X"]]
>>> iv = cp.InstrumentalVariable(
...     instruments_data=instruments_data,
...     data=data,
...     instruments_formula=instruments_formula,
...     formula=formula,
...     model=InstrumentalVariableRegression(sample_kwargs=sample_kwargs),
... )
>>> # With variable selection
>>> iv = cp.InstrumentalVariable(
...     instruments_data=instruments_data,
...     data=data,
...     instruments_formula=instruments_formula,
...     formula=formula,
...     model=InstrumentalVariableRegression(sample_kwargs=sample_kwargs),
...     vs_prior_type="spike_and_slab",
...     vs_hyperparams={"slab_sigma": 5.0},
... )

Methods

InstrumentalVariable.algorithm()

Run the experiment algorithm: fit OLS, 2SLS, and Bayesian IV model.

InstrumentalVariable.effect_summary(*[, ...])

Generate a decision-ready summary of causal effects.

InstrumentalVariable.fit(*args, **kwargs)

Fit the underlying model.

InstrumentalVariable.generate_report(*[, ...])

Generate a self-contained HTML report for this experiment.

InstrumentalVariable.get_2SLS_fit()

Two Stage Least Squares Fit.

InstrumentalVariable.get_naive_OLS_fit()

Naive Ordinary Least Squares.

InstrumentalVariable.get_plot_data(*args, ...)

Recover the data of an experiment along with the prediction and causal impact information.

InstrumentalVariable.input_validation()

Validate the input data and model formula for correctness.

InstrumentalVariable.plot(*[, show, ...])

Plot the results.

InstrumentalVariable.print_coefficients([...])

Ask the model to print its coefficients.

InstrumentalVariable.set_maketables_options(*)

Set optional maketables rendering options for this experiment.

InstrumentalVariable.summary([round_to])

Print summary of main results and model coefficients.

Attributes

idata

Return fitted InferenceData when the model backend supports it.

supports_bayes

supports_ols

supports_pymc_forecast

labels

data

__init__(instruments_data, data, instruments_formula, formula, model=None, priors=None, vs_prior_type=None, vs_hyperparams=None, binary_treatment=False, **kwargs)[source]#
Parameters:
Return type:

None

classmethod __new__(*args, **kwargs)#