milia.recommend.uplift#

Uplift: the change in an outcome that an action causes, estimated for each case from its features.

For a case with features \(\mathbf{x}\), the potential outcomes \(Y(1)\) with the action and \(Y(0)\) without it define the conditional effect

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

such as the violation hours a lever removes at a transformer. Only one potential outcome is observed for each case, so the effect is estimated by meta-learners that combine ordinary regressors [Künzel et al., 2019]:

  • TLearner fits \(\hat\mu_0\) on the untreated and \(\hat\mu_1\) on the treated cases and estimates \(\hat\tau = \hat\mu_1 - \hat\mu_0\).

  • XLearner imputes each case’s effect from the other group’s model, \(D_i^1 = Y_i - \hat\mu_0(\mathbf{x}_i)\) for treated and \(D_i^0 = \hat\mu_1(\mathbf{x}_i) - Y_i\) for untreated cases, regresses the imputed effects on the features in each group, and weights the two estimates by the share of treated cases \(e\), \(\hat\tau = e\, \hat\tau_0 + (1 - e)\, \hat\tau_1\), which helps when the groups are of unequal size.

Where a simulator supplies both potential outcomes, as for the levers of a network model, the estimated effect can be checked exactly against the simulated one.

Classes

TLearner([estimator])

Effect of an action as the difference of two outcome models, one per arm.

XLearner([estimator])

Effect of an action from imputed individual effects, weighted by the share of treated cases.

class milia.recommend.uplift.TLearner(estimator=None)#

Bases: BaseEstimator

Effect of an action as the difference of two outcome models, one per arm.

Parameters:

estimator (RegressorMixin | None) – Regressor cloned for each arm; a random forest when omitted.

Examples

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> X = rng.uniform(size=(400, 1))
>>> treatment = rng.integers(0, 2, 400)
>>> y = X[:, 0] + treatment * 2 * X[:, 0] + 0.05 * rng.normal(size=400)
>>> learner = TLearner().fit(X, y, treatment)
>>> abs(float(learner.effect([[0.5]])[0]) - 1.0) < 0.2  # the true effect at 0.5 is 1.0
True
fit(X, y, treatment)#

Fit one outcome model on the untreated and one on the treated cases.

Parameters:
  • X (ArrayLike) – Features of each case.

  • y (ArrayLike) – Observed outcome of each case.

  • treatment (ArrayLike) – Whether each case received the action.

Return type:

TLearner

Returns:

The fitted learner.

effect(X)#

Estimated effect of the action for each case.

Parameters:

X (ArrayLike) – Features of each case.

Return type:

ndarray

Returns:

The estimated change in the outcome caused by the action.

set_fit_request(*, treatment='$UNCHANGED$')#

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to fit.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters#

treatmentstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for treatment parameter in fit.

Returns#

selfobject

The updated object.

Return type:

TLearner

class milia.recommend.uplift.XLearner(estimator=None)#

Bases: BaseEstimator

Effect of an action from imputed individual effects, weighted by the share of treated cases.

Parameters:

estimator (RegressorMixin | None) – Regressor cloned for each outcome and effect model; a random forest when omitted.

Examples

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> X = rng.uniform(size=(400, 1))
>>> treatment = (rng.uniform(size=400) < 0.2).astype(int)  # few treated cases
>>> y = X[:, 0] + treatment * 2 * X[:, 0] + 0.05 * rng.normal(size=400)
>>> learner = XLearner().fit(X, y, treatment)
>>> abs(float(learner.effect([[0.5]])[0]) - 1.0) < 0.2  # the true effect at 0.5 is 1.0
True
fit(X, y, treatment)#

Fit the outcome models, impute each case’s effect, and fit the effect models.

Parameters:
  • X (ArrayLike) – Features of each case.

  • y (ArrayLike) – Observed outcome of each case.

  • treatment (ArrayLike) – Whether each case received the action.

Return type:

XLearner

Returns:

The fitted learner.

effect(X)#

Estimated effect of the action for each case.

Parameters:

X (ArrayLike) – Features of each case.

Return type:

ndarray

Returns:

The estimated change in the outcome caused by the action.

set_fit_request(*, treatment='$UNCHANGED$')#

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

  • True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.

  • False: metadata is not requested and the meta-estimator will not pass it to fit.

  • None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

  • str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters#

treatmentstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for treatment parameter in fit.

Returns#

selfobject

The updated object.

Return type:

XLearner