vivi_importance: vivi_importance

In vivid: Variable Importance and Variable Interaction Displays

vivi_importance

Description

Compute variable importance only, without interactions.

Usage

vivi_importance(
  data,
  fit,
  response,
  importanceType = "agnostic",
  class = 1,
  predictFun = NULL,
  numPerm = 4,
  showVimpError = FALSE,
  vars = NULL,
  as_matrix = FALSE,
  reorder = FALSE
)

Arguments

data	Data frame used for fit.
fit	A supervised ML model understood by condvis2::CVpredict (or supply predictFun).
response	Name of the response column in data.
importanceType	Importance metric to use. Defaults to "agnostic" (permutation via flashlight). If an embedded metric exists, set this to that metric name to extract it instead.
class	Classification level (factor level or 1-based index) when response is a factor.
predictFun	Optional prediction function of signature ⁠(fit, data, prob = TRUE/FALSE)⁠. If NULL, an internal CVpredict-based function is used.
numPerm	Number of permutations for agnostic importance. Default 4.
showVimpError	If TRUE and numPerm > 1, print standard errors.
vars	Optional character vector of feature names to restrict the calculation.
as_matrix	If TRUE, return a square matrix with importances on the diagonal and zeros elsewhere; otherwise return a named numeric vector. Default FALSE.
reorder	If as_matrix = TRUE, optionally reorder the matrix with vividReorder(). Default FALSE.

Value

Named numeric vector of importances, or a square matrix if as_matrix = TRUE.

Examples

# Example 1 — importance as a named vector
aq <- na.omit(airquality)
fit_lm <- lm(Ozone ~ ., data = aq)
imp_vec <- vivi_importance(data = aq, fit = fit_lm, response = "Ozone")
head(imp_vec)

# Example 2 — importance as a diagonal matrix for plotting
imp_mat <- vivi_importance(data = aq, fit = fit_lm, response = "Ozone",
                           as_matrix = TRUE)
# viviHeatmap(imp_mat)  # if you want to visualise the diagonal

# Example 3 — embedded importance from a random forest (if available)

if (requireNamespace("randomForest", quietly = TRUE)) {
  library(randomForest)
  rf <- randomForest(Ozone ~ ., data = aq, importance = TRUE)
  vivi_importance(data = aq, fit = rf, response = "Ozone",
                  importanceType = "%IncMSE")
}


# Example 4 — classification model with ranger using embedded impurity importance

if (requireNamespace("ranger", quietly = TRUE)) {
  library(ranger)
  fit_rf <- ranger(Species ~ ., data = iris,
                   importance = "impurity", probability = TRUE)
  vivi_importance(data = iris, fit = fit_rf, response = "Species",
                  importanceType = "impurity")
}

vivid documentation built on Aug. 24, 2025, 1:09 a.m.