vip (version 0.2.2)

vip: Variable importance plots

Description

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,
  ...,
  bar = NULL,
  width = NULL,
  alpha = NULL,
  color = NULL,
  fill = NULL,
  size = NULL,
  shape = NULL
)
# S3 method for model_fit
vip(object, ...)

Arguments

object

A fitted model object (e.g., a "randomForest" object) or an object that inherits from class "vi".

...

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 or aes_. 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, like colour = "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.

bar

Logical indicating whether or not to produce a barplot. Default is NULL. WARNING: This argument has been deprecated in favor of the new mapping and aesthetics arguments. It will be removed in version 0.3.0.

width

Numeric value specifying the width of the bars when bar = TRUE. Default is NULL. WARNING: This argument has been deprecated in favor of the new mapping and aesthetics arguments. It will be removed in version 0.3.0.

alpha

Numeric value between 0 and 1 giving the transparency of the bars (bar = TRUE) or points (bar = FALSE). WARNING: This argument has been deprecated in favor of the new mapping and aesthetics arguments. It will be removed in version 0.3.0.

color

Character string specifying the color to use for the borders of the bars. Could also be a function, such as heat.colors. Default is NULL. WARNING: This argument has been deprecated in favor of the new mapping and aesthetics arguments. It will be removed in version 0.3.0.

fill

Character string specifying the color to use to fill the bars. Could also be a function, such as heat.colors. Default is NULL. WARNING: This argument has been deprecated in favor of the new mapping and aesthetics arguments. It will be removed in version 0.3.0.

size

Numeric value indicating the size to use for the points whenever bar = FALSE. Default is NULL. WARNING: This argument has been deprecated in favor of the new mapping and aesthetics arguments. It will be removed in version 0.3.0.

shape

Numeric value indicating the shape to use for the points whenever bar = FALSE. Default is NULL. WARNING: This argument has been deprecated in favor of the new mapping and aesthetics arguments. It will be removed in version 0.3.0.

Examples

# NOT RUN {
#
# A projection pursuit regression example
#

# Load the sample data
data(mtcars)

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

# Construct variable importance plot
vip(model, method = "firm")

# Better yet, store the variable importance scores and then plot
vi_scores <- vi(model, method = "firm")
vip(vi_scores, geom = "point", horiz = FALSE)
vip(vi_scores, geom = "point", horiz = FALSE, aesthetics = list(size = 3))

# The `%T>\%` operator is imported for convenience; see ?magrittr::`%T>%`
# for details
vi_scores <- model %>%
  vi(method = "firm") %T>%
  {print(vip(.))}
vi_scores

# Permutation scores (barplot w/ raw values and jittering)
pfun <- function(object, newdata) predict(object, newdata = newdata)
vip(model, method = "permute", train = mtcars, target = "mpg", nsim = 10,
    metric = "rmse", pred_wrapper = pfun,
    aesthetics = list(color = "grey50", fill = "grey50"),
    all_permutations = TRUE, jitter = TRUE)

# Permutation scores (boxplot)
vip(model, method = "permute", train = mtcars, target = "mpg", nsim = 10,
    metric = "rmse", pred_wrapper = pfun, geom = "boxplot")

# Permutation scores (boxplot colored by feature)
library(ggplot2)  # for `aes_string()` function
vip(model, method = "permute", train = mtcars, target = "mpg", nsim = 10,
    metric = "rmse", pred_wrapper = pfun, geom = "boxplot",
    all_permutations = TRUE, mapping = aes_string(fill = "Variable"),
    aesthetics = list(color = "grey35", size = 0.8))
# }