fairlearn.adversarial package

Adversarial techniques to help mitigate unfairness.

class fairlearn.adversarial.AdversarialFairnessClassifier(*, backend='auto', predictor_model=[], adversary_model=[], predictor_optimizer='Adam', adversary_optimizer='Adam', constraints='demographic_parity', learning_rate=0.001, alpha=1.0, epochs=1, batch_size=32, shuffle=False, progress_updates=None, skip_validation=False, callbacks=None, cuda=None, warm_start=False, random_state=None)

Bases: fairlearn.adversarial._adversarial_mitigation._AdversarialFairness, sklearn.base.ClassifierMixin

Train PyTorch or TensorFlow classifiers while mitigating unfairness.

This estimator implements the supervised learning method proposed in “Mitigating Unwanted Biases with Adversarial Learning” [1]. The training algorithm takes as input two neural network models, a predictor model and an adversarial model, defined either as a PyTorch module or TensorFlow2 model. The API follows conventions of sklearn estimators.

The predictor model takes the features X as input and seeks to predict y. For binary classification, the predictor model should return a single real-valued score, which is transformed into a probability of the positive class via the logistic function (aka sigmoid), similarly to logistic regression. For multi-class classification, the predictor model should return a vector of real-valued scores, which are transformed into class probabilities via the softmax function, similarly to multinomial logistic regression. The training loss is the negative log likelihood (aka log loss, logistic loss, cross-entropy loss).

The adversarial model for demographic parity takes scores produced by the predictor model as input, and seeks to predict sensitive_features. Depending on the type of the provided sensitive features, the model should produce a scalar or vector output. Three types of sensitive features are supported: (1) a single binary feature; (2) a single discrete feature; (3) one or multiple real-valued features. For a single binary sensitive feature and a single discrete feature, the network outputs are transformed by the logistic function and the softmax function, respectively, and the loss is the negative log likelihood. For one or multiple real-valued features, the network output is left as is, and the loss is a square loss.

The adversarial model for equalized odds additionaly takes y as input. For multi-class classification, y is transformed using one-hot encoding.

Parameters

• backend (str, BackendEngine, default = 'auto') – The backend to use. Must be one of 'torch', 'tensorflow', or 'auto' which indicates PyTorch, TensorFlow, or to automatically infer the backend from the predictor_model. You can also pass in a BackendEngine class.

• predictor_model (list, torch.nn.Module, tf.keras.Model) – The predictor model to train. Instead of a neural network model, it is possible to pass a list \([k_1, k_2, \dots]\), where each \(k_i\) either indicates the number of nodes (if \(k_i\) is an integer) or an activation function (if \(k_i\) is a string) or a layer or activation function instance directly (if \(k_i\) is a callable). The default parameter is [], which indicates a neural network without any hidden layers. However, the number of nodes in the input and output layer are automatically inferred from data, and the final activation function (such as softmax for categorical predictors) are inferred from data. If backend is specified, you cannot pass a model that uses a different backend.

• adversary_model (list, torch.nn.Module, tf.keras.Model) – The adversary model to train. Defined similarly as predictor_model. Must be the same type as the predictor_model.

• predictor_optimizer (str, torch.optim, tensorflow.keras.optimizers, callable, default = 'Adam') – The optimizer class to use. If a string is passed instead, this must be either ‘SGD’ or ‘Adam’. A corresponding SGD or Adam optimizer is initialized with the given predictor model and learning rate. If an instance of a subclass of torch.optim.Optimizer or tensorflow.keras.optimizers.Optimizer is passed, this is used directly. If a callable fn is passed, we call this callable and pass our model, and set the result of this call as the optimizer, so: predictor_optimizer=fn(predictor_model).

• adversary_optimizer (str, torch.optim, tensorflow.keras.optimizers, callable, default = 'Adam') – The optimizer class to use. Defined similarly as predictor_optimizer.

• constraints (str, default = 'demographic_parity') – The fairness constraint. Must be either ‘demographic_parity’ or ‘equalized_odds’.

• learning_rate (float, default = 0.001) – A small number greater than zero to set as a learning rate.

