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
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]:
TLearnerfits \(\hat\mu_0\) on the untreated and \(\hat\mu_1\) on the treated cases and estimates \(\hat\tau = \hat\mu_1 - \hat\mu_0\).XLearnerimputes 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
|
Effect of an action as the difference of two outcome models, one per arm. |
|
Effect of an action from imputed individual effects, weighted by the share of treated cases. |
- class milia.recommend.uplift.TLearner(estimator=None)#
Bases:
BaseEstimatorEffect 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.
- effect(X)#
Estimated effect of the action for each case.
- set_fit_request(*, treatment='$UNCHANGED$')#
Configure whether metadata should be requested to be passed to the
fitmethod.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(seesklearn.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 tofitif provided. The request is ignored if metadata is not provided.False: metadata is not requested and the meta-estimator will not pass it tofit.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
treatmentparameter infit.
Returns#
- selfobject
The updated object.
- Return type:
- class milia.recommend.uplift.XLearner(estimator=None)#
Bases:
BaseEstimatorEffect 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.
- effect(X)#
Estimated effect of the action for each case.
- set_fit_request(*, treatment='$UNCHANGED$')#
Configure whether metadata should be requested to be passed to the
fitmethod.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(seesklearn.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 tofitif provided. The request is ignored if metadata is not provided.False: metadata is not requested and the meta-estimator will not pass it tofit.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
treatmentparameter infit.
Returns#
- selfobject
The updated object.
- Return type: