`statspai.conformal_causal`¶

conformal_causal ¶

Conformal Causal Inference: Distribution-free prediction intervals for ITE.

Provides prediction intervals for individual treatment effects (ITE) without distributional assumptions, using conformal inference.

References

Lei, L. & Candes, E. J. (2021). Conformal Inference of Counterfactuals and Individual Treatment Effects. JRSS-B, 83(5), 911-938. [@lei2021conformal]

Chernozhukov, V., Wuthrich, K., & Zhu, Y. (2021). An Exact and Robust Conformal Inference Method for Counterfactual and Synthetic Controls. JASA, 116(536), 1849-1864. [@chernozhukov2021exact]

ConformalCATE ¶

Conformal prediction intervals for individual treatment effects.

Parameters:

Name	Type	Default
`data`	`DataFrame`	required
`y`	`str`	required
`treat`	`str`	required
`covariates`	`list of str`	required
`model`	`sklearn estimator`	`None`
`alpha`	`float`	`0.05`
`calib_fraction`	`float`	`0.25`
`random_state`	`int`	`42`

fit ¶

fit() -> CausalResult

Compute conformal CATE intervals.

predict ¶

predict(X_new: ndarray) -> Dict[str, ndarray]

Predict CATE with conformal intervals for new data.

Returns:

Type	Description
`dict with 'cate', 'lower', 'upper'`

ConformalCounterfactualResult `dataclass` ¶

Counterfactual prediction intervals under each potential outcome.

ConformalITEResult `dataclass` ¶

Prediction intervals for the individual treatment effect τ(x).

ConformalDensityResult `dataclass` ¶

Conditional-density conformal ITE intervals.

MultiDPConformalResult `dataclass` ¶

Multi-decision-point conformal ITE intervals.

DebiasedConformalResult `dataclass` ¶

Debiased ML conformal counterfactual intervals.

FairConformalResult `dataclass` ¶

Fairness-aware conformal ITE intervals.

ContinuousConformalResult `dataclass` ¶

Output of :func:conformal_continuous.

InterferenceConformalResult `dataclass` ¶

Output of :func:conformal_interference.

conformal_cate ¶

conformal_cate(data: DataFrame, y: str, treat: str, covariates: List[str], model: Optional[BaseEstimator] = None, alpha: float = 0.05, calib_fraction: float = 0.25, random_state: int = 42) -> CausalResult

Compute conformal prediction intervals for CATE.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	Input data.	required
`y`	`str`	Outcome variable.	required
`treat`	`str`	Binary treatment variable (0/1).	required
`covariates`	`list of str`	Covariate names.	required
`model`	`sklearn estimator`	Outcome model for mu_d(X). If None, uses GBM.	`None`
`alpha`	`float`	Miscoverage level. Intervals have (1-alpha) coverage.	`0.05`
`calib_fraction`	`float`	Fraction of data used for calibration.	`0.25`
`random_state`	`int`		`42`

Returns:

Type	Description
`CausalResult`	Includes CATE point estimates and prediction intervals. model_info contains: - 'cate': point estimates - 'cate_lower': lower bounds of prediction intervals - 'cate_upper': upper bounds of prediction intervals - 'interval_width': average width of prediction intervals

Examples:

>>> import statspai as sp
>>> result = sp.conformal_cate(df, y='outcome', treat='treatment',
...                            covariates=['x1', 'x2'])
>>> cate_lower = result.model_info['cate_lower']
>>> cate_upper = result.model_info['cate_upper']

weighted_conformal_prediction ¶

weighted_conformal_prediction(X_train: ndarray, y_train: ndarray, X_calib: ndarray, y_calib: ndarray, X_test: ndarray, weights_calib: Optional[ndarray] = None, model: Optional[BaseEstimator] = None, alpha: float = 0.1) -> tuple

Split conformal prediction with per-calibration-point weights.

Implements the Tibshirani-Barber-Candès-Ramdas (2019) weighted split-conformal procedure. When weights_calib is None, this reduces to standard split conformal.

Parameters:

Name	Type	Description	Default
`X_train`	`arrays`	Training fold used to fit the base regression model.	required
`y_train`	`arrays`	Training fold used to fit the base regression model.	required
`X_calib`	`arrays`	Calibration fold used to compute non-conformity scores.	required
`y_calib`	`arrays`	Calibration fold used to compute non-conformity scores.	required
`X_test`	`array`	Points at which to produce prediction intervals.	required
`weights_calib`	`array`	Per-calibration-point likelihood-ratio weights `w_i = f_test(X_i) / f_train(X_i)` for covariate-shift correction. If None, uniform weights.	`None`
`model`	`sklearn-style estimator`	Defaults to `RandomForestRegressor(n_estimators=200, min_samples_leaf=5, random_state=0)`.	`None`
`alpha`	`float`	Miscoverage level (interval targets `1-alpha` coverage).	`0.1`

Returns:

Type	Description
(lower, upper, point) : tuple of arrays, each length ``len(X_test)``

conformal_counterfactual ¶

conformal_counterfactual(data: DataFrame, y: str, treat: str, covariates: list, X_test: Optional[ndarray] = None, *, alpha: float = 0.1, calib_frac: float = 0.3, model: Optional[BaseEstimator] = None, propensity_model: Optional[BaseEstimator] = None, random_state: Optional[int] = None) -> ConformalCounterfactualResult

Prediction intervals for the counterfactual potential outcomes Y(1) | X and Y(0) | X (Lei & Candès 2021 Theorem 1).

Uses weighted split-conformal separately for each treatment arm, with the propensity score providing the covariate-shift weight between the treated sub-population and the overall population.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`		required
`y`	`str`	Outcome and 0/1 treatment column names.	required
`treat`	`str`	Outcome and 0/1 treatment column names.	required
`covariates`	`list of str`	Columns used as features for both the outcome and propensity models.	required
`X_test`	`array`	Points at which to return intervals. Defaults to `data[covariates]`.	`None`
`alpha`	`float`	Miscoverage level.	`0.1`
`calib_frac`	`float`	Fraction of each arm used for calibration.	`0.3`
`model`	`sklearn estimators`	Defaults: :class:`RandomForestRegressor` / :class:`LogisticRegression`.	`None`
`propensity_model`	`sklearn estimators`	Defaults: :class:`RandomForestRegressor` / :class:`LogisticRegression`.	`None`
`random_state`	`int`		`None`

Returns:

Type	Description
`ConformalCounterfactualResult`

conformal_ite_interval ¶

conformal_ite_interval(data: DataFrame, y: str, treat: str, covariates: list, X_test: Optional[ndarray] = None, *, alpha: float = 0.1, calib_frac: float = 0.3, model: Optional[BaseEstimator] = None, propensity_model: Optional[BaseEstimator] = None, random_state: Optional[int] = None) -> ConformalITEResult

Conformal prediction intervals for the individual treatment effect τ(x) = Y(1) - Y(0).

Implements the Lei-Candès (2021) nested counterfactual bound (Eq. 3.4):

.. math::

[\hat τ(x) - \Delta_1(x) - \Delta_0(x),
 \hat τ(x) + \Delta_1(x) + \Delta_0(x)]

where Δ_a(x) is the half-width of the split-conformal counterfactual interval for arm a at x. This is conservative but finite-sample valid under the usual overlap and SUTVA conditions.

Accepts the same arguments as :func:conformal_counterfactual.

Returns:

Type	Description
`ConformalITEResult`

conformal_density_ite ¶

conformal_density_ite(data: DataFrame, y: str, treat: str, covariates: List[str], test_data: Optional[DataFrame] = None, alpha: float = 0.1, bandwidth: Optional[float] = None, seed: int = 0) -> ConformalDensityResult

Conditional-density conformal ITE intervals.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	Training data with both treated and control units.	required
`y`	`str`		required
`treat`	`str`		required
`covariates`	`list of str`		required
`test_data`	`DataFrame`	Test set; defaults to `data` (in-sample intervals).	`None`
`alpha`	`float`	Miscoverage; intervals target 1 − α coverage.	`0.1`
`bandwidth`	`float`	KDE bandwidth; defaults to Silverman's rule on calibration Y.	`None`
`seed`	`int`		`0`

Returns:

Type	Description
`ConformalDensityResult`

conformal_ite_multidp ¶

conformal_ite_multidp(data: DataFrame, y_per_stage: List[str], treat_per_stage: List[str], history_per_stage: List[List[str]], test_data: Optional[DataFrame] = None, alpha: float = 0.1, seed: int = 0) -> MultiDPConformalResult

Multi-decision-point conformal ITE.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	Long-format wide data: each row = subject; columns include stage-specific outcomes / treatments / histories.	required
`y_per_stage`	`list of str`	Outcome column at each stage k = 1, ..., K.	required
`treat_per_stage`	`list of str`	Binary treatment at each stage.	required
`history_per_stage`	`list of list of str`	History (covariates available at decision time k).	required
`test_data`	`DataFrame`		`None`
`alpha`	`float`		`0.1`
`seed`	`int`		`0`

Returns:

Type	Description
`MultiDPConformalResult`

conformal_debiased_ml ¶

conformal_debiased_ml(data: DataFrame, y: str, treat: str, covariates: List[str], test_data: Optional[DataFrame] = None, alpha: float = 0.1, n_folds: int = 5, seed: int = 0) -> DebiasedConformalResult

Debiased ML conformal counterfactual intervals.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`		required
`y`	`str`		required
`treat`	`str`		required
`covariates`	`list of str`		required
`test_data`	`DataFrame`		`None`
`alpha`	`float`		`0.1`
`n_folds`	`int`	Cross-fitting folds (debiased step).	`5`
`seed`	`int`		`0`

