Recourse Methods

The recourse method module contains

  • a Catalog with pre-implemented and ready-to-use recourse methods for arbitrary datasets and black-box-models or

  • an Interface to implement new recourse methods for benchmarking and comparison.

Example implementations for both use-cases can be found in our section Examples.

Interface

class recourse_methods.api.recourse_method.RecourseMethod(mlmodel)

Abstract class to implement custom recourse methods for a given black-box-model.

Parameters
mlmodel: carla.models.MLModel

Black-box-classifier we want to discover.

Returns
None

Methods

get_counterfactuals:

Generate counterfactual examples for given factuals.

encode_normalize_order_factuals:

Uses encoder and scaler from black-box-model to preprocess data as needed.

encode_normalize_order_factuals(factuals, with_target=False)

Uses encoder and scaler from black-box-model to preprocess data as needed.

Parameters
factuals: pd.DataFrame

Not encoded and not normalised factual examples in two-dimensional shape (m, n).

with_target: bool, default: False

If True, the output DataFrame contains label information

Returns
pd.DataFrame

Encoded, normalized and ordered factual examples

abstract get_counterfactuals(factuals)

Generate counterfactual examples for given factuals.

Parameters
factuals: pd.DataFrame

Not encoded and not normalised factual examples in two-dimensional shape (m, n).

Returns
pd.DataFrame

Encoded and normalised counterfactual examples.

Catalog

The following catalog lists all currently implemented recourse methods. Important hyperparameters that are needed for each method are specified in the notes of each section, and have to be passed in the constructor as dictionary.

Actionable Recourse

class recourse_methods.catalog.actionable_recourse.model.ActionableRecourse(mlmodel, hyperparams, coeffs=None, intercepts=None)

Implementation of Actionable Recourse from Ustun et.al. [1]

Parameters
datacarla.data.Data

Dataset

mlmodelcarla.model.MLModel

Black-Box-Model

hyperparamsdict

Dictionary containing hyperparameters. See Notes below to see its content.

coeffsnp.ndArray, optional

Coefficients. Will be approximated by LIME if None

intercepts: np.ndArray, optional

Intercepts. Will be approximated by LIME if None

Notes

  • Hyperparams

    Hyperparameter contains important information for the recourse method to initialize. Please make sure to pass all values as dict with the following keys.

    • “fs_size”: int, default: 100

      Size of generated flipset.

    • “discretize”: bool, default: False

      Parameter for LIME sampling.

    • “sample”: boo, default: True

      Lime sampling around instance.

  • Restrictions
  • Warning
    • AR does not always find a counterfactual example. The probability of finding one raises for a high size of flip set.

1

Berk Ustun, Alexander Spangher, and Y. Liu. 2019. Actionable Recourse in Linear Classification. InProceedings of the Conference on Fairness, Accountability, and Transparency (FAT*)

Attributes
action_set

Contains dictionary with possible actions for every input feature.

Methods

get_counterfactuals:

Generate counterfactual examples for given factuals.

encode_normalize_order_factuals:

Uses encoder and scaler from black-box-model to preprocess data as needed.

property action_set

Contains dictionary with possible actions for every input feature.

Returns
dict
get_counterfactuals(factuals)

Generate counterfactual examples for given factuals.

Parameters
factuals: pd.DataFrame

Not encoded and not normalised factual examples in two-dimensional shape (m, n).

Returns
pd.DataFrame

Encoded and normalised counterfactual examples.

Return type

DataFrame

CCHVAE

class recourse_methods.catalog.cchvae.model.CCHVAE(mlmodel, hyperparams)

Implementation of CCHVAE [1]

Parameters
mlmodelcarla.model.MLModel

Black-Box-Model

hyperparamsdict

Dictionary containing hyperparameters. See Notes below to see its content.

