Generating counterfactual explanations with any ML model

The goal of this notebook is to show how to generate CFs for ML models using frameworks other than TensorFlow or PyTorch. We show how to generate diverse CFs by three methods: 1. Independent random sampling of features (method_name='random') 2. Genetic algorithm (method_name='genetic') 3. Querying a KD tree (method_name='kdtree')

We use scikit-learn models for demonstration.

1. Independent random sampling of features

[1]:
# import DiCE
import dice_ml
from dice_ml.utils import helpers  # helper functions

from sklearn.compose import ColumnTransformer
from sklearn.model_selection import train_test_split
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler, OneHotEncoder
from sklearn.ensemble import RandomForestClassifier
[2]:
%load_ext autoreload
%autoreload 2

Loading dataset

We use the “adult” income dataset from UCI Machine Learning Repository (https://archive.ics.uci.edu/ml/datasets/adult). We transform the data as described in dice_ml.utils.helpers module.

[3]:
dataset = helpers.load_adult_income_dataset()
---------------------------------------------------------------------------
FileNotFoundError                         Traceback (most recent call last)
Input In [3], in <cell line: 1>()
----> 1 dataset = helpers.load_adult_income_dataset()

File /mnt/c/Users/amshar/code/dice/dice_ml/utils/helpers.py:25, in load_adult_income_dataset(only_train)
     19 def load_adult_income_dataset(only_train=True):
     20     """Loads adult income dataset from https://archive.ics.uci.edu/ml/datasets/Adult and prepares
     21        the data for data analysis based on https://rpubs.com/H_Zhu/235617
     22
     23     :return adult_data: returns preprocessed adult income dataset.
     24     """
---> 25     raw_data = np.genfromtxt('https://archive.ics.uci.edu/ml/machine-learning-databases/adult/adult.data',
     26                              delimiter=', ', dtype=str, invalid_raise=False)
     28     #  column names from "https://archive.ics.uci.edu/ml/datasets/Adult"
     29     column_names = ['age', 'workclass', 'fnlwgt', 'education', 'educational-num', 'marital-status', 'occupation',
     30                     'relationship', 'race', 'gender', 'capital-gain', 'capital-loss', 'hours-per-week', 'native-country',
     31                     'income']

File ~/python-envs/v3.8dowhy/lib/python3.8/site-packages/numpy/lib/npyio.py:1934, in genfromtxt(fname, dtype, comments, delimiter, skip_header, skip_footer, converters, missing_values, filling_values, usecols, names, excludelist, deletechars, replace_space, autostrip, case_sensitive, defaultfmt, unpack, usemask, loose, invalid_raise, max_rows, encoding, ndmin, like)
   1932     fname = os_fspath(fname)
   1933 if isinstance(fname, str):
-> 1934     fid = np.lib._datasource.open(fname, 'rt', encoding=encoding)
   1935     fid_ctx = contextlib.closing(fid)
   1936 else:

File ~/python-envs/v3.8dowhy/lib/python3.8/site-packages/numpy/lib/_datasource.py:193, in open(path, mode, destpath, encoding, newline)
    156 """
    157 Open `path` with `mode` and return the file object.
    158
   (...)
    189
    190 """
    192 ds = DataSource(destpath)
--> 193 return ds.open(path, mode, encoding=encoding, newline=newline)

File ~/python-envs/v3.8dowhy/lib/python3.8/site-packages/numpy/lib/_datasource.py:533, in DataSource.open(self, path, mode, encoding, newline)
    530     return _file_openers[ext](found, mode=mode,
    531                               encoding=encoding, newline=newline)
    532 else:
--> 533     raise FileNotFoundError(f"{path} not found.")

FileNotFoundError: https://archive.ics.uci.edu/ml/machine-learning-databases/adult/adult.data not found.
[4]:
dataset.head()
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [4], in <cell line: 1>()
----> 1 dataset.head()

NameError: name 'dataset' is not defined
[5]:
d = dice_ml.Data(dataframe=dataset, continuous_features=['age', 'hours_per_week'], outcome_name='income')
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [5], in <cell line: 1>()
----> 1 d = dice_ml.Data(dataframe=dataset, continuous_features=['age', 'hours_per_week'], outcome_name='income')

NameError: name 'dataset' is not defined

Training a custom ML model

Below, we build an ML model using scikit-learn to demonstrate how our methods can work with any sklearn model.

[6]:
target = dataset["income"]
# Split data into train and test
datasetX = dataset.drop("income", axis=1)
x_train, x_test, y_train, y_test = train_test_split(datasetX,
                                                    target,
                                                    test_size=0.2,
                                                    random_state=0,
                                                    stratify=target)

numerical = ["age", "hours_per_week"]
categorical = x_train.columns.difference(numerical)

# We create the preprocessing pipelines for both numeric and categorical data.
numeric_transformer = Pipeline(steps=[
    ('scaler', StandardScaler())])

categorical_transformer = Pipeline(steps=[
    ('onehot', OneHotEncoder(handle_unknown='ignore'))])

transformations = ColumnTransformer(
    transformers=[
        ('num', numeric_transformer, numerical),
        ('cat', categorical_transformer, categorical)])

# Append classifier to preprocessing pipeline.
# Now we have a full prediction pipeline.
clf = Pipeline(steps=[('preprocessor', transformations),
                      ('classifier', RandomForestClassifier())])
model = clf.fit(x_train, y_train)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [6], in <cell line: 1>()
----> 1 target = dataset["income"]
      2 # Split data into train and test
      3 datasetX = dataset.drop("income", axis=1)

NameError: name 'dataset' is not defined
[7]:
# provide the trained ML model to DiCE's model object
backend = 'sklearn'
m = dice_ml.Model(model=model, backend=backend)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [7], in <cell line: 3>()
      1 # provide the trained ML model to DiCE's model object
      2 backend = 'sklearn'
----> 3 m = dice_ml.Model(model=model, backend=backend)

NameError: name 'model' is not defined

Generate diverse counterfactuals

[8]:
# initiate DiCE
exp_random = dice_ml.Dice(d, m, method="random")
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [8], in <cell line: 2>()
      1 # initiate DiCE
----> 2 exp_random = dice_ml.Dice(d, m, method="random")

NameError: name 'd' is not defined
[9]:
query_instances = x_train[4:6]
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [9], in <cell line: 1>()
----> 1 query_instances = x_train[4:6]

NameError: name 'x_train' is not defined
[10]:
# generate counterfactuals
dice_exp_random = exp_random.generate_counterfactuals(query_instances, total_CFs=2, desired_class="opposite", verbose=False)

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [10], in <cell line: 2>()
      1 # generate counterfactuals
----> 2 dice_exp_random = exp_random.generate_counterfactuals(query_instances, total_CFs=2, desired_class="opposite", verbose=False)

NameError: name 'exp_random' is not defined
[11]:
dice_exp_random.visualize_as_dataframe(show_only_changes=True)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [11], in <cell line: 1>()
----> 1 dice_exp_random.visualize_as_dataframe(show_only_changes=True)

NameError: name 'dice_exp_random' is not defined

It can be observed that the random sampling method produces less sparse CFs in contrast to current DiCE’s implementation. The sparsity issue with random sampling worsens with increasing total_CFs

Further, different sets of counterfactuals can be generated with different random seeds.

[12]:
# generate counterfactuals
# default random seed is 17
dice_exp_random = exp_random.generate_counterfactuals(query_instances,
                                                      total_CFs=4,
                                                      desired_class="opposite",
                                                      random_seed=9)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [12], in <cell line: 3>()
      1 # generate counterfactuals
      2 # default random seed is 17
----> 3 dice_exp_random = exp_random.generate_counterfactuals(query_instances,
      4                                                       total_CFs=4,
      5                                                       desired_class="opposite",
      6                                                       random_seed=9)

NameError: name 'exp_random' is not defined
[13]:
dice_exp_random.visualize_as_dataframe(show_only_changes=True)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [13], in <cell line: 1>()
----> 1 dice_exp_random.visualize_as_dataframe(show_only_changes=True)

NameError: name 'dice_exp_random' is not defined

Selecting the features to vary

Here, you can ensure that DiCE varies only features that it makes sense to vary.

[14]:
# generate counterfactuals
dice_exp_random = exp_random.generate_counterfactuals(
        query_instances, total_CFs=4, desired_class="opposite",
        features_to_vary=['workclass', 'education', 'occupation', 'hours_per_week'])
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [14], in <cell line: 2>()
      1 # generate counterfactuals
----> 2 dice_exp_random = exp_random.generate_counterfactuals(
      3         query_instances, total_CFs=4, desired_class="opposite",
      4         features_to_vary=['workclass', 'education', 'occupation', 'hours_per_week'])

NameError: name 'exp_random' is not defined
[15]:
dice_exp_random.visualize_as_dataframe(show_only_changes=True)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [15], in <cell line: 1>()
----> 1 dice_exp_random.visualize_as_dataframe(show_only_changes=True)

NameError: name 'dice_exp_random' is not defined

Choosing feature ranges

Since the features are sampled randomly, they can freely vary across their range. In the below example, we show how range of continuous features can be controlled using permitted_range parameter that can now be passed during CF generation.

[16]:
# generate counterfactuals
dice_exp_random = exp_random.generate_counterfactuals(
    query_instances, total_CFs=4, desired_class="opposite",
    permitted_range={'age': [22, 50], 'hours_per_week': [40, 60]})
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [16], in <cell line: 2>()
      1 # generate counterfactuals
----> 2 dice_exp_random = exp_random.generate_counterfactuals(
      3     query_instances, total_CFs=4, desired_class="opposite",
      4     permitted_range={'age': [22, 50], 'hours_per_week': [40, 60]})

NameError: name 'exp_random' is not defined
[17]:
dice_exp_random.visualize_as_dataframe(show_only_changes=True)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [17], in <cell line: 1>()
----> 1 dice_exp_random.visualize_as_dataframe(show_only_changes=True)

NameError: name 'dice_exp_random' is not defined

2. Genetic Algorithm

Here, we show how to use DiCE can be used to generate CFs for any ML model by using the genetic algorithm to find the best counterfactuals close to the query point. The genetic algorithm converges quickly, and promotes diverse counterfactuals.

Training a custom ML model

Currently, the genetic algorithm method works with scikit-learn models. We will use the same model as shown previously in the notebook. Support for Tensorflow 1&2 and Pytorch will be implemented soon.

Generate diverse counterfactuals

[18]:
# initiate DiceGenetic
exp_genetic = dice_ml.Dice(d, m, method='genetic')
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [18], in <cell line: 2>()
      1 # initiate DiceGenetic
----> 2 exp_genetic = dice_ml.Dice(d, m, method='genetic')

NameError: name 'd' is not defined
[19]:
# generate counterfactuals
dice_exp_genetic = exp_genetic.generate_counterfactuals(query_instances, total_CFs=4, desired_class="opposite", verbose=True)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [19], in <cell line: 2>()
      1 # generate counterfactuals
----> 2 dice_exp_genetic = exp_genetic.generate_counterfactuals(query_instances, total_CFs=4, desired_class="opposite", verbose=True)

NameError: name 'exp_genetic' is not defined
[20]:
dice_exp_genetic.visualize_as_dataframe(show_only_changes=True)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [20], in <cell line: 1>()
----> 1 dice_exp_genetic.visualize_as_dataframe(show_only_changes=True)

NameError: name 'dice_exp_genetic' is not defined

We can also ensure that the genetic algorithm also only varies the features that you wish to vary

[21]:
# generate counterfactuals
dice_exp_genetic = exp_genetic.generate_counterfactuals(
    query_instances, total_CFs=2, desired_class="opposite",
    features_to_vary=['workclass', 'education', 'occupation', 'hours_per_week'])
dice_exp_genetic.visualize_as_dataframe(show_only_changes=True)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [21], in <cell line: 2>()
      1 # generate counterfactuals
----> 2 dice_exp_genetic = exp_genetic.generate_counterfactuals(
      3     query_instances, total_CFs=2, desired_class="opposite",
      4     features_to_vary=['workclass', 'education', 'occupation', 'hours_per_week'])
      5 dice_exp_genetic.visualize_as_dataframe(show_only_changes=True)

NameError: name 'exp_genetic' is not defined

You can also constrain the features to vary only within the permitted range

[22]:
# generate counterfactuals
dice_exp_genetic = exp_genetic.generate_counterfactuals(
    query_instances, total_CFs=2, desired_class="opposite",
    permitted_range={'age': [22, 50], 'hours_per_week': [40, 60]})
dice_exp_genetic.visualize_as_dataframe(show_only_changes=True)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [22], in <cell line: 2>()
      1 # generate counterfactuals
----> 2 dice_exp_genetic = exp_genetic.generate_counterfactuals(
      3     query_instances, total_CFs=2, desired_class="opposite",
      4     permitted_range={'age': [22, 50], 'hours_per_week': [40, 60]})
      5 dice_exp_genetic.visualize_as_dataframe(show_only_changes=True)

NameError: name 'exp_genetic' is not defined

3. Querying a KD Tree

Here, we show how to use DiCE can be used to generate CFs for any ML model by finding the closest points in the dataset that give the output as the desired class. We do this efficiently by building KD trees for each class, and querying the KD tree of the desired class to find the k closest counterfactuals from the dataset. The idea behind finding the closest points from the training data itself is to ensure that the counterfactuals displayed are feasible.

Training a custom ML model

Currently, the KD tree algorithm method works with scikit-learn models. Again, we will use the same model as shown previously in the notebook. Support for Tensorflow 1&2 and Pytorch will be implemented soon.

Generate diverse counterfactuals

[23]:
# initiate DiceKD
exp_KD = dice_ml.Dice(d, m, method='kdtree')
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [23], in <cell line: 2>()
      1 # initiate DiceKD
----> 2 exp_KD = dice_ml.Dice(d, m, method='kdtree')

NameError: name 'd' is not defined
[24]:
# generate counterfactuals
dice_exp_KD = exp_KD.generate_counterfactuals(query_instances, total_CFs=4, desired_class="opposite")
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [24], in <cell line: 2>()
      1 # generate counterfactuals
----> 2 dice_exp_KD = exp_KD.generate_counterfactuals(query_instances, total_CFs=4, desired_class="opposite")

NameError: name 'exp_KD' is not defined
[25]:
dice_exp_KD.visualize_as_dataframe(show_only_changes=True)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [25], in <cell line: 1>()
----> 1 dice_exp_KD.visualize_as_dataframe(show_only_changes=True)

NameError: name 'dice_exp_KD' is not defined

Selecting the features to vary

Here, again, you can vary only features that you wish to vary. Please note that the output counterfactuals are only from the training data. If you want other counterfactuals, please use the random or genetic method.

[26]:
# generate counterfactuals
dice_exp_KD = exp_KD.generate_counterfactuals(
    query_instances, total_CFs=4, desired_class="opposite",
    features_to_vary=['age', 'workclass', 'education', 'occupation', 'hours_per_week'])
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [26], in <cell line: 2>()
      1 # generate counterfactuals
----> 2 dice_exp_KD = exp_KD.generate_counterfactuals(
      3     query_instances, total_CFs=4, desired_class="opposite",
      4     features_to_vary=['age', 'workclass', 'education', 'occupation', 'hours_per_week'])

NameError: name 'exp_KD' is not defined
[27]:
dice_exp_KD.visualize_as_dataframe(show_only_changes=True)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [27], in <cell line: 1>()
----> 1 dice_exp_KD.visualize_as_dataframe(show_only_changes=True)

NameError: name 'dice_exp_KD' is not defined

Selecting the feature ranges

Here, you can control the ranges of continuous features.

[28]:
# generate counterfactuals
dice_exp_KD = exp_KD.generate_counterfactuals(
    query_instances, total_CFs=5, desired_class="opposite",
    permitted_range={'age': [30, 50], 'hours_per_week': [40, 60]})
dice_exp_KD.visualize_as_dataframe(show_only_changes=True)
---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Input In [28], in <cell line: 2>()
      1 # generate counterfactuals
----> 2 dice_exp_KD = exp_KD.generate_counterfactuals(
      3     query_instances, total_CFs=5, desired_class="opposite",
      4     permitted_range={'age': [30, 50], 'hours_per_week': [40, 60]})
      5 dice_exp_KD.visualize_as_dataframe(show_only_changes=True)

NameError: name 'exp_KD' is not defined