Skip to contents

Plot variable importance scores for the predictors in a model.

Usage

vip(object, ...)

# S3 method for default
vip(
  object,
  num_features = 10L,
  geom = c("col", "point", "boxplot", "violin"),
  mapping = NULL,
  aesthetics = list(),
  horizontal = TRUE,
  all_permutations = FALSE,
  jitter = FALSE,
  include_type = FALSE,
  ...
)

# S3 method for model_fit
vip(object, ...)

# S3 method for workflow
vip(object, ...)

# S3 method for WrappedModel
vip(object, ...)

# S3 method for Learner
vip(object, ...)

Arguments

object

A fitted model (e.g., of class randomForest object) or a vi object.

...

Additional optional arguments to be passed on to vi.

num_features

Integer specifying the number of variable importance scores to plot. Default is 10.

geom

Character string specifying which type of plot to construct. The currently available options are described below.

  • geom = "col" uses geom_col to construct a bar chart of the variable importance scores.

  • geom = "point" uses geom_point to construct a Cleveland dot plot of the variable importance scores.

  • geom = "boxplot" uses geom_boxplot to construct a boxplot plot of the variable importance scores. This option can only for the permutation-based importance method with nsim > 1 and keep = TRUE; see vi_permute for details.

  • geom = "violin" uses geom_violin to construct a violin plot of the variable importance scores. This option can only for the permutation-based importance method with nsim > 1 and keep = TRUE; see vi_permute for details.

mapping

Set of aesthetic mappings created by aes-related functions and/or tidy eval helpers. See example usage below.

aesthetics

List specifying additional arguments passed on to layer. These are often aesthetics, used to set an aesthetic to a fixed value, likecolour = "red" or size = 3. See example usage below.

horizontal

Logical indicating whether or not to plot the importance scores on the x-axis (TRUE). Default is TRUE.

all_permutations

Logical indicating whether or not to plot all permutation scores along with the average. Default is FALSE. (Only used for permutation scores when nsim > 1.)

jitter

Logical indicating whether or not to jitter the raw permutation scores. Default is FALSE. (Only used when all_permutations = TRUE.)

include_type

Logical indicating whether or not to include the type of variable importance computed in the axis label. Default is FALSE.

Examples

#
# A projection pursuit regression example using permutation-based importance
#

# Load the sample data
data(mtcars)

# Fit a projection pursuit regression model
model <- ppr(mpg ~ ., data = mtcars, nterms = 1)

# Construct variable importance plot (permutation importance, in this case)
set.seed(825)  # for reproducibility
pfun <- function(object, newdata) predict(object, newdata = newdata)
vip(model, method = "permute", train = mtcars, target = "mpg", nsim = 10,
    metric = "rmse", pred_wrapper = pfun)


# Better yet, store the variable importance scores and then plot
set.seed(825)  # for reproducibility
vis <- vi(model, method = "permute", train = mtcars, target = "mpg",
          nsim = 10, metric = "rmse", pred_wrapper = pfun)
vip(vis, geom = "point", horiz = FALSE)

vip(vis, geom = "point", horiz = FALSE, aesthetics = list(size = 3))


# Plot unaggregated permutation scores (boxplot colored by feature)
library(ggplot2)  # for `aes()`-related functions and tidy eval helpers
vip(vis, geom = "boxplot", all_permutations = TRUE, jitter = TRUE,
    #mapping = aes_string(fill = "Variable"),   # for ggplot2 (< 3.0.0)
    mapping = aes(fill = .data[["Variable"]]),  # for ggplot2 (>= 3.0.0)
    aesthetics = list(color = "grey35", size = 0.8))


#
# A binary classification example
#
if (FALSE) {
library(rpart)  # for classification and regression trees

# Load Wisconsin breast cancer data; see ?mlbench::BreastCancer for details
data(BreastCancer, package = "mlbench")
bc <- subset(BreastCancer, select = -Id)  # for brevity

# Fit a standard classification tree
set.seed(1032)  # for reproducibility
tree <- rpart(Class ~ ., data = bc, cp = 0)

# Prune using 1-SE rule (e.g., use `plotcp(tree)` for guidance)
cp <- tree$cptable
cp <- cp[cp[, "nsplit"] == 2L, "CP"]
tree2 <- prune(tree, cp = cp)  # tree with three splits

# Default tree-based VIP
vip(tree2)

# Computing permutation importance requires a prediction wrapper. For
# classification, the return value depends on the chosen metric; see
# `?vip::vi_permute` for details.
pfun <- function(object, newdata) {
  # Need vector of predicted class probabilities when using  log-loss metric
  predict(object, newdata = newdata, type = "prob")[, "malignant"]
}

# Permutation-based importance (note that only the predictors that show up
# in the final tree have non-zero importance)
set.seed(1046)  # for reproducibility
vip(tree2, method = "permute", nsim = 10, target = "Class",
    metric = "logloss", pred_wrapper = pfun, reference_class = "malignant")
}