fairlearn.reductions.GridSearch

class fairlearn.reductions.GridSearch(estimator, constraints, selection_rule='tradeoff_optimization', constraint_weight=0.5, grid_size=10, grid_limit=2.0, grid_offset=None, grid=None, sample_weight_name='sample_weight')

Estimator to perform a grid search given a blackbox estimator algorithm.

The approach used is taken from section 3.4 of Agarwal et al.[1].

Read more in the User Guide.

New in version 0.3.0.

Changed in version 0.4.6: Enabled for more than two sensitive feature values

Parameters:

• estimator (estimator) – An estimator implementing methods fit(X, y, sample_weight) and predict(X), where X is the matrix of features, y is the vector of labels (binary classification) or continuous values (regression), and sample_weight is a vector of weights. In binary classification labels y and predictions returned by predict(X) are either 0 or 1. In regression values y and predictions are continuous.

• constraints (fairlearn.reductions.Moment) – The disparity constraints expressed as moments

• selection_rule (str) – Specifies the procedure for selecting the best model found by the grid search. At the present time, the only valid value is “tradeoff_optimization” which minimizes a weighted sum of the error rate and constraint violation.

• constraint_weight (float) – When the selection_rule is “tradeoff_optimization” this specifies the relative weight put on the constraint violation when selecting the best model. The weight placed on the error rate will be 1-constraint_weight

• grid_size (int) – The number of Lagrange multipliers to generate in the grid

• grid_limit (float) – The largest Lagrange multiplier to generate. The grid will contain values distributed between -grid_limit and grid_limit by default

• grid_offset (pandas.DataFrame) – Shifts the grid of Lagrangian multiplier by that value. It is ‘0’ by default

• grid – Instead of supplying a size and limit for the grid, users may specify the exact set of Lagrange multipliers they desire using this argument.

• sample_weight_name (str) –

  Name of the argument to estimator.fit() which supplies the sample weights (defaults to sample_weight)

  New in version 0.5.0.

Methods

fit(X, y, **kwargs)	Run the grid search.
get_metadata_routing()	Get metadata routing of this object.
get_params([deep])	Get parameters for this estimator.
predict(X)	Provide a prediction using the best model found by the grid search.
predict_proba(X)	Return probability estimates from the best model found by the grid search.
set_params(**params)	Set the parameters of this estimator.

fit(X, y, **kwargs)

Run the grid search.

This will result in multiple copies of the estimator being made, and the fit(X) method of each one called.

Parameters:

• X (numpy.ndarray or pandas.DataFrame) – The feature matrix

• y (numpy.ndarray, pandas.DataFrame, pandas.Series, or list) – The label vector

• sensitive_features (numpy.ndarray, pandas.DataFrame, pandas.Series, or list (for now)) – A (currently) required keyword argument listing the feature used by the constraints 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

predict(X)

Provide a prediction using the best model found by the grid search.

This dispatches X to the predict(X) method of the selected estimator, and hence the return type is dependent on that method.

Parameters:

X (numpy.ndarray or pandas.DataFrame) – Feature data

predict_proba(X)

Return probability estimates from the best model found by the grid search.

The underlying estimator must support predict_proba(X) for this to work. The return type is determined by this method.

Parameters:

X (numpy.ndarray or pandas.DataFrame) – Feature data

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