econml.policy.PolicyForest

class econml.policy.PolicyForest(n_estimators=100, *, criterion='neg_welfare', max_depth=None, min_samples_split=10, min_samples_leaf=5, min_weight_fraction_leaf=0.0, max_features='auto', min_impurity_decrease=0.0, max_samples=0.5, min_balancedness_tol=0.45, honest=True, n_jobs=-1, random_state=None, verbose=0, warm_start=False)

Bases: BaseEnsemble

Welfare maximization policy forest.

Trains a forest to maximize the objective: \(1/n \sum_i \sum_j a_j(X_i) * y_{ij}\), where, where \(a(X)\) is constrained to take value of 1 only on one coordinate and zero otherwise. This corresponds to a policy optimization problem.

Parameters:

• n_estimators (int, default 100) – The total number of trees in the forest. The forest consists of a forest of sqrt(n_estimators) sub-forests, where each sub-forest contains sqrt(n_estimators) trees.

• criterion ({'neg_welfare'}, default ‘neg_welfare’) – The criterion type

• max_depth (int, default None) – The maximum depth of the tree. If None, then nodes are expanded until all leaves are pure or until all leaves contain less than min_samples_split samples.

• min_samples_split (int or float, default 10) – The minimum number of samples required to split an internal node:

  • If int, then consider min_samples_split as the minimum number.

  • If float, then min_samples_split is a fraction and ceil(min_samples_split * n_samples) are the minimum number of samples for each split.

• min_samples_leaf (int or float, default 5) – The minimum number of samples required to be at a leaf node. A split point at any depth will only be considered if it leaves at least min_samples_leaf training samples in each of the left and right branches. This may have the effect of smoothing the model, especially in regression.

  • If int, then consider min_samples_leaf as the minimum number.

  • If float, then min_samples_leaf is a fraction and ceil(min_samples_leaf * n_samples) are the minimum number of samples for each node.

• min_weight_fraction_leaf (float, default 0.0) – The minimum weighted fraction of the sum total of weights (of all the input samples) required to be at a leaf node. Samples have equal weight when sample_weight is not provided.

• max_features (int, float, {“auto”, “sqrt”, “log2”}, or None, default None) – The number of features to consider when looking for the best split:

  • If int, then consider max_features features at each split.

  • If float, then max_features is a fraction and int(max_features * n_features) features are considered at each split.

  • If “auto”, then max_features=n_features.

  • If “sqrt”, then max_features=sqrt(n_features).

  • If “log2”, then max_features=log2(n_features).

  • If None, then max_features=n_features.

  Note: the search for a split does not stop until at least one valid partition of the node samples is found, even if it requires to effectively inspect more than max_features features.

• min_impurity_decrease (float, default 0.0) – A node will be split if this split induces a decrease of the impurity greater than or equal to this value. The weighted impurity decrease equation is the following:

  N_t / N * (impurity - N_t_R / N_t * right_impurity
                      - N_t_L / N_t * left_impurity)
  

  where N is the total number of samples, N_t is the number of samples at the current node, N_t_L is the number of samples in the left child, and N_t_R is the number of samples in the right child. N, N_t, N_t_R and N_t_L all refer to the weighted sum, if sample_weight is passed.

• max_samples (int or float in (0, 1], default .5,) – The number of samples to use for each subsample that is used to train each tree:

  • If int, then train each tree on max_samples samples, sampled without replacement from all the samples

  • If float, then train each tree on ceil(max_samples * n_samples), sampled without replacement from all the samples.

• min_balancedness_tol (float in [0, .5], default .45) – How imbalanced a split we can tolerate. This enforces that each split leaves at least (.5 - min_balancedness_tol) fraction of samples on each side of the split; or fraction of the total weight of samples, when sample_weight is not None. Default value, ensures that at least 5% of the parent node weight falls in each side of the split. Set it to 0.0 for no balancedness and to .5 for perfectly balanced splits. For the formal inference theory to be valid, this has to be any positive constant bounded away from zero.

• honest (bool, default True) – Whether the data should be split in two equally sized samples, such that the one half-sample is used to determine the optimal split at each node and the other sample is used to determine the value of every node.

• n_jobs (int or None, default -1) – The number of jobs to run in parallel for both fit and predict. None means 1 unless in a joblib.parallel_backend() context. -1 means using all processors. See Glossary for more details.

• verbose (int, default 0) – Controls the verbosity when fitting and predicting.

• random_state (int, RandomState instance, or None, default None) – If int, random_state is the seed used by the random number generator; If RandomState instance, random_state is the random number generator; If None, the random number generator is the RandomState instance used by np.random.

• warm_start (bool, default False) – When set to True, reuse the solution of the previous call to fit and add more estimators to the ensemble, otherwise, just fit a whole new forest.

feature_importances_

The feature importances based on the amount of parameter heterogeneity they create. The higher, the more important the feature.

Type:

ndarray of shape (n_features,)

__init__(n_estimators=100, *, criterion='neg_welfare', max_depth=None, min_samples_split=10, min_samples_leaf=5, min_weight_fraction_leaf=0.0, max_features='auto', min_impurity_decrease=0.0, max_samples=0.5, min_balancedness_tol=0.45, honest=True, n_jobs=-1, random_state=None, verbose=0, warm_start=False)

