A `Counterfactuals`

object should be created by the `$find_counterfactuals`

method of CounterfactualMethodRegr
or CounterfactualMethodClassif.
It contains the counterfactuals and has several methods for their evaluation and visualization.

`desired`

(

`list(1)`

|`list(2)`

)

A`list`

with the desired properties of the counterfactuals. For regression tasks it has one element`desired_outcome`

(CounterfactualMethodRegr) and for classification tasks two elements`desired_class`

and`desired_prob`

(CounterfactualMethodClassif).`data`

(

`data.table`

)

The counterfactuals for`x_interest`

.`x_interest`

(

`data.table(1)`

)

A single row with the observation of interest.`distance_function`

(

`function()`

)

The distance function used in the second and fourth evaluation measure. The function must have three arguments:`x`

,`y`

, and`data`

and return a`numeric`

matrix. If set to`NULL`

(default), then Gower distance (Gower 1971) is used.`method`

(

`character`

)

A single row with the observation of interest.

`new()`

Creates a new `Counterfactuals`

object.
This method should only be called by the `$find_counterfactuals`

methods of CounterfactualMethodRegr
and CounterfactualMethodClassif.

```
Counterfactuals$new(
cfactuals,
predictor,
x_interest,
param_set,
desired,
method = NULL
)
```

`cfactuals`

(

`data.table`

)

The counterfactuals. Must have the same column names and types as`predictor$data$X`

.

`predictor`

(Predictor)

The object (created with `iml::Predictor$new()`

) holding the machine learning model and the data.

`x_interest`

(`data.table(1)`

| `data.frame(1)`

)

A single row with the observation of interest.

`param_set`

(ParamSet)

A ParamSet based on the features of `predictor$data$X`

.

`desired`

(`list(1)`

| `list(2)`

)

A `list`

with the desired properties of the counterfactuals. It should have one element `desired_outcome`

for
regression tasks (CounterfactualMethodRegr) and two elements `desired_class`

and `desired_prob`

for classification tasks (CounterfactualMethodClassif).

`method`

(`character`

)

Name of the method with which counterfactuals were generated. Default is
NULL which means that no name is provided.

`evaluate()`

Evaluates the counterfactuals. It returns the counterfactuals together with the evaluation `measures`

.

```
Counterfactuals$evaluate(
measures = c("dist_x_interest", "dist_target", "no_changed", "dist_train",
"minimality"),
show_diff = FALSE,
k = 1L,
weights = NULL
)
```

`measures`

(

`character`

)

The name of one or more evaluation measures. The following measures are available:`dist_x_interest`

: The distance of a counterfactual to`x_interest`

measured by Gower's dissimilarity measure (Gower 1971).`dist_target`

: The absolute distance of the prediction for a counterfactual to the interval`desired_outcome`

(regression tasks) or`desired_prob`

(classification tasks).`no_changed`

: The number of feature changes w.r.t.`x_interest`

.`dist_train`

: The (weighted) distance to the`k`

nearest training data points measured by Gower's dissimilarity measure (Gower 1971).`minimality`

: The number of changed features that each could be set to the value of`x_interest`

while keeping the desired prediction value.

`show_diff`

(`logical(1)`

)

Should the counterfactuals be displayed as their differences to `x_interest`

? Default is `FALSE`

.
If set to `TRUE`

, positive values for numeric features indicate an increase compared to the feature value in
`x_interest`

, negative values indicate a decrease. For factors, the feature value is displayed if it differs
from `x_interest`

; `NA`

means "no difference" in both cases.

`k`

(`integerish(1)`

)

How many nearest training points should be considered for computing the `dist_train`

measure? Default is `1L`

.

`weights`

(`numeric(k)`

| `NULL`

)

How should the `k`

nearest training points be weighted when computing the `dist_train`

measure? If `NULL`

(default) then all `k`

points are weighted equally. If a numeric vector of length `k`

is given, the i-th element
specifies the weight of the i-th closest data point.

`evaluate_set()`

Evaluates a set of counterfactuals. It returns the evaluation `measures`

.

```
Counterfactuals$evaluate_set(
measures = c("diversity", "no_nondom", "frac_nondom", "hypervolume"),
nadir = NULL
)
```

`measures`

(

`character`

)

The name of one or more evaluation measures. The following measures are available:`diversity`

: Diversity of returned counterfactuals in the feature space`no_nondom`

: Number of counterfactuals that are not dominated by other counterfactuals.`frac_nondom`

: Fraction of counterfactuals that are not dominated by other counterfactuals`hypervolume`

: Hypervolume of the induced Pareto front

`nadir`

(`numeric`

)

Max objective values to calculate dominated hypervolume.
Only considered, if `hypervolume`

is one of the `measures`

.
May be a scalar, in which case it is used for all four objectives,
or a vector of length 4.
Default is NULL, meaning the nadir point by Dandl et al. (2020) is used:
(min distance between prediction of `x_interest`

to `desired_prob/_outcome`

,
1, number of features, 1).

`subset_to_valid()`

Subset data to those meeting the desired prediction,
Process could be reverted using `revert_subset_to_valid()`

.

`Counterfactuals$subset_to_valid()`

`revert_subset_to_valid()`

Subset data to those meeting the desired prediction,
Process could be reverted using `revert_subset_to_valid()`

.

`Counterfactuals$revert_subset_to_valid()`

`plot_parallel()`

Plots a parallel plot that connects the (scaled) feature values of each counterfactual and highlights
`x_interest`

in blue.

```
Counterfactuals$plot_parallel(
feature_names = NULL,
row_ids = NULL,
digits_min_max = 2L
)
```

`feature_names`

(

`character`

|`NULL`

)

The names of the (numeric) features to display. If`NULL`

(default) all features are displayed.

`row_ids`

(`integerish`

| `NULL`

)

The row ids of the counterfactuals to display. If `NULL`

(default) all counterfactuals are displayed.

`digits_min_max`

Maximum number of digits for the minimum and maximum features values. Default is `2L`

.

`plot_freq_of_feature_changes()`

Plots a bar chart with the frequency of feature changes across all counterfactuals.

`Counterfactuals$plot_freq_of_feature_changes(subset_zero = FALSE)`

`subset_zero`

(

`logical(1)`

)

Should unchanged features be excluded from the plot? Default is`FALSE`

.

`get_freq_of_feature_changes()`

Returns the frequency of feature changes across all counterfactuals.

`Counterfactuals$get_freq_of_feature_changes(subset_zero = FALSE)`

`subset_zero`

(

`logical(1)`

)

Should unchanged features be excluded? Default is`FALSE`

.

A (named) `numeric`

vector with the frequency of feature changes.

`plot_surface()`

Creates a surface plot for two features. `x_interest`

is represented as a white dot and
all counterfactuals that differ from `x_interest`

**only** in the two selected features are represented as black dots.
The tick marks next to the axes show the marginal distribution of the observed data (`predictor$data$X`

).

The exact plot type depends on the selected feature types and number of features:

2 numeric features: surface plot

2 non-numeric features: heatmap

1 numeric or non-numeric feature: line graph

`Counterfactuals$plot_surface(feature_names, grid_size = 250L)`

`feature_names`

(

`character(2)`

)

The names of the features to plot.

`grid_size`

(`integerish(1)`

)

The grid size of the plot. It is ignored in case of two `non-numeric`

features. Default is `250L`

.

`clone()`

The objects of this class are cloneable with this method.

`Counterfactuals$clone(deep = FALSE)`

`deep`

Whether to make a deep clone.

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