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