# `causalis.scenarios.uplift.model`

Lazy Conditional Average Treatment Effect (CATE) and uplift scoring helpers.

This module provides functionality to predict heterogeneous treatment effects (CATE) for new observations using models fitted under the unconfoundedness assumption.

## Module Contents

### Functions

`predict_cate` | Predict Conditional Average Treatment Effect (CATE), or uplift, for new observations.

### Data

`__all__` |

### API

causalis.scenarios.uplift.model.predict_cate(irm_model: Any, X: pandas.DataFrame | numpy.ndarray) → numpy.ndarray

  Predict Conditional Average Treatment Effect (CATE), or uplift, for new observations.

  This function implements a “lazy” T-learner approach. On its first call for a given fitted :class:`~causalis.scenarios.unconfoundedness.model.IRM` model, it trains two separate full-sample outcome models—one for the control group ($D=0$) and one for the treatment group ($D=1$). These models are then cached on the `irm_model` object for subsequent calls.

  Mathematical Note

  The CATE at a point $x$ is defined as the difference in potential outcomes:

  .. math::

      \tau(x) = \mathbb{E}[Y(1) - Y(0) \mid X = x]

  Under the assumption of unconfoundedness (no unmeasured confounders), this can be estimated as:

  .. math::

      \tau(x) = \mathbb{E}[Y \mid X = x, D = 1] - \mathbb{E}[Y \mid X = x, D = 0]

  The estimator $\hat{\tau}(x)$ used here is:

  .. math::

      \hat{\tau}(x) = \hat{g}_1(x) - \hat{g}_0(x)

  where $\hat{g}_1$ is a machine learning model (cloned from `irm_model.ml_g`) trained on the subset of the original training data where $D_i = 1$, and $\hat{g}_0$ is similarly trained on the subset where $D_i = 0$.

  Parameters

  irm_model : IRM A fitted :class:`~causalis.scenarios.unconfoundedness.model.IRM` object. The model must have been fitted using :meth:`~causalis.scenarios.unconfoundedness.model.IRM.fit`. X : pd.DataFrame or np.ndarray New observations for which to predict the CATE. If a DataFrame, it must contain the same confounder columns as used during fit. If an ndarray, it must have the same number of columns as the fitted confounders.

  Returns

  np.ndarray A 1D array of predicted CATE/uplift values for each row in `X`.

  Examples

  > > > import pandas as pd import numpy as np from causalis.scenarios.unconfoundedness.model import IRM from causalis.scenarios.unconfoundedness.dgp import generate_obs_hte_26 from causalis.scenarios.uplift.model import predict_cate

  > > > Generate data

  > > > data = generate_obs_hte_26(n=1000, seed=42)

  > > > Fit IRM model

  > > > irm = IRM(data=data).fit()

  > > > Predict uplift for new data

  > > > X_new = data.df.loc[:5, data.confounders] uplift = predict_cate(irm, X_new) print(uplift.shape) (6,)

  Notes

  The models trained for prediction use the full sample (split by treatment arm) available at fit time, whereas the :meth:`~causalis.scenarios.unconfoundedness.model.IRM.fit` method uses cross-fitting for nuisance estimation.

causalis.scenarios.uplift.model.__all__

  [‘predict_cate’]