Notes

  • Hyperparams

    Hyperparameter contains important information for the recourse method to initialize. Please make sure to pass all values as dict with the following keys.

    • “data_name”: str

      name of the dataset

    • “n_search_samples”: int, default: 300

      Number of generated candidate counterfactuals.

    • “p_norm”: {1, 2}

      Defines L_p norm for distance calculation.

    • “step”: float, default: 0.1

      Step size for each generated candidate counterfactual.

    • “max_iter”: int, default: 1000

      Number of iterations per factual instance.

    • “clamp”: bool, default: True

      Feature values will be clamped between 0 and 1

    • “binary_cat_features”: bool, default: True

      If true, the encoding of x is done by drop_if_binary.

    • “vae_params”: Dict

      With parameter for VAE.

      • “layers”: list

        List with number of neurons per layer.

      • “train”: bool, default: True

        Decides if a new Autoencoder will be learned.

      • “lambda_reg”: float, default: 1e-6

        Hyperparameter for variational autoencoder.

      • “epochs”: int, default: 5

        Number of epochs to train VAE

      • “lr”: float, default: 1e-3

        Learning rate for VAE training

      • “batch_size”: int, default: 32

        Batch-size for VAE training

1

Pawelczyk, Martin, Klaus Broelemann and Gjergji Kasneci. “Learning Model-Agnostic Counterfactual Explanations for Tabular Data.” Proceedings of The Web Conference 2020 (2020): n. pag..

Methods

get_counterfactuals:

Generate counterfactual examples for given factuals.

encode_normalize_order_factuals:

Uses encoder and scaler from black-box-model to preprocess data as needed.

get_counterfactuals(factuals)
Return type

DataFrame

CEM

class recourse_methods.catalog.cem.model.CEM(sess, mlmodel, hyperparams)

Implementation of CEM from Dhurandhar et.al. [1]. CEM needs an variational autoencoder to generate counterfactual examples. By setting the train_ae key to True in hyperparams, a tensorflow VAE will be trained.

Parameters
mlmodelcarla.model.MLModel

Black-Box-Model

hyperparamsdict

Dictionary containing hyperparameters. See notes below for its contents.

Notes

  • Hyperparams

    Hyperparameter contains important information for the recourse method to initialize. Please make sure to pass all values as dict with the following keys.

    • “kappa”: float

      Hyperparameter for CEM

    • “init_learning_rate”: float

      Learning rate for CEM optimization

    • “binary_search_steps”: int

      Hyperparameter for CEM

    • “max_iterations”: int

      Number of maximum iterations to find a counterfactual example.

    • “initial_const”: int

      Hyperparameter for CEM

    • “beta”: float

      Hyperparameter for CEM

    • “gamma”: float

      Hyperparameter for CEM

    • “mode”: {“PN”, “PP”}

      Mode for CEM

    • “num_classes”: int.

      Currently only binary classifier are supported

    • “data_name”: str

      Identificates the loaded or saved autoencoder model

    • “ae_params:” dict

      Initialisation and training parameter for the autoencoder model

      • “hidden_layer”: list

        Number of neurons and layer of autoencoder.

      • “train_ae”: bool

        If True, an autoencoder will be trained and saved

      • “epochs”: int

        Number of training epochs for autoencoder

1

Amit Dhurandhar, Pin-Yu Chen, Ronny Luss, Chun-Chen Tu, Paishun Ting, Karthikeyan Shanmugam,and Payel Das. 2018. Explanations based on the Missing: Towards Contrastive Explanations with Pertinent Negatives. In Advances in Neural Information Processing Systems344(NeurIPS).

Methods

get_counterfactuals:

Generate counterfactual examples for given factuals.

encode_normalize_order_factuals:

Uses encoder and scaler from black-box-model to preprocess data as needed.

get_counterfactuals(factuals)

Compute a certain number of counterfactuals per factual example.

Parameters
factualspd.DataFrame

DataFrame containing all samples for which we want to generate counterfactual examples. All instances should belong to the same class.

Return type

DataFrame

CLUE

class recourse_methods.catalog.clue.model.Clue(data, mlmodel, hyperparams)

Implementation of CLUE from Antorán et.al. [1]. CLUE needs an variational autoencoder to generate counterfactual examples. By setting the train_ae key to True in hyperparams, a Pytorch VAE will be trained.

Parameters
datadata.api.Data

Underlying dataset we want to build counterfactuals for.

mlmodelcarla.model.MLModel

Black-Box-Model

hyperparamsdict

Dictionary containing hyperparameters. See notes below for its contents.

Notes

  • Hyperparams

    Hyperparameter contains important information for the recourse method to initialize. Please make sure to pass all values as dict with the following keys.

    • “data_name”: str

      Identifies the loaded or saved autoencoder model

    • “train_vae”: bool

      Decides whether to load or train a vae

    • “width”: int

      Structure for VAE

    • “depth”: int

      Structure for VAE

    • “latent_dim”: int

      Structure for VAE

    • “batch_size”: int

      Structure for VAE

    • “epochs”: int

      Structure for VAE

    • “lr”: int

      Structure for VAE

    • “early_stop”: int

      Structure for VAE

