fairlearn.preprocessing.PrototypeRepresentationLearner

class fairlearn.preprocessing.PrototypeRepresentationLearner(n_prototypes=2, reconstruct_weight=1.0, target_weight=1.0, fairness_weight=1.0, random_state=None, tol=1e-06, max_iter=1000)

A transformer and classifier that learns a latent representation of the input data to obfuscate the sensitive features while preserving the classification and reconstruction performance.

The model minimizes a loss function that consists of three terms: the reconstruction error, the classification error, and an approximation of the demographic parity difference.

Read more in the User Guide.

Parameters:

n_prototypesint, default=2

Number of prototypes to use in the latent representation.

reconstruct_weightfloat, default=1.0

Weight of the reconstruction error term in the objective function.

target_weightfloat, default=1.0

Weight of the classification error term in the objective function.

fairness_weightfloat, default=1.0

Weight of the fairness error term in the objective function.

random_stateint, np.random.RandomState, or None, default=None

Seed or random number generator for reproducibility.

tolfloat, default=1e-6

Convergence tolerance for the optimization algorithm.

max_iterint, default=1000

Maximum number of iterations for the optimization algorithm.

Attributes:

n_prototypesint

Number of prototypes to use in the latent representation.

reconstruct_weightfloat

Weight of the reconstruction error term in the objective function.

target_weightfloat

Weight of the classification error term in the objective function.

fairness_weightfloat

Weight of the fairness error term in the objective function.

random_stateint, np.random.RandomState, or None

Seed or random number generator for reproducibility.

tolfloat

Tolerance for the optimization algorithm.

max_iterint

Maximum number of iterations for the optimization algorithm.

coef_np.ndarray

Coefficients of the learned model.

n_iter_int

Number of iterations run by the optimization algorithm.

n_features_in_int

Number of features in the input data.

classes_np.ndarray or None

Unique classes in the target variable. Only set if target labels are provided during fitting, otherwise None.

Notes

The PrototypeRepresentationLearner implements the algorithms intoduced in Zemel et al. [1].

If no sensitive features are provided during fitting, the loss function will not include the fairness error term.

If no target labels are provided during fitting, the loss function will not include the classification error term and the model will not be able to predict probabilities or labels.

References

[1]

Rich Zemel, Yu Wu, Kevin Swersky, Toni Pitassi, and Cynthia Dwork. Learning fair representations. In Sanjoy Dasgupta and David McAllester, editors, Proceedings of the 30th International Conference on Machine Learning, volume 28 of Proceedings of Machine Learning Research, 325–333. Atlanta, Georgia, USA, 17–19 Jun 2013. PMLR. URL: https://proceedings.mlr.press/v28/zemel13.html.

Examples

>>> import numpy as np
>>> from fairlearn.preprocessing import PrototypeRepresentationLearner
>>> X = np.array([[0, 1], [1, 0], [0, 0], [1, 1]])
>>> y = np.array([0, 1, 0, 1])
>>> sensitive_features = np.array([0, 0, 1, 1])
>>> prl = PrototypeRepresentationLearner(n_prototypes=2, random_state=42)
>>> prl.fit(X, y, sensitive_features=sensitive_features)
PrototypeRepresentationLearner(random_state=42)
>>> X_transformed = prl.transform(X)
>>> y_pred = prl.predict(X)

fit(X, y=None, *, sensitive_features=None)

Fit the Prototype Representation Learner to the provided data.

Return type:

PrototypeRepresentationLearner

Parameters:

Xarray_like of shape (n_samples, n_features)

The input samples.

yarray_like of shape (n_samples,) or None, default=None

The target values.

sensitive_featuresarray_like or None, default=None

Sensitive features to be considered whose groups will be used to promote demographic parity. If None, the fairness error term will not be included in the loss function.

Returns:

selfPrototypeRepresentationLearner

Returns the fitted instance.

fit_transform(X, y=None, **fit_params)

Fit to data, then transform it.

Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.

Parameters:

Xarray_like of shape (n_samples, n_features)

Input samples.

yarray_like of shape (n_samples,) or (n_samples, n_outputs), default=None

Target values (None for unsupervised transformations).

**fit_paramsdict

Additional fit parameters. Pass only if the estimator accepts additional params in its fit method.

Returns:

X_newndarray array of shape (n_samples, n_features_new)

Transformed array.

get_metadata_routing()

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest

A MetadataRequest encapsulating routing information.

get_params(deep=True)

Get parameters for this estimator.

Parameters:

deepbool, default=True

If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict

Parameter names mapped to their values.

predict(X)

Predict the labels for the given input data.

Return type:

ndarray

Parameters:

Xarray_like of shape (n_samples, n_features)

The input data to predict.

Returns:

np.ndarray

The predicted labels for the input data.

Raises:

NotFittedError

If the estimator is not fitted yet.

ValueError

If no labels were provided during fitting.

predict_proba(X)

Predict class probabilities for the input samples X.

Return type:

ndarray

Parameters:

Xarray_like of shape (n_samples, n_features)

The input samples.

Returns:

np.ndarray of shape (n_samples, 2)

The class probabilities of the input samples. The first column represents the probability of the negative class, and the second column represents the probability of the positive class.

Raises:

NotFittedError

If the estimator is not fitted yet.

ValueError

If no labels were provided during fitting.

score(X, y, sample_weight=None)

Return accuracy on provided data and labels.

In multi-label classification, this is the subset accuracy which is a harsh metric since you require for each sample that each label set be correctly predicted.

Parameters:

Xarray_like of shape (n_samples, n_features)

Test samples.

yarray_like of shape (n_samples,) or (n_samples, n_outputs)

True labels for X.

sample_weightarray_like of shape (n_samples,), default=None

Sample weights.

Returns:

scorefloat

Mean accuracy of self.predict(X) w.r.t. y.

set_fit_request(*, sensitive_features: bool | None | str = '$UNCHANGED$') → PrototypeRepresentationLearner

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:

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

Metadata routing for sensitive_features parameter in fit.

Returns:

selfobject

The updated object.

set_output(*, transform=None)

Set output container.

Refer to the user guide for more details and Introducing the set_output API for an example on how to use the API.

Parameters:

transform{“default”, “pandas”, “polars”}, default=None

Configure output of transform and fit_transform.

• “default”: Default output format of a transformer

• “pandas”: DataFrame output

• “polars”: Polars output

• None: Transform configuration is unchanged

Added in version 1.4: “polars” option was added.

Returns:

selfestimator instance

Estimator instance.

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:

**paramsdict

Estimator parameters.

Returns:

selfestimator instance

Estimator instance.

set_score_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → PrototypeRepresentationLearner

Configure whether metadata should be requested to be passed to the score 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 score 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 score.

• 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:

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

Metadata routing for sample_weight parameter in score.

Returns:

selfobject

The updated object.

transform(X)

Transform the input data X using the learned prototype representation.

Each sample is transformed to its associated learned latent mapping, i.e. the softmax of its negative distance to the prototypes.

Return type:

ndarray

Parameters:

Xarray_like of shape (n_samples, n_features)

The input data to transform.

Returns:

np.ndarray

The transformed data.

Notes

This method checks if the model is fitted, validates the input data, and then applies the learned prototype representation.

property alpha_: ndarray

classes_: ndarray | None

coef_: ndarray

fairness_weight: float

max_iter: int

n_features_in_: int

n_iter_: int

n_prototypes: int

property prototypes_: ndarray

random_state: int | RandomState | None

reconstruct_weight: float

target_weight: float

tol: float