NICE (Nearest Instance Counterfactual Explanations) for Classification Tasks

Source: R/NICEClassif.R

NICE (Brughmans and Martens 2021) searches for counterfactuals by iteratively replacing feature values of x_interest with the corresponding value of its most similar (optionally correctly classified) instance x_nn.

Details

NICE starts the counterfactual search for x_interest by finding its most similar (optionally) correctly classified neighbor x_nn.
In the first iteration, NICE creates new instances by replacing a different feature value of x_interest with the corresponding value of x_nn in each new instance. Thus, if x_nn differs from x_interest in d features, d new instances are created.
Then, the reward values for the created instances are computed with the chosen reward function. Available reward functions are sparsity, proximity, and plausibility.
In the second iteration, NICE creates d-1 new instances by replacing a different feature value of the highest reward instance of the previous iteration with the corresponding value of x_interest, and so on.
If finish_early = TRUE, the algorithm terminates when the predicted desired_class probability for the highest reward instance is in the interval desired_prob; if finish_early = FALSE, the algorithm continues until x_nn is recreated.
Once the algorithm terminated, it depends on return_multiple which instances are returned as counterfactuals: if return_multiple = FALSE, then only the highest reward instance in the last iteration is returned as counterfactual; if return_multiple = TRUE, then all instances (of all iterations) whose predicted desired_class probability is in the interval desired_prob are returned as counterfactuals.

If finish_early = FALSE and return_multiple = FALSE, then x_nn is returned as single counterfactual.

This NICE implementation corresponds to the original version of Brughmans and Martens (2021) when return_multiple = FALSE, finish_early = TRUE, and x_nn_correct = TRUE.

References

Brughmans, D., & Martens, D. (2021). NICE: An Algorithm for Nearest Instance Counterfactual Explanations. arXiv 2104.07411 v2.

Gower, J. C. (1971), "A general coefficient of similarity and some of its properties". Biometrics, 27, 623–637.

Active bindings

x_nn

(logical(1))
The most similar (optionally) correctly classified instance of x_interest.

archive

(list())
A list that stores the history of the algorithm run. For each algorithm iteration, it has one element containing a data.table, which stores all created instances of this iteration together with their reward values and their predictions.

Methods

Public methods

Inherited methods

Method new()

Create a new NICEClassif object.

Usage

NICEClassif$new(
  predictor,
  optimization = "sparsity",
  x_nn_correct = TRUE,
  return_multiple = FALSE,
  finish_early = TRUE,
  distance_function = "gower"
)

Arguments

predictor

(Predictor)
The object (created with iml::Predictor$new()) holding the machine learning model and the data.

optimization

(character(1))
The reward function to optimize. Can be sparsity (default), proximity or plausibility.

x_nn_correct

(logical(1))
Should only correctly classified data points in predictor$data$X be considered for the most similar instance search? Default is TRUE.

return_multiple

(logical(1))
Should multiple counterfactuals be returned? If TRUE, the algorithm returns all created instances whose desired_class prediction is in the interval desired_prob. For more information, see the Details section.

finish_early

(logical(1))
Should the algorithm terminate after an iteration in which the desired_class prediction for the highest reward instance is in the interval desired_prob. If FALSE, the algorithm continues until x_nn is recreated.

distance_function

(function() | 'gower' | 'gower_c')
The distance function used to compute the distances between x_interest and the training data points for finding x_nn. If optimization is set to proximity, the distance function is also used for calculating the distance between candidates and x_interest. Either the name of an already implemented distance function ('gower' or 'gower_c') or a function is allowed as input. If set to 'gower' (default), then Gower's distance (Gower 1971) is used; if set to 'gower_c', a C-based more efficient version of Gower's distance is used. A function must have three arguments x, y, and data and should return a double matrix with nrow(x) rows and maximum nrow(y) columns.

Method clone()

The objects of this class are cloneable with this method.

Usage

NICEClassif$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

if (require("randomForest")) {
  # Train a model
  rf = randomForest(Species ~ ., data = iris)
  # Create a predictor object
  predictor = iml::Predictor$new(rf, type = "prob")
  # Find counterfactuals
  nice_classif = NICEClassif$new(predictor)
  cfactuals = nice_classif$find_counterfactuals(
    x_interest = iris[150L, ], desired_class = "versicolor", desired_prob = c(0.5, 1)
  )
  # Print the results
  cfactuals$data
  # Print archive
  nice_classif$archive
}
#> [[1]]
#>    Sepal.Length Sepal.Width Petal.Length Petal.Width reward setosa versicolor
#>           <num>       <num>        <num>       <num>  <num>  <num>      <num>
#> 1:          5.9         3.2          5.1         1.8  0.120      0      0.162
#> 2:          5.9         3.0          4.8         1.8  0.308      0      0.350
#>    virginica
#>        <num>
#> 1:     0.838
#> 2:     0.650
#> 
#> [[2]]
#>    Sepal.Length Sepal.Width Petal.Length Petal.Width reward setosa versicolor
#>           <num>       <num>        <num>       <num>  <num>  <num>      <num>
#> 1:          5.9         3.2          4.8         1.8   0.15      0      0.638
#>    virginica
#>        <num>
#> 1:     0.362
#>