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.
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=None, 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 rises 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.
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

Causal Recourse

class recourse_methods.catalog.causal_recourse.model.CausalRecourse(mlmodel, hyperparams)

Implementation of causal recourse [1].

Parameters
mlmodelcarla.model.MLModel

Black-Box-Model

checked_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.

    • “optimization_approach”: {“brute_force”, “gradient_descent”}

      Choose which optimization approach to use.

    • “num_samples”: int

    • “scm”: CausalModel

      Class that contains the structural causal model, and has some useful helper methods.

    • “constraint_handle”: method

      Method that returns a boolean, true if constraint is met.

    • “sampler_handle”: method

      Method used to sample.

    1

    Karimi, A. H., Schölkopf, B., & Valera, I. (2021, March). Algorithmic recourse: from counterfactual

    explanations to interventions. In Proceedings of the 2021 ACM Conference on Fairness, Accountability, and Transparency (pp. 353-362).

Methods

get_counterfactuals:

Generate counterfactual examples for given factuals.
compute_optimal_action_set(factual_instance, constraint_handle, sampling_handle)
get_counterfactuals(factuals)
get_intervenable_nodes()
Return type

dict

recourse_methods.catalog.causal_recourse.model.powerset([1,2,3]) --> () (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)

CCHVAE

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

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.
get_counterfactuals(factuals)
Return type

DataFrame

CEM

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

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.
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=None)

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.
get_counterfactuals(factuals)
Return type

DataFrame

Dice

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

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.
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=None)

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.
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

FeatureTweak

code adapted from: https://github.com/upura/featureTweakPy

class recourse_methods.catalog.feature_tweak.model.FeatureTweak(mlmodel, hyperparams=None, cost_func=<function _L2_cost_func>)

Implementation of FeatureTweak [1].

Parameters
mlmodel: MLModelCatalog

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.

    • “eps”: float

1

Tolomei, G., Silvestri, F., Haines, A., & Lalmas, M. (2017, August). Interpretable predictions of tree-based ensembles via actionable feature tweaking. In Proceedings of the 23rd ACM SIGKDD international conference on knowledge discovery and data mining (pp. 465-474).

Methods

get_counterfactuals:

Generate counterfactual examples for given factuals.

esatisfactory_instance:

Return the epsilon satisfactory instance of x.

feature_tweaking:

Generate a single counterfactual by FeatureTweaking.
esatisfactory_instance(x, path_info)

return the epsilon satisfactory instance of x.

Parameters
x: np.ndarray

A single factual example.

path_info:

One path from the result of search_path(tree, class_labels, cf_label)

Returns
epsilon satisfactory instance
feature_tweaking(x, class_labels, cf_label)

Perform feature tweaking on a single factual example.

Parameters
x: np.ndarray

A single factual example.

class_labels: List[int]

List of possible class labels.

cf_label: int

What label the counterfactual should have.

Returns
counterfactual example
get_counterfactuals(factuals)
recourse_methods.catalog.feature_tweak.model.get_path_info(paths, threshold, feature)

Extract the path info from the parameters

Parameters
paths:

Paths trough the tree from root to leaves.

threshold: array of double

threshold[i] holds the threshold for the internal node i.

feature: array of int

feature[i] holds the feature to split on, for the internal node i.

Returns
dictionary where dict[i] contains node_id, inequality_symbol, threshold, and feature
recourse_methods.catalog.feature_tweak.model.search_path(tree, class_labels)

return path index list containing [{leaf node id, inequality symbol, threshold, feature index}].

Parameters
tree: sklearn.tree.DecisionTreeClassifier or xgboost.core.Booster

The classification tree.

class_labels:

All the possible class labels.

Returns
path_info

FOCUS

code adapted from: https://github.com/a-lucic/focus

class recourse_methods.catalog.focus.model.FOCUS(mlmodel, hyperparams=None)

Implementation of Focus [1].

Parameters
mlmodelcarla.model.MLModel

Black-Box-Model

checked_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.

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

      Determines the optimizer.

    • “n_class”: int

      Number of classes.

    • “n_iter”: int

      Number of iterations to run for.

    • “sigma”: float

      Parameter in sig(z) = (1 + exp(sigma * z)^-1, controls degree of approximation.

    • “temperature”: float

      Parameter in the softmax operation, also controls degreee of approximation.

    • “distance_weight”: float

      Determines the weight of the counterfactual distance in the loss.

    • “distance_func”: {“l1”, “l2”}

      Norm to be used.

1

Lucic, A., Oosterhuis, H., Haned, H., & de Rijke, M. (2018). FOCUS: Flexible optimizable counterfactual explanations for tree ensembles. arXiv preprint arXiv:1910.12199.

Methods

get_counterfactuals:

Generate counterfactual examples for given factuals.
get_counterfactuals(factuals)
Return type

DataFrame

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.
get_counterfactuals(factuals)
Return type

DataFrame

REVISE

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

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 epochs 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.
get_counterfactuals(factuals)
Return type

DataFrame

ROAR

class recourse_methods.catalog.roar.model.Roar(mlmodel, hyperparams, coeffs=None, intercepts=None)

Implementation of ROAR [1].

Parameters
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.

    • “feature_cost”: str, optional

      List with costs per feature.

    • “lr”: float, default: 0.01

      Learning rate for gradient descent.

    • “lambda_”: float, default: 0.01

      Weight factor for feature_cost.

    • “delta_max”: float, default: 0.01

      Maximum perturbation for weights

    • “t_max_min”: float, default: 0.5

      Maximum time of search.

    • “norm”: int, default: 1

      L-norm to calculate cost.

    • “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.

    • “discretize”: bool, default: False

      Parameter for LIME sampling.

    • “sample”: bool, default: True

      LIME sampling around instance.

    • “loss_threshold”: float, default: 0.001

      Threshold for loss difference

    • “lime_seed”: int, default: 0

      Seed when generating LIME coefficients

    • “seed”: int, default: 0

      Seed for torch when calculating counterfactuals

  • Restrictions

    • ROAR is only defined on linear models. To make it work for arbitrary non-linear networks we need to find coefficients for every instance, for example with lime.

    • Currently working only with Pytorch models.

  • Warning

    • Not guaranteed to find recourse.

1

Upadhyay, S., Joshi, S., & Lakkaraju, H. (2021). Towards Robust and Reliable Algorithmic Recourse. NeurIPS.

Methods

get_counterfactuals:

Generate counterfactual examples for given factuals.
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

Wachter

class recourse_methods.catalog.wachter.model.Wachter(mlmodel, hyperparams=None)

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, default: 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, default: 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.
get_counterfactuals(factuals)
Return type

DataFrame