NICEClassif {counterfactuals} | R Documentation |

## NICE (Nearest Instance Counterfactual Explanations) for Classification Tasks

### Description

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`

.

### Super classes

`counterfactuals::CounterfactualMethod`

-> `counterfactuals::CounterfactualMethodClassif`

-> `NICEClassif`

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

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

### 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
}
```

*counterfactuals*version 0.1.4 Index]