iBreakDown (version 2.1.2)

describe: Generates Textual Explanations for Predictive Models

Description

Generic function describe generates natural language explanations based on break_down and shap explanations, what enhances their interpretability.

Usage

describe(x, nonsignificance_treshold = 0.15, ...)
# S3 method for break_down
describe(
  x,
  nonsignificance_treshold = 0.15,
  ...,
  label = NULL,
  short_description = FALSE,
  display_values = FALSE,
  display_numbers = FALSE,
  display_distribution_details = FALSE,
  display_shap = FALSE
)
# S3 method for break_down_uncertainty
describe(
  x,
  nonsignificance_treshold = 0.15,
  ...,
  label = NULL,
  short_description = FALSE,
  display_values = FALSE,
  display_numbers = FALSE,
  display_distribution_details = FALSE,
  display_shap = FALSE
)

Value

A character string of textual explanation

Arguments

x

an explanation created with break_down or shap

nonsignificance_treshold

a numeric specifying a threshold for variable importance

...

other arguments

label

a character string describing model's prediction

short_description

a boolean, returns a short description

display_values

a boolean, displays variables' values

display_numbers

a boolean, displays a description containing numerical values

display_distribution_details

a boolean, displays details about the distribution of model's predictions

display_shap

a boolean, adds information about variables' average contribution. Use only with shap explanation.

Details

Function describe generates a textual explanations by extracting information from a break_down or shap explanation. It makes an argument justifying why the model's prediction is lower or higher, than it's average prediction. The description consists of an introduction, argumenation and summary making use from the claim, support, evidence argumentation structure, as recomended for the World Universities Debating style.

The function first selects one of four different scenarios, due to nonsignificance_treshold. The chosen scenario can be one of the following: 1. Model's prediction for the selected instance is significantly higher than the average prediction. 2. Model's prediction is significantly lower. 3. Model's prediction is close to it's average prediction, however there are significant variables counteracting with each other 4. Model's prediction is close to it's average prediction and all the variables are rather nonsignificant. Then an explanation due to the chosen scenario is generated.

Examples

library("DALEX")
library("randomForest")
library("iBreakDown")

titanic <- na.omit(titanic)
model_titanic_rf <- randomForest(survived == "yes" ~ gender + age + class + embarked +
                                  fare + sibsp + parch,  data = titanic)

explain_titanic_rf <- explain(model_titanic_rf,
                              data = titanic[ ,-9],
                              y = titanic$survived == "yes",
                              label = "Random Forest v7")

bd_explanation <- break_down(explain_titanic_rf, titanic[1, ], keep_distributions = TRUE)
plot(bd_explanation)

description <- describe(bd_explanation,
                        label = "the passanger will survive with probability",
                        short_description = FALSE,
                        display_values =  TRUE,
                        display_numbers = TRUE,
                        display_distribution_details = FALSE)

description

library("DALEX")
library("iBreakDown")
titanic <- na.omit(titanic)
model_titanic_glm <- glm(titanic$survived == "yes" ~ age + gender + class + fare + sibsp,
                         data = titanic[ ,-9], family = "binomial")
explain_titanic_glm <- explain(model_titanic_glm,
                              data = titanic[,-9],
                              y = titanic$survived == "yes",
                              label = "glm")
passanger <- titanic[1, -9]
shap_glm <- shap(explain_titanic_glm, passanger)
plot(shap_glm)

describe(shap_glm,
         label = "the selected passanger survives with probability",
         display_shap = TRUE,
         display_numbers = TRUE)