Methods

__init__([n_estimators, criterion, ...])
apply(X)	Apply trees in the forest to X, return leaf indices.
decision_path(X)	Return the decision path in the forest.
feature_importances([max_depth, ...])	Get the feature importances based on the amount of parameter heterogeneity they create.
fit(X, y, *[, sample_weight])	Build a forest of trees from the training set (X, y) and any other auxiliary variables.
get_metadata_routing()	Get metadata routing of this object.
get_params([deep])	Get parameters for this estimator.
get_subsample_inds()	Re-generate the example same sample indices as those at fit time using same pseudo-randomness.
predict(X)	Predict the best treatment for each sample.
predict_proba(X)	Predict the probability of recommending each treatment.
predict_value(X)	Predict the expected value of each treatment for each sample.
set_fit_request(*[, sample_weight])	Request metadata passed to the fit method.
set_params(**params)	Set the parameters of this estimator.

Attributes

feature_importances_

apply(X)

Apply trees in the forest to X, return leaf indices.

Parameters:

X (array_like of shape (n_samples, n_features)) – The input samples. Internally, it will be converted to dtype=np.float64.

Returns:

X_leaves – For each datapoint x in X and for each tree in the forest, return the index of the leaf x ends up in.

Return type:

ndarray of shape (n_samples, n_estimators)

decision_path(X)

Return the decision path in the forest.

Parameters:

X (array_like of shape (n_samples, n_features)) – The input samples. Internally, it will be converted to dtype=np.float64.

Returns:

• indicator (sparse matrix of shape (n_samples, n_nodes)) – Return a node indicator matrix where non zero elements indicates that the samples goes through the nodes. The matrix is of CSR format.

• n_nodes_ptr (ndarray of shape (n_estimators + 1,)) – The columns from indicator[n_nodes_ptr[i]:n_nodes_ptr[i+1]] gives the indicator value for the i-th estimator.

feature_importances(max_depth=4, depth_decay_exponent=2.0)

Get the feature importances based on the amount of parameter heterogeneity they create.

The higher, the more important the feature.

Parameters:

• max_depth (int, default 4) – Splits of depth larger than max_depth are not used in this calculation

• depth_decay_exponent (double, default 2.0) – The contribution of each split to the total score is re-weighted by 1 / (1 + depth)**2.0.

Returns:

feature_importances_ – Normalized total parameter heterogeneity inducing importance of each feature

Return type:

ndarray of shape (n_features,)

fit(X, y, *, sample_weight=None, **kwargs)

Build a forest of trees from the training set (X, y) and any other auxiliary variables.

Parameters:

• X (array_like of shape (n_samples, n_features)) – The training input samples. Internally, its dtype will be converted to dtype=np.float64.

• y (array_like of shape (n_samples,) or (n_samples, n_treatments)) – The outcome values for each sample and for each treatment.

• sample_weight (array_like of shape (n_samples,), default None) – Sample weights. If None, then samples are equally weighted. Splits that would create child nodes with net zero or negative weight are ignored while searching for a split in each node.

• **kwargs (dictionary of array_like items of shape (n_samples, d_var)) – Auxiliary random variables

Returns:

self

Return type:

object

get_metadata_routing()

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routing – A MetadataRequest encapsulating routing information.

Return type:

MetadataRequest

get_params(deep=True)

Get parameters for this estimator.

Parameters:

deep (bool, default=True) – If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

params – Parameter names mapped to their values.

Return type:

dict

get_subsample_inds()

Re-generate the example same sample indices as those at fit time using same pseudo-randomness.

predict(X)

Predict the best treatment for each sample.

Parameters:

X ({array_like} of shape (n_samples, n_features)) – The input samples. Internally, it will be converted to dtype=np.float64.

Returns:

treatment – The recommded treatment, i.e. the treatment index most often predicted to have the highest reward for each sample. Recommended treatments are aggregated from each tree in the ensemble and the treatment that receives the most votes is returned. Use predict_proba to get the fraction of trees in the ensemble that recommend each treatment for each sample.

Return type:

array_like of shape (n_samples)

predict_proba(X)

Predict the probability of recommending each treatment.

Parameters:

• X ({array_like} of shape (n_samples, n_features)) – The input samples. Internally, it will be converted to dtype=np.float64.

• check_input (bool, default True) – Allow to bypass several input checking. Don’t use this parameter unless you know what you do.

Returns:

treatment_proba – The probability of each treatment recommendation

Return type:

array_like of shape (n_samples, n_treatments)

predict_value(X)

Predict the expected value of each treatment for each sample.

Parameters:

X ({array_like} of shape (n_samples, n_features)) – The input samples. Internally, it will be converted to dtype=np.float64.

Returns:

welfare – The conditional average welfare for each treatment for the group of each sample defined by the tree

Return type:

array_like of shape (n_samples, n_treatments)

set_fit_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → PolicyForest

Request metadata passed to the fit method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see 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.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

Parameters:

sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in fit.

Returns:

self – The updated object.

Return type:

object

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**params (dict) – Estimator parameters.

Returns:

self – Estimator instance.

Return type:

estimator instance