vip R Package

The vip package quantifies and visualizes which features drive a fitted model's predictions. It provides two primary interfaces:

1. vi(): Returns a tidy data frame (class "vi") containing importance scores. This is useful for post-processing or custom plotting.
2. vip(): Generates a variable importance plot using base R graphics via the tinyplot package.

Importance Methods

• method = "model": Uses native importance measures provided by the model class (e.g., impurity in ranger).
• method = "permute": Model-agnostic permutation importance. Requires a user-supplied pred_wrapper.
• method = "shap": Shapley-based importance.
• method = "firm": Variance-based importance.

Model Compatibility

vi() and vip() work out-of-the-box with many model classes including randomForest, ranger, gbm, xgboost, lightgbm, glmnet, caret, tidymodels, and mlr3. For any other model, you can use model-agnostic methods by providing a prediction wrapper function.

library(vip)

# Example: Model-specific importance
rfo <- ranger(y ~ ., data = trn, importance = "impurity")
vi(rfo)    # Returns data frame of scores
vip(rfo)   # Returns variable importance plot

Version 0.5.0 is a breaking release. If you are upgrading from 0.4.x, note the following changes:

1. Graphics Engine: Plots have moved from ggplot2 to base R graphics via tinyplot. vip(fit) + theme_bw() will no longer work. Use plot(vi(fit), ...) with graphical parameters instead.
2. Return Type: vi() now returns a plain data frame (class "vi") instead of a tibble. If you require a tibble, use tibble::as_tibble(vi(fit)).
3. Argument Changes:
   • aesthetics is deprecated; use plot_args in vip() instead.
   • The mapping argument (ggplot2-style) is ignored with a warning.
   • geom = "col" remains a valid alias for geom = "bar".
4. Package Maintainers: If your package depends on vip, move it to Suggests, use requireNamespace("vip", quietly = TRUE), and add Additional_repositories: https://bgreenwell.r-universe.dev to your DESCRIPTION file.

Variable importance results (objects of class "vi") can be visualized using the plot() method. This method uses tinyplot (base R graphics) rather than ggplot2.

Note for users migrating from v0.4.x:

• vip() and plot() return the "vi" object invisibly. You can no longer use ggplot2 syntax like + theme_bw().
• Instead, pass graphical parameters directly to plot().
• Arguments passed to plot() are passed on to tinyplot::tinyplot().

Common arguments for plot():

• type: e.g., "point", "boxplot".
• col: Color for elements.
• jitter: Boolean to add jitter to points.
• all_permutations: Boolean to show all permutations in boxplots.

library(vip)

# Plotting a 'vi' object with boxplots
plot(vis, type = "boxplot", all_permutations = TRUE, jitter = TRUE, fill = "grey90")

# Plotting with specific graphical parameters
plot(vi(rfo), type = "point", col = "red")