• alpha (float, default = 1.0) – A small number \(\alpha\) as specified in the paper. It is the factor that balances the training towards predicting y (choose \(\alpha\) closer to zero) or enforcing fairness constraint (choose larger \(\alpha\)).

• epochs (int, default = 1) – Number of epochs to train for.

• batch_size (int, default = 32) – Batch size. For no batching, set this to -1.

• shuffle (bool, default = False) – When true, shuffle the data before every epoch (including the first).

• progress_updates (number, optional, default = None) – If a number \(t\) is provided, we print an update about the training loop after processing a batch and \(t\) seconds have passed since the previous update.

• skip_validation (bool, default = False) – Skip the validation of the data. Useful because validate_input is a costly operation, and we may instead pass all data to validate_input at an earlier stage. Note that not only checking X is skipped, but also no tranform is applied to y and sensitive_features.

• callbacks (callable) – Callback function, called after every batch. For instance useable when wanting to validate. A list of callback functions can also be provided. Each callback function is passed two arguments self (the estimator instance) and step (the completed iteration), and may return a Boolean value. If the returned value is True, the optimization algorithm terminates. This can be used to implement early stopping.

• cuda (str, default = None) – A string to indicate which device to use when training. For instance, set cuda='cuda:0' to train on the first GPU. Only for PyTorch backend.

• warm_start (bool, default = False) – Normally, when set to False, a call to fit() triggers reinitialization, which discards the models and intializes them again. Setting to True triggers reuse of these models. Note: if pre-initialized models are passed, the models (and their parameters) are never discarded.

• random_state (int, RandomState, default = None) – Controls the randomized aspects of this algorithm, such as shuffling. Useful to get reproducible output across multiple function calls.

References

1

Zhang, Lemoine, Mitchell “Mitigating Unwanted Biases with Adversarial Learning”, AIES, 2018.

Methods

decision_function(X)	Compute predictor output for given test data.
fit(X, y, *[, sensitive_features])	Fit the model based on the given training data and sensitive features.
get_params([deep])	Get parameters for this estimator.
partial_fit(X, y, *[, sensitive_features])	Perform one epoch on given samples and update model.
predict(X)	Compute predictions for given test data.
score(X, y[, sample_weight])	Return the mean accuracy on the given test data and labels.
set_params(**params)	Set the parameters of this estimator.

class fairlearn.adversarial.AdversarialFairnessRegressor(*, backend='auto', predictor_model=[], adversary_model=[], predictor_optimizer='Adam', adversary_optimizer='Adam', constraints='demographic_parity', learning_rate=0.001, alpha=1.0, epochs=1, batch_size=32, shuffle=False, progress_updates=None, skip_validation=False, callbacks=None, cuda=None, warm_start=False, random_state=None)

Bases: fairlearn.adversarial._adversarial_mitigation._AdversarialFairness, sklearn.base.RegressorMixin

Train PyTorch or TensorFlow regressors while mitigating unfairness.

This estimator implements the supervised learning method proposed in “Mitigating Unwanted Biases with Adversarial Learning” [1]. The training algorithm takes as input two neural network models, a predictor model and an adversarial model, defined either as a PyTorch module or TensorFlow2 model. The API follows conventions of sklearn estimators.

The regressor model takes the features X as input and seeks to predict y. The training loss is measured using the squared error.

The adversarial model for demographic parity takes scores produced by the predictor model as input, and seeks to predict sensitive_features. Depending on the type of the provided sensitive features, the model should produce a scalar or vector output. Three types of sensitive features are supported: (1) a single binary feature; (2) a single discrete feature; (3) one or multiple real-valued features. For a single binary sensitive feature and a single discrete feature, the network outputs are transformed by the logistic function and the softmax function, respectively, and the loss is the negative log likelihood. For one or multiple real-valued features, the network output is left as is, and the loss is a square loss.

The adversarial model for equalized odds additionaly takes y as input.

Parameters

• backend (str, BackendEngine, default = 'auto') – The backend to use. Must be one of 'torch', 'tensorflow', or 'auto' which indicates PyTorch, TensorFlow, or to automatically infer the backend from the predictor_model. You can also pass in a BackendEngine class.