Returns:

Type	Description
`DebiasedConformalResult`

conformal_fair_ite ¶

conformal_fair_ite(data: DataFrame, y: str, treat: str, covariates: List[str], protected: str, test_data: Optional[DataFrame] = None, alpha: float = 0.1, seed: int = 0) -> FairConformalResult

Counterfactual-fair conformal ITE intervals.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`		required
`y`	`str`		required
`treat`	`str`		required
`covariates`	`list of str`	Predictive features. `protected` is excluded from the outcome regression to preserve counterfactual fairness, but used downstream for stratified calibration.	required
`protected`	`str`	Protected attribute column (categorical).	required
`test_data`	`DataFrame`		`None`
`alpha`	`float`		`0.1`
`seed`	`int`		`0`

Returns:

Type	Description
`FairConformalResult`

conformal_continuous ¶

conformal_continuous(data: DataFrame, *, y: str, treatment: str, covariates: Sequence[str], test_data: DataFrame, dose_grid: Optional[Sequence[float]] = None, alpha: float = 0.1, estimator: Optional[Any] = None, calibration_frac: float = 0.5, random_state: int = 0) -> ContinuousConformalResult

Split-conformal bands for a continuous-treatment dose response.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	Training sample with continuous `treatment` and outcome `y`.	required
`y`	`str`		required
`treatment`	`str`		required
`covariates`	`sequence of str`		required
`test_data`	`DataFrame`	Test rows to predict on.	required
`dose_grid`	`sequence of float`	If provided, return conformal bands for the entire curve `E[Y \| T=t, X]` at each `t` on the grid (one curve per test row).	`None`
`alpha`	`float`	Target miscoverage rate (`1 - alpha` is the nominal coverage).	`0.1`
`estimator`	`sklearn-style regressor`	Model for `E[Y \| T, X]`. Must accept `fit(X, y)` and `predict(X)`. Defaults to a gradient-boosting regressor.	`None`
`calibration_frac`	`float`		`0.5`
`random_state`	`int`		`0`

Returns:

Type	Description
`ContinuousConformalResult`

References

Schröder et al. (arXiv:2407.03094, 2024).

conformal_interference ¶

conformal_interference(data: DataFrame, *, y: str, treatment: str, cluster: str, covariates: Sequence[str], test_clusters: Sequence, alpha: float = 0.1, estimator: Optional[Any] = None, calibration_frac: float = 0.5, random_state: int = 0) -> InterferenceConformalResult

Cluster-exchangeable split-conformal prediction under interference.

When units within a cluster interfere (spillover, networks) but clusters are exchangeable, the exchangeable-data guarantee of split conformal survives at the cluster level. We compute a cluster-level absolute-residual score by averaging per-unit residuals inside each cluster, then build the usual split-conformal quantile over clusters.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame`	Full sample with cluster identifier `cluster`.	required
`y`	`str`		required
`treatment`	`str`		required
`cluster`	`str`		required
`covariates`	`sequence of str`		required
`test_clusters`	`sequence`	Cluster IDs to predict on. Must appear in `data`.	required
`alpha`	`float`		`0.1`
`estimator`	`sklearn-style regressor`		`None`
`calibration_frac`	`float`		`0.5`
`random_state`	`int`		`0`

