Repository files navigation

Thecounterfactuals package provides various (model-agnostic)counterfactual explanation methods via a unified R6-based interface.

Counterfactual explanation methods address questions of the form: “Forinput, the model predicted. What needs to be changed in for the model to predict a desired outcome instead?”.
Denied loan applications serve as a common example; here acounterfactual explanation (or counterfactual for short) could be: “Theloan was denied because the amount of €30k is too high given the income.If the amount had been €20k, the loan would have been granted.”

For an introduction to counterfactual explanation methods, we recommendChapter 9.3 of theInterpretable Machine Learningbook by ChristophMolnar. The package is based on the R code underlying the paperMulti-Objective Counterfactual Explanations(MOC).

The following counterfactual explanation methods are currentlyimplemented:

• Multi-Objective Counterfactual Explanations(MOC)
• Nearest Instance Counterfactual Explanations(NICE) (an extended version)
• WhatIf (an extended version)

You can install the development version fromGitHub with:

# install.packages("devtools")devtools::install_github("dandls/counterfactuals")

In this example, we train arandomForest on theiris dataset andexamine how a givenvirginica observation would have to change inorder to be classified asversicolor.

library(counterfactuals)library(randomForest)library(iml)

First, we train arandomForest model to predict the target variableSpecies, omitting one observation from the training data, which isx_interest (the observation for which we want to find counterfactuals).

rf= randomForest(Species~.,data=iris[-150L, ])

We then create animl::Predictorobject, which serves as a wrapper for different model types; it containsthe model and the data for its analysis.

predictor=Predictor$new(rf,type="prob")

Forx_interest, the model predicts a probability of 8% for classversicolor.

x_interest=iris[150L, ]predictor$predict(x_interest)#>   setosa versicolor virginica#> 1      0       0.08      0.92

Now, we examine what needs to be changed inx_interest so that themodel predicts a probability of at least 50% for classversicolor.

Here, we want to apply WhatIf and since it is a classification task, wecreate aWhatIfClassif object.

wi_classif=WhatIfClassif$new(predictor,n_counterfactuals=5L)

Then, we use thefind_counterfactuals() method to find counterfactualsforx_interest.

cfactuals=wi_classif$find_counterfactuals(x_interest,desired_class="versicolor",desired_prob= c(0.5,1))

cfactuals is aCounterfactuals object that contains thecounterfactuals and has several methods for their evaluation andvisualization.

cfactuals#> 5 Counterfactual(s)#>#> Desired class: versicolor#> Desired predicted probability range: [0.5, 1]#>#> Head:#>    Sepal.Length Sepal.Width Petal.Length Petal.Width#> 1:          5.9         3.2          4.8         1.8#> 2:          6.0         2.7          5.1         1.6#> 3:          5.9         3.0          4.2         1.5

The counterfactuals are stored in thedata field.

cfactuals$data#>    Sepal.Length Sepal.Width Petal.Length Petal.Width#> 1:          5.9         3.2          4.8         1.8#> 2:          6.0         2.7          5.1         1.6#> 3:          5.9         3.0          4.2         1.5#> 4:          6.7         3.0          5.0         1.7#> 5:          6.0         2.9          4.5         1.5

With theevaluate() method, we can evaluate the counterfactuals usingvarious quality measures.

cfactuals$evaluate()#>    Sepal.Length Sepal.Width Petal.Length Petal.Width dist_x_interest no_changed dist_train dist_target minimality#> 1:          5.9         3.2          4.8         1.8      0.03354520          2          0           0          0#> 2:          6.0         2.7          5.1         1.6      0.05902778          3          0           0          2#> 3:          5.9         3.0          4.2         1.5      0.06938559          2          0           0          0#> 4:          6.7         3.0          5.0         1.7      0.07020951          3          0           0          1#> 5:          6.0         2.9          4.5         1.5      0.07403484          4          0           0          2

One visualization option is to plot the frequency of feature changesacross all counterfactuals using theplot_freq_of_feature_changes()method.

cfactuals$plot_freq_of_feature_changes()

Another visualization option is a parallel plot—created with theplot_parallel() method—that connects the (scaled) feature values ofeach counterfactual and highlightsx_interest in blue.

cfactuals$plot_parallel()

Each of the implemented R6 Classes has its own documentation.Counterfactual generation methods can be accessed, e.g., via?WhatIfClassif for the WhatIf method applied to a classification task.The documentation for its parent class can be accessed via?CounterfactualMethodClassif and?CounterfactualMethod.For notes on the evaluation and visualization methods for generated counterfactuals - independent on the method that was used -?Counterfactuals should be consulted.Class methods can also be found via??<methodname>, e.g.,??find_counterfactuals will point to the help page of theCounterfactualMethodClassif class.