• predictor_model (list, torch.nn.Module, tf.keras.Model) – The predictor model to train. Instead of a neural network model, it is possible to pass a list \([k_1, k_2, \dots]\), where each \(k_i\) either indicates the number of nodes (if \(k_i\) is an integer) or an activation function (if \(k_i\) is a string) or a layer or activation function instance directly (if \(k_i\) is a callable). The default parameter is [], which indicates a neural network without any hidden layers. However, the number of nodes in the input and output layer are automatically inferred from data, and the final activation function (such as softmax for categorical predictors) are inferred from data. If backend is specified, you cannot pass a model that uses a different backend.

• adversary_model (list, torch.nn.Module, tf.keras.Model) – The adversary model to train. Defined similarly as predictor_model. Must be the same type as the predictor_model.

• predictor_optimizer (str, torch.optim, tensorflow.keras.optimizers, callable, default = 'Adam') – The optimizer class to use. If a string is passed instead, this must be either ‘SGD’ or ‘Adam’. A corresponding SGD or Adam optimizer is initialized with the given predictor model and learning rate. If an instance of a subclass of torch.optim.Optimizer or tensorflow.keras.optimizers.Optimizer is passed, this is used directly. If a callable fn is passed, we call this callable and pass our model, and set the result of this call as the optimizer, so: predictor_optimizer=fn(predictor_model).

• adversary_optimizer (str, torch.optim, tensorflow.keras.optimizers, callable, default = 'Adam') – The optimizer class to use. Defined similarly as predictor_optimizer.

• constraints (str, default = 'demographic_parity') – The fairness constraint. Must be either ‘demographic_parity’ or ‘equalized_odds’.

• learning_rate (float, default = 0.001) – A small number greater than zero to set as a learning rate.

• alpha (float, default = 1.0) – A small number \(\alpha\) as specified in the paper. It is the factor that balances the training towards predicting y (choose \(\alpha\) closer to zero) or enforcing fairness constraint (choose larger \(\alpha\)).

• epochs (int, default = 1) – Number of epochs to train for.

• batch_size (int, default = 32) – Batch size. For no batching, set this to -1.

• shuffle (bool, default = False) – When true, shuffle the data before every epoch (including the first).

• progress_updates (number, optional, default = None) – If a number \(t\) is provided, we print an update about the training loop after processing a batch and \(t\) seconds have passed since the previous update.

• skip_validation (bool, default = False) – Skip the validation of the data. Useful because validate_input is a costly operation, and we may instead pass all data to validate_input at an earlier stage. Note that not only checking X is skipped, but also no tranform is applied to y and sensitive_features.

• callbacks (callable) – Callback function, called after every batch. For instance useable when wanting to validate. A list of callback functions can also be provided. Each callback function is passed two arguments self (the estimator instance) and step (the completed iteration), and may return a Boolean value. If the returned value is True, the optimization algorithm terminates. This can be used to implement early stopping.

• cuda (str, default = None) – A string to indicate which device to use when training. For instance, set cuda='cuda:0' to train on the first GPU. Only for PyTorch backend.

• warm_start (bool, default = False) – Normally, when set to False, a call to fit() triggers reinitialization, which discards the models and intializes them again. Setting to True triggers reuse of these models. Note: if pre-initialized models are passed, the models (and their parameters) are never discarded.

• random_state (int, RandomState, default = None) – Controls the randomized aspects of this algorithm, such as shuffling. Useful to get reproducible output across multiple function calls.

References

1

Zhang, Lemoine, Mitchell “Mitigating Unwanted Biases with Adversarial Learning”, AIES, 2018.

Methods

decision_function(X)	Compute predictor output for given test data.
fit(X, y, *[, sensitive_features])	Fit the model based on the given training data and sensitive features.
get_params([deep])	Get parameters for this estimator.
partial_fit(X, y, *[, sensitive_features])	Perform one epoch on given samples and update model.
predict(X)	Compute predictions for given test data.
score(X, y[, sample_weight])	Return the coefficient of determination of the prediction.
set_params(**params)	Set the parameters of this estimator.