Returns:

Type	Description
`InterferenceConformalResult`

Notes

This is the cluster-exchangeable variant used in the Memmesheimer, Heuveline & Hesser (arXiv:2509.21660, 2025) systematic review as the recommended default when SUTVA is violated within clusters.

conformal ¶

conformal(kind: str = 'cate', /, **kwargs: Any) -> Any

Unified entry point for the conformal causal inference family.

Parameters:

Name	Type	Description	Default
`kind`	`str`	The conformal estimator to run. Supported values are listed by `sp.conformal_available_kinds()`.	``"cate"``
`**kwargs`	`Any`	Passed through unchanged to the target function.	`{}`

Returns:

Type	Description
The underlying estimator's return object — e.g. ``CausalResult`` for
func:`conformal_cate`, ``ConformalITEResult`` for ``kind="ite"``,
``ContinuousConformalResult`` for ``kind="continuous"``.

Examples:

>>> import statspai as sp
>>> r = sp.conformal("cate", data=df, y="y", treat="d",
...                   covariates=["x1", "x2"])

conformal_available_kinds ¶

conformal_available_kinds() -> list[str]

Return the full list of registered conformal kind names.

statspai.conformal_causal¶

conformal_causal ¶

ConformalCATE ¶

fit ¶

predict ¶

ConformalCounterfactualResult dataclass ¶

ConformalITEResult dataclass ¶

ConformalDensityResult dataclass ¶

MultiDPConformalResult dataclass ¶

DebiasedConformalResult dataclass ¶

FairConformalResult dataclass ¶

ContinuousConformalResult dataclass ¶

InterferenceConformalResult dataclass ¶

conformal_cate ¶

weighted_conformal_prediction ¶

conformal_counterfactual ¶

conformal_ite_interval ¶

conformal_density_ite ¶

conformal_ite_multidp ¶

conformal_debiased_ml ¶

conformal_fair_ite ¶

conformal_continuous ¶

conformal_interference ¶

conformal ¶

conformal_available_kinds ¶

`statspai.conformal_causal`¶

ConformalCounterfactualResult `dataclass` ¶

ConformalITEResult `dataclass` ¶

ConformalDensityResult `dataclass` ¶

MultiDPConformalResult `dataclass` ¶

DebiasedConformalResult `dataclass` ¶

FairConformalResult `dataclass` ¶

ContinuousConformalResult `dataclass` ¶

InterferenceConformalResult `dataclass` ¶