1

Javier Antorán, Umang Bhatt, Tameem Adel, Adrian Weller, and José Miguel Hernández-Lobato. Getting a CLUE: A Method for Explaining Uncertainty Estimates. In International Conference on Learning Representations (ICLR).

Methods

get_counterfactuals:

Generate counterfactual examples for given factuals.

encode_normalize_order_factuals:

Uses encoder and scaler from black-box-model to preprocess data as needed.

get_counterfactuals(factuals)
Return type

DataFrame

Dice

class recourse_methods.catalog.dice.model.Dice(mlmodel, hyperparams)

Implementation of Dice from Mothilal et.al. [1].

Parameters
mlmodelcarla.model.MLModel

Black-Box-Model

hyperparamsdict

Dictionary containing hyperparameters. See notes below for its contents.

Notes

  • Hyperparams

    Hyperparameter contains important information for the recourse method to initialize. Please make sure to pass all values as dict with the following keys.

    • “num”: int, default: 1

      Number of counterfactuals per factual to generate

    • “desired_class”: int, default: 1

      Given a binary class label, the desired class a counterfactual should have (e.g., 0 or 1)

    • “posthoc_sparsity_param”: float, default: 0.1

      Fraction of post-hoc preprocessing steps.

  • Restrictions:
    • Only the model agnostic approach (backend: sklearn) is used in our implementation.

    • ML model needs to have a transformation pipeline for normalization, encoding and feature order. See pipelining at carla/models/catalog/catalog.py for an example ML model class implementation

1

R. K. Mothilal, Amit Sharma, and Chenhao Tan. 2020. Explaining machine learning classifiers through diverse counterfactual explanations

Methods

get_counterfactuals:

Generate counterfactual examples for given factuals.

encode_normalize_order_factuals:

Uses encoder and scaler from black-box-model to preprocess data as needed.

get_counterfactuals(factuals)

Generate counterfactual examples for given factuals.

Parameters
factuals: pd.DataFrame

Not encoded and not normalised factual examples in two-dimensional shape (m, n).

Returns
pd.DataFrame

Encoded and normalised counterfactual examples.

Return type

DataFrame

FACE

class recourse_methods.catalog.face.model.Face(mlmodel, hyperparams)

Implementation of FACE from Poyiadzi et.al. [1].

Parameters
mlmodelcarla.model.MLModel

Black-Box-Model

hyperparamsdict

Dictionary containing hyperparameters. See notes below for its contents.

Notes

  • Hyperparams

    Hyperparameter contains important information for the recourse method to initialize. Please make sure to pass all values as dict with the following keys.

    • “mode”: {“knn”, “epsilon”},

      Decides over type of FACE

    • “fraction”: float [0 < x < 1]

      determines fraction of data set to be used to construct neighbourhood graph

1

Rafael Poyiadzi, Kacper Sokol, Raul Santos-Rodriguez, Tijl De Bie, and Peter Flach. 2020. In Proceedings of the AAAI/ACM Conference on AI, Ethics, and Society (AIES)

Attributes
fraction

Controls the fraction of the used dataset to build graph on.

mode

Sets and changes the type of FACE.

Methods

get_counterfactuals:

Generate counterfactual examples for given factuals.

encode_normalize_order_factuals:

Uses encoder and scaler from black-box-model to preprocess data as needed.

property fraction: float

Controls the fraction of the used dataset to build graph on.

Returns
float
Return type

float

get_counterfactuals(factuals)
Return type

DataFrame

property mode: str

Sets and changes the type of FACE. {“knn”, “epsilon”}

Returns
str
Return type

str

Growing Spheres

class recourse_methods.catalog.growing_spheres.model.GrowingSpheres(mlmodel, hyperparams=None)

Implementation of Growing Spheres from Laugel et.al. [1].

Parameters
mlmodelcarla.model.MLModel

Black-Box-Model

hyperparamsdict

Growing Spheeres needs no hyperparams.

Notes

  • Restrictions

    Growing Spheres works at the moment only for data with dropped first column of binary categorical features.

