causalis.scenarios.iv.refutation.diagnostics

Post-inference diagnostics for binary instrumental-variable estimates.

Module Contents

Functions

compute_instrument_overlap_diagnostics	Compute instrument propensity/overlap diagnostics from IV diagnostic data.
compute_first_stage_diagnostics	Compute controlled first-stage diagnostics: D ~ 1 + Z + X.
compute_reduced_form_diagnostics	Compute simple reduced-form diagnostics: Y ~ 1 + Z.
instrument_overlap	Return instrument propensity/overlap diagnostics for an IV result.
first_stage	Return first-stage diagnostics for an IV result.
reduced_form	Return reduced-form sanity diagnostics for an IV result. The reduced form is the regression of the outcome on the instrument. Under the IV assumptions, the LATE is the ratio of the reduced-form effect to the first-stage effect. .. math:: heta =
instrument_overlap_plot	Plot instrument propensity distributions by observed instrument group.

Data

__all__

API

causalis.scenarios.iv.refutation.diagnostics.compute_instrument_overlap_diagnostics(diag: causalis.data_contracts.causal_diagnostic_data.IVDiagnosticData) → Dict[str, Any]

Compute instrument propensity/overlap diagnostics from IV diagnostic data.

causalis.scenarios.iv.refutation.diagnostics.compute_first_stage_diagnostics(diag: causalis.data_contracts.causal_diagnostic_data.IVDiagnosticData, *, weak_iv_threshold: float = 0.01) → Dict[str, Any]

Compute controlled first-stage diagnostics: D ~ 1 + Z + X.

causalis.scenarios.iv.refutation.diagnostics.compute_reduced_form_diagnostics(diag: causalis.data_contracts.causal_diagnostic_data.IVDiagnosticData, *, late_value: Optional[float] = None) → Dict[str, Any]

Compute simple reduced-form diagnostics: Y ~ 1 + Z.

causalis.scenarios.iv.refutation.diagnostics.instrument_overlap(result: Any) → pandas.DataFrame

Return instrument propensity/overlap diagnostics for an IV result.

Checks how well the instrument can be predicted from covariates and whether there is sufficient overlap in instrument assignment.

Parameters

result : IIVM or IVCausalEstimate The fitted IV model or its estimation result.

Returns

pd.DataFrame A table with diagnostic metrics (AUC, KS, ESS ratio).

Examples

from causalis.scenarios.iv.refutation import instrument_overlap

Assuming ‘result’ is obtained from model.estimate()

instrument_overlap(result)

causalis.scenarios.iv.refutation.diagnostics.first_stage(result: Any) → pandas.DataFrame

Return first-stage diagnostics for an IV result.

Checks the strength of the relationship between the instrument and the treatment. A weak first stage (F-statistic < 10 or similar) can lead to biased and unstable IV estimates.

Parameters

result : IIVM or IVCausalEstimate The fitted IV model or its estimation result.

Returns

pd.DataFrame A table with first-stage metrics (Effect, F-statistic, Partial R2, etc.).

Examples

from causalis.scenarios.iv.refutation import first_stage

Assuming ‘result’ is obtained from model.estimate()

first_stage(result)

causalis.scenarios.iv.refutation.diagnostics.reduced_form(result: Any) → pandas.DataFrame

Return reduced-form sanity diagnostics for an IV result.

The reduced form is the regression of the outcome on the instrument.
Under the IV assumptions, the LATE is the ratio of the reduced-form
effect to the first-stage effect.

.. math::

            heta = 

rac{\mathbb{E}[Y|Z=1] - \mathbb{E}[Y|Z=0]}{\mathbb{E}[D|Z=1] - \mathbb{E}[D|Z=0]}

Parameters
----------
result : IIVM or IVCausalEstimate
    The fitted IV model or its estimation result.

Returns
-------
pd.DataFrame
    A table with reduced-form metrics.

Examples
--------
>>> from causalis.scenarios.iv.refutation import reduced_form
>>> # Assuming 'result' is obtained from model.estimate()
>>> reduced_form(result)

causalis.scenarios.iv.refutation.diagnostics.instrument_overlap_plot(result: Any, *, bins: Any = 'fd', ax: Optional[Any] = None, figsize: Tuple[float, float] = (8.0, 4.5), dpi: int = 150, save: Optional[str] = None) → Any

Plot instrument propensity distributions by observed instrument group.

Visualizes the overlap of :math:\mathbb{P}(Z=1|X) between the :math:Z=0 and :math:Z=1 groups. Good overlap is essential for reliable IV estimation.

Parameters

result : IIVM or IVCausalEstimate The fitted IV model or its estimation result. bins : str or int, default “fd” Binning strategy for histograms. ax : matplotlib.axes.Axes, optional Pre-existing axes to plot on. figsize : tuple, default (8.0, 4.5) Figure size. dpi : int, default 150 Resolution. save : str, optional Path to save the figure.

Returns

matplotlib.figure.Figure The generated figure.

causalis.scenarios.iv.refutation.diagnostics.__all__

[‘compute_first_stage_diagnostics’, ‘compute_instrument_overlap_diagnostics’, ‘compute_reduced_form_…