vip: vi – R documentation

Pricing

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

Get Started for Free

Documentation

vip

vi

Variable importance

Description

Compute variable importance scores for the predictors in a model.

Usage

vi(object, ...)

## Default S3 method:
vi(
  object,
  method = c("model", "firm", "permute", "shap"),
  feature_names = NULL,
  FUN = NULL,
  var_fun = NULL,
  ice = FALSE,
  abbreviate_feature_names = NULL,
  sort = TRUE,
  decreasing = TRUE,
  scale = FALSE,
  rank = FALSE,
  ...
)

## S3 method for class 'model_fit'
vi(object, ...)

## S3 method for class 'WrappedModel'
vi(object, ...)

## S3 method for class 'Learner'
vi(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_model`, `vi_firm`, `vi_permute`, or `vi_shap`.
`method`	Character string specifying the type of variable importance (VI) to compute. Current options are `"model"` (the default), for model-specific VI scores (see `vi_model` for details), `"firm"`, for variance-based VI scores (see `vi_firm` for details), `"permute"`, for permutation-based VI scores (see ' `vi_permute` for details), or `"shap"`, for Shapley-based VI scores. For more details on the variance-based methods, see Greenwell et al. (2018) and Scholbeck et al. (2019).
`feature_names`	Character string giving the names of the predictor variables (i.e., features) of interest.
`FUN`	Deprecated. Use `var_fun` instead.
`var_fun`	List with two components, `"cat"` and `"con"`, containing the functions to use to quantify the variability of the feature effects (e.g., partial dependence values) for categorical and continuous features, respectively. If `NULL`, the standard deviation is used for continuous features. For categorical features, the range statistic is used (i.e., (max - min) / 4). Only applies when `method = "firm"`.
`ice`	Logical indicating whether or not to estimate feature effects using individual conditional expectation (ICE) curves. Only applies when `method = "firm"`. Default is `FALSE`. Setting `ice = TRUE` is preferred whenever strong interaction effects are potentially present.
`abbreviate_feature_names`	Integer specifying the length at which to abbreviate feature names. Default is `NULL` which results in no abbreviation (i.e., the full name of each feature will be printed).
`sort`	Logical indicating whether or not to order the sort the variable importance scores. Default is `TRUE`.
`decreasing`	Logical indicating whether or not the variable importance scores should be sorted in descending (`TRUE`) or ascending (`FALSE`) order of importance. Default is `TRUE`.
`scale`	Logical indicating whether or not to scale the variable importance scores so that the largest is 100. Default is `FALSE`.
`rank`	Logical indicating whether or not to rank the variable importance scores (i.e., convert to integer ranks). Default is `FALSE`. Potentially useful when comparing variable importance scores across different models using different methods.

Value

A tidy data frame (i.e., a "tibble" object) with at least two columns: Variable and Importance. For "lm"/"glm"-like objects, an additional column, called Sign, is also included which includes the sign (i.e., POS/NEG) of the original coefficient. If method = "permute" and nsim > 1, then an additional column, StDev, giving the standard deviation of the permutation-based variable importance scores is included.

References

Greenwell, B. M., Boehmke, B. C., and McCarthy, A. J. A Simple and Effective Model-Based Variable Importance Measure. arXiv preprint arXiv:1805.04755 (2018).

Examples

#
# A projection pursuit regression example
#

# Load the sample data
data(mtcars)

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

# Compute variable importance scores
vi(mtcars.ppr, method = "firm", ice = TRUE)
vi(mtcars.ppr, method = "firm", ice = TRUE,
   var_fun = list("con" = mad, "cat" = function(x) diff(range(x)) / 4))

# Plot variable importance scores
vip(mtcars.ppr, method = "firm", ice = TRUE)

vip

Variable Importance Plots

v0.3.2

GPL (>= 2)

Authors

Brandon Greenwell [aut, cre] (<https://orcid.org/0000-0002-8120-0084>), Brad Boehmke [aut] (<https://orcid.org/0000-0002-3611-8516>), Bernie Gray [aut] (<https://orcid.org/0000-0001-9190-6032>)

Initial release

vi