1

Thibault Laugel, Marie-Jeanne Lesot, Christophe Marsala, Xavier Renard, and Marcin Detyniecki. 2017. Inverse Classification for Comparison-based Interpretability in Machine Learning. arXiv preprint arXiv:1712.08443(2017).

Methods

get_counterfactuals:

Generate counterfactual examples for given factuals.

encode_normalize_order_factuals:

Uses encoder and scaler from black-box-model to preprocess data as needed.

get_counterfactuals(factuals)
Return type

DataFrame

REVISE

class recourse_methods.catalog.revise.model.Revise(mlmodel, data, hyperparams)

Implementation of Revise from Joshi et.al. [1].

Parameters
mlmodelcarla.model.MLModel

Black-Box-Model

data: carla.data.Data

Dataset to perform on

hyperparamsdict

Dictionary containing hyperparameters. See notes below for its contents.

Notes

  • Hyperparams

    Hyperparameter contains important information for the recourse method to initialize. Please make sure to pass all values as dict with the following keys.

    • “data_name”: str

      name of the dataset

    • “lambda”: float, default: 0.5

      Decides how similar the counterfactual is to the factual

    • “optimizer”: {“adam”, “rmsprop”}

      Optimizer for generation of counterfactuals.

    • “lr”: float, default: 0.1

      Learning rate for Revise.

    • “max_iter”: int, default: 1000

      Number of iterations for Revise optimization.

    • “target_class”: List, default: [0, 1]

      List of one-hot-encoded target class.

    • “binary_cat_features”: bool, default: True

      If true, the encoding of x is done by drop_if_binary.

    • “vae_params”: Dict

      With parameter for VAE.

      • “layers”: list

        Number of neurons and layer of autoencoder.

      • “train”: bool

        Decides if a new Autoencoder will be learned.

      • “lambda_reg”: flot

        Hyperparameter for variational autoencoder.

      • “epochs”: int

        Number of epcchs to train VAE

      • “lr”: float

        Learning rate for VAE training

      • “batch_size”: int

        Batch-size for VAE training

1

Shalmali Joshi, Oluwasanmi Koyejo, Warut Vijitbenjaronk, Been Kim, and Joydeep Ghosh.2019. Towards Realistic Individual Recourse and Actionable Explanations in Black-BoxDecision Making Systems. arXiv preprint arXiv:1907.09615(2019).

Methods

get_counterfactuals:

Generate counterfactual examples for given factuals.

encode_normalize_order_factuals:

Uses encoder and scaler from black-box-model to preprocess data as needed.

get_counterfactuals(factuals)
Return type

DataFrame

Wachter

class recourse_methods.catalog.wachter.model.Wachter(*args: Any, **kwargs: Any)

Implementation of Wachter from Wachter et.al. [1].

Parameters
mlmodelcarla.model.MLModel

Black-Box-Model

hyperparamsdict

Dictionary containing hyperparameters. See notes below for its contents.

Notes

  • Hyperparams

    Hyperparameter contains important information for the recourse method to initialize. Please make sure to pass all values as dict with the following keys.

    • “feature_cost”: str, optional

      List with costs per feature.

    • “lr”: float, default: 0.01

      Learning rate for gradient descent.

    • “lambda_param”: float, default: 0.01

      Weight factor for feature_cost.

    • “n_iter”: int, defaul: 1000

      Maximum number of iteration.

    • “t_max_min”: float, default: 0.5

      Maximum time of search.

    • “norm”: int, default: 1

      L-norm to calculate cost.

    • “clamp”: bool, defaul: True

      If true, feature values will be clamped to (0, 1).

    • “loss_type”: {“MSE”, “BCE”}

      String for loss function.

    • “y_target” list, default: [0, 1]

      List of one-hot-encoded target class.

    • “binary_cat_features”: bool, default: True

      If true, the encoding of x is done by drop_if_binary.

1

Sandra Wachter, B. Mittelstadt, and Chris Russell. 2017. Counterfactual Explanations Withoutpening the Black Box: Automated Decisions and the GDPR. Cybersecurity(2017).

Methods

get_counterfactuals:

Generate counterfactual examples for given factuals.

encode_normalize_order_factuals:

Uses encoder and scaler from black-box-model to preprocess data as needed.

get_counterfactuals(factuals)
Return type

DataFrame