Movatterモバイル変換

shapviz: SHAP Visualizations

Description

Visualizations for SHAP (SHapley Additive exPlanations), such as waterfall plots, force plots, various types of importance plots, dependence plots, and interaction plots. These plots act on a 'shapviz' object created from a matrix of SHAP values and a corresponding feature dataset. Wrappers for the R packages 'xgboost', 'lightgbm', 'fastshap', 'shapr', 'h2o', 'treeshap', 'DALEX', and 'kernelshap' are added for convenience. By separating visualization and computation, it is possible to display factor variables in graphs, even if the SHAP values are calculated by a model that requires numerical features. The plots are inspired by those provided by the 'shap' package in Python, but there is no dependency on it.

Author(s)

Maintainer: Michael Mayermayermichael79@gmail.com

Other contributors:

• Adrian Standoadrian.j.stando@gmail.com [contributor]

See Also

Useful links:

• https://github.com/ModelOriented/shapviz

• https://modeloriented.github.io/shapviz/

• Report bugs athttps://github.com/ModelOriented/shapviz/issues

Rowbinds two "shapviz" Objects

Description

Rowbinds two "shapviz" objects using+.

Usage

## S3 method for class 'shapviz'e1 + e2## S3 method for class 'mshapviz'e1 + e2

Arguments

Value

A new object of class "shapviz".

See Also

shapviz(),rbind.shapviz()

Examples

S <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))s1 <- shapviz(S, X, baseline = 4)[1]s2 <- shapviz(S, X, baseline = 4)[2]s <- s1 + s2s# mshapvizS <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))s1 <- shapviz(S, X, baseline = 4)[1L]s2 <- shapviz(S, X, baseline = 4)[2L]s <- mshapviz(c(shp1 = s1, shp2 = s2))s + s

Subsets "shapviz" Object

Description

Use standard square bracket subsetting to select rows and/or columns ofSHAP values, feature values, and SHAP interaction values of a "shapviz" object.

Usage

## S3 method for class 'shapviz'x[i, j, ...]

Arguments

Value

A new object of class "shapviz".

See Also

shapviz()

Examples

S <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))x <- shapviz(S, X, baseline = 4)x[1, "x"]x[1]x[c(FALSE, TRUE), ]x[, "x"]

Concatenates "shapviz" Objects

Description

This function combines two or more (usually named) "shapviz" objectsto an object of class "mshapviz".

Usage

## S3 method for class 'shapviz'c(...)

Arguments

Value

A "mshapviz" object.

See Also

mshapviz()

Examples

S <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))s1 <- shapviz(S, X, baseline = 4)[1]s2 <- shapviz(S, X, baseline = 4)[2]s <- c(shp1 = s1, shp2 = s2)s

Collapse SHAP values

Description

This function sums up SHAP values (or SHAP interaction values) of feature groups.Typical application: SHAP values have been generated by a model with one or multipleone-hot encoded variables, but the explanations should be done using theoriginal factor.

Usage

collapse_shap(S, collapse = NULL, ...)

Arguments

Value

A matrix of SHAP values, or an array of SHAP interaction values.

Examples

S <- cbind(  x = c(0.1, 0.1, 0.1),  `age low` = c(0.2, -0.1, 0.1),  `age mid` = c(0, 0.2, -0.2),  `age high` = c(1, -1, 0))collapse <- list(age = c("age low", "age mid", "age high"))collapse_shap(S, collapse)# Arrays (as with SHAP interactions)S_inter <- array(1, dim = c(2, 4, 4), dimnames = list(NULL, letters[1:4], letters[1:4]))collapse_shap(S_inter, collapse = list(cd = c("c", "d"), ab = c("a", "b")))

Dimensions of "shapviz" Object

Description

Dimensions of "shapviz" Object

Usage

## S3 method for class 'shapviz'dim(x)

Arguments

Value

A numeric vector of length two providing the number of rows and columnsof the SHAP matrix stored inx.

See Also

shapviz()

Examples

S <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))x <- shapviz(S, X)dim(x)nrow(x)ncol(x)

Dimnames (Replacement Method) of "shapviz" Object

Description

This impliescolnames(x) <- ....

Usage

## S3 replacement method for class 'shapviz'dimnames(x) <- value

Arguments

Value

Likex, but with replaced dimnames.

See Also

shapviz()

Examples

S <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))x <- shapviz(S, X, baseline = 4)dimnames(x) <- list(1:2, c("a", "b"))dimnames(x)colnames(x) <- c("x", "y")colnames(x)

Dimnames of "shapviz" Object

Description

This implies to usecolnames(x) to get the column names of the SHAP and featurematrix (and optional SHAP interaction values).

Usage

## S3 method for class 'shapviz'dimnames(x)

Arguments

Value

Dimnames of the SHAP matrix.

See Also

shapviz()

Examples

S <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))x <- shapviz(S, X, baseline = 4)dimnames(x)colnames(x)

Extractor Functions

Description

Functions to extract SHAP values, feature values, the baseline,or SHAP interactions from a "(m)shapviz" object.

Usage

get_shap_values(object, ...)## S3 method for class 'shapviz'get_shap_values(object, ...)## S3 method for class 'mshapviz'get_shap_values(object, ...)## Default S3 method:get_shap_values(object, ...)get_feature_values(object, ...)## S3 method for class 'shapviz'get_feature_values(object, ...)## S3 method for class 'mshapviz'get_feature_values(object, ...)## Default S3 method:get_feature_values(object, ...)get_baseline(object, ...)## S3 method for class 'shapviz'get_baseline(object, ...)## S3 method for class 'mshapviz'get_baseline(object, ...)## Default S3 method:get_baseline(object, ...)get_shap_interactions(object, ...)## S3 method for class 'shapviz'get_shap_interactions(object, ...)## S3 method for class 'mshapviz'get_shap_interactions(object, ...)## Default S3 method:get_shap_interactions(object, ...)

Arguments

Value

• get_shap_values() returns the matrix of SHAP values,

• get_feature_values() thedata.frame of feature values,

• get_baseline() the numeric baseline value, and

• get_shap_interactions() the SHAP interactions of the input.

For objects of class "mshapviz", these functions return lists of those elements.

Examples

S <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))shp <- shapviz(S, X, baseline = 4)get_shap_values(shp)

Number Formatter

Description

Formats a numeric vector in a way that its largest absolute value determinesthe number of digits after the decimal separator. This function is helpful inperfectly aligning numbers on plots. Does not use scientific formatting.

Usage

format_max(x, digits = 4L, ...)

Arguments

Value

A character vector of formatted numbers.

Examples

x <- c(100, 1, 0.1)format_max(x)y <- c(100, 1.01)format_max(y)format_max(y, digits = 5)

Check for mshapviz

Description

Is object of class "mshapviz"?

Usage

is.mshapviz(object)

Arguments

Value

ReturnsTRUE ifobject has "mshapviz" among its classes,andFALSE otherwise.

See Also

mshapviz()

Examples

S <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))s1 <- shapviz(S, X, baseline = 4)[1]s2 <- shapviz(S, X, baseline = 4)x <- c(s1 = s1, s2 = s2)is.mshapviz(x)is.mshapviz(s1)

Check for shapviz

Description

Is object of class "shapviz"?

Usage

is.shapviz(object)

Arguments

Value

ReturnsTRUE ifobject has "shapviz" among its classes,andFALSE otherwise.

See Also

shapviz()

Examples

S <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))shp <- shapviz(S, X)is.shapviz(shp)is.shapviz("a")

Miami-Dade County House Prices

Description

The dataset contains information on 13,932 single-family homes sold inMiami-Dade County in 2016.Besides publicly available information, the dataset creator Steven C. Bourassa hasadded distance variables, aviation noise as well as latitude and longitude.

More information can be found open-access onhttps://www.mdpi.com/1595920.

The dataset can also be downloaded viamiami <- OpenML::getOMLDataSet(43093)$data.

Usage

miami

Format

A data frame with 13,932 rows and 17 columns:

PARCELNO

unique identifier for each property. About 1% appear multiple times.

SALE_PRC

sale price ($)

LND_SQFOOT

land area (square feet)

TOT_LVG_AREA

floor area (square feet)

SPEC_FEAT_VAL

value of special features (e.g., swimming pools) ($)

RAIL_DIST

distance to the nearest rail line (an indicator of noise) (feet)

OCEAN_DIST

distance to the ocean (feet)

WATER_DIST

distance to the nearest body of water (feet)

CNTR_DIST

distance to the Miami central business district (feet)

SUBCNTR_DI

distance to the nearest subcenter (feet)

HWY_DIST

distance to the nearest highway (an indicator of noise) (feet)

age

age of the structure

avno60plus

dummy variable for airplane noise exceeding an acceptable level

structure_quality

quality of the structure

month_sold

sale month in 2016 (1 = jan)

LATITUDE, LONGITUDE

Coordinates

Combines compatible "shapviz" Objects

Description

This function combines a list of compatible "shapviz" objects to an object of class"mshapviz". The elements can be named.

Usage

mshapviz(object, ...)

Arguments

Value

A "mshapviz" object.

Examples

S <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))s1 <- shapviz(S, X, baseline = 4)[1L]s2 <- shapviz(S, X, baseline = 4)[2L]s <- mshapviz(c(shp1 = s1, shp2 = s2))s

Interaction Strength

Description

Returns a vector of interaction strengths between variablev and all othervariables, see Details.

Usage

potential_interactions(  obj,  v,  nbins = NULL,  color_num = TRUE,  scale = FALSE,  adjusted = FALSE)

Arguments

Details

If SHAP interaction values are available, the interaction strengthbetween featurev and another feature⁠v'⁠ is measured by twice theirmean absolute SHAP interaction values.

Otherwise, we use a heuristic calculated as follows:

1. Ifv is numeric, it is binned intonbins bins.

2. Per bin, the SHAP values ofv are regressed ontov, and the R-squaredis calculated. Rows with missing⁠v'⁠ are discarded.

3. The R-squared are averaged over bins, weighted by the number ofnon-missing⁠v'⁠ values.

This measures how much variability in the SHAP values ofv is explained by⁠v'⁠,after accounting forv.

Setscale = TRUE to multiply the R-squared by the within-bin varianceof the SHAP values. This will put higher weight to bins with larger scatter.

Setcolor_num = FALSE tonot turn the values of the "color" feature⁠v'⁠to numeric.

Finally, setadjusted = TRUE to useadjusted R-squared.

The algorithm does not consider observations with missing⁠v'⁠ values.

Value

A named vector of decreasing interaction strengths.

See Also

sv_dependence()

Prints "mshapviz" Object

Description

Prints "mshapviz" Object

Usage

## S3 method for class 'mshapviz'print(x, ...)

Arguments

Value

Invisibly, the input is returned.

See Also

mshapviz()

Examples

S <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))s1 <- shapviz(S, X, baseline = 4)[1]s2 <- shapviz(S, X, baseline = 4)x <- c(s1 = s1, s2 = s2)x

Prints "shapviz" Object

Description

Prints "shapviz" Object

Usage

## S3 method for class 'shapviz'print(x, ...)

Arguments

Value

Invisibly, the input is returned.

See Also

shapviz()

Examples

S <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))x <- shapviz(S, X, baseline = 4)x

Rowbinds Multiple "shapviz" or "mshapviz" Objects

Description

Rowbinds multiple "shapviz" objects based on the+ operator.

Usage

## S3 method for class 'shapviz'rbind(...)## S3 method for class 'mshapviz'rbind(...)

Arguments

Value

A new object of class "shapviz" or "mshapviz".

See Also

shapviz(),mshapviz()

Examples

S <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))s1 <- shapviz(S, X, baseline = 4)[1]s2 <- shapviz(S, X, baseline = 4)[2]s <- rbind(s1, s2)s# mshapvizS <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))s1 <- shapviz(S, X, baseline = 4)[1L]s2 <- shapviz(S, X, baseline = 4)[2L]s <- mshapviz(c(shp1 = s1, shp2 = s2))rbind(s, s)

Initialize "shapviz" Object

Description

This function creates an object of class "shapviz" from a matrix of SHAP values, orfrom a fitted model of type

• XGBoost,

• LightGBM, or

• H2O.

Furthermore,shapviz() can digest the results of

• fastshap::explain(),

• shapr::explain(),

• treeshap::treeshap(),

• DALEX::predict_parts(),

• kernelshap::kernelshap(),

• kernelshap::permshap(), and

• kernelshap::additive_shap(),

check the vignettes for examples.

Usage

shapviz(object, ...)## Default S3 method:shapviz(object, ...)## S3 method for class 'matrix'shapviz(object, X, baseline = 0, collapse = NULL, S_inter = NULL, ...)## S3 method for class 'xgb.Booster'shapviz(  object,  X_pred,  X = X_pred,  which_class = NULL,  collapse = NULL,  interactions = FALSE,  ...)## S3 method for class 'lgb.Booster'shapviz(object, X_pred, X = X_pred, which_class = NULL, collapse = NULL, ...)## S3 method for class 'explain'shapviz(object, X = NULL, baseline = NULL, collapse = NULL, ...)## S3 method for class 'treeshap'shapviz(  object,  X = object[["observations"]],  baseline = 0,  collapse = NULL,  ...)## S3 method for class 'predict_parts'shapviz(object, ...)## S3 method for class 'shapr'shapviz(  object,  X = as.data.frame(object$internal$data$x_explain),  collapse = NULL,  ...)## S3 method for class 'kernelshap'shapviz(object, X = object[["X"]], which_class = NULL, collapse = NULL, ...)## S3 method for class 'H2OModel'shapviz(  object,  X_pred,  X = as.data.frame(X_pred),  collapse = NULL,  background_frame = NULL,  output_space = FALSE,  output_per_reference = FALSE,  ...)

Arguments

Details

Together with the main input, a data setX of feature values is required,used only for visualization. It can therefore contain character or factorvariables, even if the SHAP values were calculated from a purely numerical featurematrix. In addition, to improve visualization, it can sometimes be useful to truncategross outliers, logarithmize certain columns, or replace missing values with anexplicit value.

SHAP values of dummy variables can be combined using the convenientcollapse argument.Multi-output models created from XGBoost, LightGBM, "kernelshap", or "permshap"return a "mshapviz" object, containing a "shapviz" object per output.

Value

An object of class "shapviz" with the following elements:

• S: Numeric matrix of SHAP values.

• X:data.frame containing the feature values corresponding toS.

• baseline: Baseline value, representing the average prediction at thescale of the SHAP values.

• S_inter: Numeric array of SHAP interaction values (orNULL).

Methods (by class)

• shapviz(default): Default method to initialize a "shapviz" object.

• shapviz(matrix): Creates a "shapviz" object from a matrix of SHAP values.

• shapviz(xgb.Booster): Creates a "shapviz" object from an XGBoost model.

• shapviz(lgb.Booster): Creates a "shapviz" object from a LightGBM model.

• shapviz(explain): Creates a "shapviz" object fromfastshap::explain().

• shapviz(treeshap): Creates a "shapviz" object fromtreeshap::treeshap().

• shapviz(predict_parts): Creates a "shapviz" object fromDALEX::predict_parts().

• shapviz(shapr): Creates a "shapviz" object fromshapr::explain().

• shapviz(kernelshap): Creates a "shapviz" object from an object of class 'kernelshap'. This includesresults ofkernelshap(),permshap(), andadditive_shap().

• shapviz(H2OModel): Creates a "shapviz" object from an H2O model.

See Also

sv_importance(),sv_dependence(),sv_dependence2D(),sv_interaction(),sv_waterfall(),sv_force(),collapse_shap()

Examples

S <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))shapviz(S, X, baseline = 4)# XGBoost modelsX_pred <- data.matrix(iris[, -1])dtrain <- xgboost::xgb.DMatrix(X_pred, label = iris[, 1], nthread = 1)fit <- xgboost::xgb.train(list(nthread = 1), data = dtrain, nrounds = 10)# Will use numeric matrix "X_pred" as feature matrixx <- shapviz(fit, X_pred = X_pred)xsv_dependence(x, "Species")# Will use original values as feature matrixx <- shapviz(fit, X_pred = X_pred, X = iris)sv_dependence(x, "Species")# "X_pred" can also be passed as xgb.DMatrix, but only if X is passed as well!x <- shapviz(fit, X_pred = dtrain, X = iris)# Multiclass settingparams <- list(objective = "multi:softprob", num_class = 3, nthread = 1)X_pred <- data.matrix(iris[, -5])dtrain <- xgboost::xgb.DMatrix(  X_pred, label = as.integer(iris[, 5]) - 1, nthread = 1)fit <- xgboost::xgb.train(params = params, data = dtrain, nrounds = 10)# Select specific classx <- shapviz(fit, X_pred = X_pred, which_class = 3)x# Or combine all classes to "mshapviz" objectx <- shapviz(fit, X_pred = X_pred)x# What if we would have one-hot-encoded values and want to explain the original column?X_pred <- stats::model.matrix(~ . -1, iris[, -1])dtrain <- xgboost::xgb.DMatrix(X_pred, label = as.integer(iris[, 1]), nthread = 1)fit <- xgboost::xgb.train(list(nthread = 1), data = dtrain, nrounds = 10)x <- shapviz(  fit,  X_pred = X_pred,  X = iris,  collapse = list(Species = c("Speciessetosa", "Speciesversicolor", "Speciesvirginica")))summary(x)# Similarly with LightGBMif (requireNamespace("lightgbm", quietly = TRUE)) {  fit <- lightgbm::lgb.train(    params = list(objective = "regression", num_thread = 1),    data = lightgbm::lgb.Dataset(X_pred, label = iris[, 1]),    nrounds = 10,    verbose = -2  )  x <- shapviz(fit, X_pred = X_pred)  x  # Multiclass  params <- list(objective = "multiclass", num_class = 3, num_thread = 1)  X_pred <- data.matrix(iris[, -5])  dtrain <- lightgbm::lgb.Dataset(X_pred, label = as.integer(iris[, 5]) - 1)  fit <- lightgbm::lgb.train(params = params, data = dtrain, nrounds = 10)  # Select specific class  x <- shapviz(fit, X_pred = X_pred, which_class = 3)  x  # Or combine all classes to a "mshapviz" object  mx <- shapviz(fit, X_pred = X_pred)  mx  all.equal(mx[[3]], x)}

Splits "shapviz" Object

Description

Splits "shapviz" object along a vectorf into an object of class "mshapviz".

Usage

## S3 method for class 'shapviz'split(x, f, ...)

Arguments

Value

A "mshapviz" object.

See Also

shapviz(),rbind.shapviz()

Examples

## Not run: dtrain <- xgboost::xgb.DMatrix(data.matrix(iris[, -1]), label = iris[, 1])fit <- xgboost::xgb.train(data = dtrain, nrounds = 10, nthread = 1)sv <- shapviz(fit, X_pred = dtrain, X = iris)mx <- split(sv, f = iris$Species)sv_dependence(mx, "Petal.Length")## End(Not run)

Summarizes "shapviz" Object

Description

Summarizes "shapviz" Object

Usage

## S3 method for class 'shapviz'summary(object, n = 2L, ...)

Arguments

Value

Invisibly, the input is returned.

See Also

shapviz()

Examples

S <- matrix(c(1, -1, -1, 1), ncol = 2, dimnames = list(NULL, c("x", "y")))X <- data.frame(x = c("a", "b"), y = c(100, 10))object <- shapviz(S, X, baseline = 4)summary(object)

SHAP Dependence Plot

Description

Scatterplot of the SHAP values of a feature against its feature values.If SHAP interaction values are available, settinginteractions = TRUE allowsto focus on pure interaction effects (multiplied by two) or on pure main effects.By default, the feature on the color scale is selected via SHAP interactions(if available) or an interaction heuristic, seepotential_interactions().

Usage

sv_dependence(object, ...)## Default S3 method:sv_dependence(object, ...)## S3 method for class 'shapviz'sv_dependence(  object,  v,  color_var = "auto",  color = "#3b528b",  viridis_args = getOption("shapviz.viridis_args"),  jitter_width = NULL,  interactions = FALSE,  ih_nbins = NULL,  ih_color_num = TRUE,  ih_scale = FALSE,  ih_adjusted = FALSE,  share_y = FALSE,  ylim = NULL,  seed = 1L,  ...)## S3 method for class 'mshapviz'sv_dependence(  object,  v,  color_var = "auto",  color = "#3b528b",  viridis_args = getOption("shapviz.viridis_args"),  jitter_width = NULL,  interactions = FALSE,  ih_nbins = NULL,  ih_color_num = TRUE,  ih_scale = FALSE,  ih_adjusted = FALSE,  share_y = FALSE,  ylim = NULL,  seed = 1L,  ...)

Arguments

Value

An object of class "ggplot" (or "patchwork") representing a dependence plot.

Methods (by class)

• sv_dependence(default): Default method.

• sv_dependence(shapviz): SHAP dependence plot for "shapviz" object.

• sv_dependence(mshapviz): SHAP dependence plot for "mshapviz" object.

See Also

potential_interactions()

Examples

dtrain <- xgboost::xgb.DMatrix(  data.matrix(iris[, -1]),  label = iris[, 1], nthread = 1)fit <- xgboost::xgb.train(data = dtrain, nrounds = 10, nthread = 1)x <- shapviz(fit, X_pred = dtrain, X = iris)sv_dependence(x, "Petal.Length")sv_dependence(x, "Petal.Length", color_var = "Species")sv_dependence(x, "Petal.Length", color_var = NULL)sv_dependence(x, c("Species", "Petal.Length"), share_y = TRUE)sv_dependence(x, "Petal.Width", color_var = c("Species", "Petal.Length")) +  patchwork::plot_layout(ncol = 1)# SHAP interaction values/main effectsx2 <- shapviz(fit, X_pred = dtrain, X = iris, interactions = TRUE)sv_dependence(x2, "Petal.Length", interactions = TRUE)sv_dependence(  x2, c("Petal.Length", "Species"),  color_var = NULL, interactions = TRUE)sv_dependence(  x2, "Petal.Length",  color_var = colnames(iris[-1]), interactions = TRUE,  share_y = TRUE)

2D SHAP Dependence Plot

Description

Scatterplot of two features, showing the sum of their SHAP values on the color scale.This allows to visualize the combined effect of two features, including interactions.A typical application are models with latitude and longitude as features (plusmaybe other regional features that can be passed viaadd_vars).

If SHAP interaction values are available, settinginteractions = TRUE allowsto focus on pure interaction effects (multiplied by two). In this case,add_varshas no effect.

Usage

sv_dependence2D(object, ...)## Default S3 method:sv_dependence2D(object, ...)## S3 method for class 'shapviz'sv_dependence2D(  object,  x,  y,  viridis_args = getOption("shapviz.viridis_args"),  jitter_width = NULL,  jitter_height = NULL,  interactions = FALSE,  add_vars = NULL,  seed = 1L,  ...)## S3 method for class 'mshapviz'sv_dependence2D(  object,  x,  y,  viridis_args = getOption("shapviz.viridis_args"),  jitter_width = NULL,  jitter_height = NULL,  interactions = FALSE,  add_vars = NULL,  seed = 1L,  ...)

Arguments

Value

An object of class "ggplot" (or "patchwork") representing a dependence plot.

Methods (by class)

• sv_dependence2D(default): Default method.

• sv_dependence2D(shapviz): 2D SHAP dependence plot for "shapviz" object.

• sv_dependence2D(mshapviz): 2D SHAP dependence plot for "mshapviz" object.

See Also

sv_dependence()

Examples

dtrain <- xgboost::xgb.DMatrix(  data.matrix(iris[, -1]),  label = iris[, 1], nthread = 1)fit <- xgboost::xgb.train(data = dtrain, nrounds = 10, nthread = 1)sv <- shapviz(fit, X_pred = dtrain, X = iris)sv_dependence2D(sv, x = "Petal.Length", y = "Species")sv_dependence2D(sv, x = c("Petal.Length", "Species"), y = "Sepal.Width")# SHAP interaction valuessv2 <- shapviz(fit, X_pred = dtrain, X = iris, interactions = TRUE)sv_dependence2D(sv2, x = "Petal.Length", y = "Species", interactions = TRUE)sv_dependence2D(  sv2,  x = "Petal.Length", y = c("Species", "Petal.Width"), interactions = TRUE)# mshapviz objectmx <- split(sv, f = iris$Species)sv_dependence2D(mx, x = "Petal.Length", y = "Sepal.Width")

SHAP Force Plot

Description

Creates a force plot of SHAP values of one observation. If multipleobservations are selected, their SHAP values and predictions are averaged.

Usage

sv_force(object, ...)## Default S3 method:sv_force(object, ...)## S3 method for class 'shapviz'sv_force(  object,  row_id = 1L,  max_display = 6L,  fill_colors = c("#f7d13d", "#a52c60"),  format_shap = getOption("shapviz.format_shap"),  format_feat = getOption("shapviz.format_feat"),  contrast = TRUE,  bar_label_size = 3.2,  show_annotation = TRUE,  annotation_size = 3.2,  ...)## S3 method for class 'mshapviz'sv_force(  object,  row_id = 1L,  max_display = 6L,  fill_colors = c("#f7d13d", "#a52c60"),  format_shap = getOption("shapviz.format_shap"),  format_feat = getOption("shapviz.format_feat"),  contrast = TRUE,  bar_label_size = 3.2,  show_annotation = TRUE,  annotation_size = 3.2,  ...)

Arguments

Details

f(x) denotes the prediction on the SHAP scale, while E(f(x)) refers to thebaseline SHAP value.

Value

An object of class "ggplot" (or "patchwork") representing a force plot.

Methods (by class)

• sv_force(default): Default method.

• sv_force(shapviz): SHAP force plot for object of class "shapviz".

• sv_force(mshapviz): SHAP force plot for object of class "mshapviz".

See Also

sv_waterfall()

Examples

dtrain <- xgboost::xgb.DMatrix(  data.matrix(iris[, -1]),  label = iris[, 1], nthread = 1)fit <- xgboost::xgb.train(data = dtrain, nrounds = 20, nthread = 1)x <- shapviz(fit, X_pred = dtrain, X = iris[, -1])sv_force(x)sv_force(x, row_id = 65, max_display = 3, size = 9, fill_colors = 4:5)# Aggregate over all observations with Petal.Length == 1.4sv_force(x, row_id = x$X$Petal.Length == 1.4)# Two observations separatelysv_force(c(x[1, ], x[2, ])) +  patchwork::plot_layout(ncol = 1)

SHAP Importance Plots

Description

This function provides two types of SHAP importance plots: a bar plotand a beeswarm plot (sometimes called "SHAP summary plot").The two types of plots can also be combined.

Usage

sv_importance(object, ...)## Default S3 method:sv_importance(object, ...)## S3 method for class 'shapviz'sv_importance(  object,  kind = c("bar", "beeswarm", "both", "no"),  max_display = 15L,  fill = "#fca50a",  bar_width = 2/3,  bee_width = 0.4,  bee_adjust = 0.5,  viridis_args = getOption("shapviz.viridis_args"),  color_bar_title = "Feature value",  show_numbers = FALSE,  format_fun = format_max,  number_size = 3.2,  sort_features = TRUE,  ...)## S3 method for class 'mshapviz'sv_importance(  object,  kind = c("bar", "beeswarm", "both", "no"),  max_display = 15L,  fill = "#fca50a",  bar_width = 2/3,  bar_type = c("dodge", "stack", "facets", "separate"),  bee_width = 0.4,  bee_adjust = 0.5,  viridis_args = getOption("shapviz.viridis_args"),  color_bar_title = "Feature value",  show_numbers = FALSE,  format_fun = format_max,  number_size = 3.2,  sort_features = TRUE,  ...)

Arguments

Details

The bar plot shows SHAP feature importances, calculated as the average absolute SHAPvalue per feature. The beeswarm plot displays SHAP values per feature, using min-maxscaled feature values on the color axis. Non-numeric features are transformedto numeric by callingdata.matrix() first. For both types of plots, the featuresare sorted in decreasing order of importance.

Value

A "ggplot" (or "patchwork") object representing an importance plot, or - ifkind = "no" - a named numeric vector of sorted SHAP feature importances(or a matrix in case of an object of class "mshapviz").

Methods (by class)

• sv_importance(default): Default method.

• sv_importance(shapviz): SHAP importance plot for an object of class "shapviz".

• sv_importance(mshapviz): SHAP importance plot for an object of class "mshapviz".

See Also

sv_interaction

Examples

X_train <- data.matrix(iris[, -1])dtrain <- xgboost::xgb.DMatrix(X_train, label = iris[, 1], nthread = 1)fit <- xgboost::xgb.train(data = dtrain, nrounds = 10, nthread = 1)x <- shapviz(fit, X_pred = X_train)sv_importance(x)sv_importance(x, kind = "no")sv_importance(x, kind = "beeswarm", show_numbers = TRUE)

SHAP Interaction Plot

Description

Creates a beeswarm plot or a barplot of SHAP interaction values/main effects.

In the beeswarm plot (kind = "beeswarm"), diagonals represent the main effects,while off-diagonals show SHAP interactions (multiplied by two due to symmetry).The color axis represent min-max scaled feature values.Non-numeric features are transformed to numeric by callingdata.matrix() first.The features are sorted in decreasing order of usual SHAP importance.

The barplot (kind = "bar") shows average absolute SHAP interaction valuesand main effects for each feature pair.Again, due to symmetry, the interaction values are multiplied by two.

Usage

sv_interaction(object, ...)## Default S3 method:sv_interaction(object, ...)## S3 method for class 'shapviz'sv_interaction(  object,  kind = c("beeswarm", "bar", "no"),  max_display = 15L - 8 * (kind == "beeswarm"),  alpha = 0.3,  bee_width = 0.3,  bee_adjust = 0.5,  viridis_args = getOption("shapviz.viridis_args"),  color_bar_title = "Row feature value",  sort_features = TRUE,  fill = "#fca50a",  bar_width = 2/3,  ...)## S3 method for class 'mshapviz'sv_interaction(  object,  kind = c("beeswarm", "bar", "no"),  max_display = 7L,  alpha = 0.3,  bee_width = 0.3,  bee_adjust = 0.5,  viridis_args = getOption("shapviz.viridis_args"),  color_bar_title = "Row feature value",  sort_features = TRUE,  fill = "#fca50a",  bar_width = 2/3,  ...)

Arguments

Value

A "ggplot" (or "patchwork") object, or - ifkind = "no" - a namednumeric matrix of average absolute SHAP interactions sorted by the averageabsolute SHAP values (or a list of such matrices in case of "mshapviz" object).

Methods (by class)

• sv_interaction(default): Default method.

• sv_interaction(shapviz): SHAP interaction plot for an object of class "shapviz".

• sv_interaction(mshapviz): SHAP interaction plot for an object of class "mshapviz".

See Also

sv_importance()

Examples

dtrain <- xgboost::xgb.DMatrix(  data.matrix(iris[, -1]),  label = iris[, 1], nthread = 1)fit <- xgboost::xgb.train(data = dtrain, nrounds = 10, nthread = 1)x <- shapviz(fit, X_pred = dtrain, X = iris, interactions = TRUE)sv_interaction(x, kind = "no")sv_interaction(x, max_display = 2, size = 3)sv_interaction(x, kind = "bar")

SHAP Waterfall Plot

Description

Creates a waterfall plot of SHAP values of one observation. If multipleobservations are selected, their SHAP values and predictions are averaged.

Usage

sv_waterfall(object, ...)## Default S3 method:sv_waterfall(object, ...)## S3 method for class 'shapviz'sv_waterfall(  object,  row_id = 1L,  max_display = 10L,  order_fun = function(s) order(abs(s)),  fill_colors = c("#f7d13d", "#a52c60"),  format_shap = getOption("shapviz.format_shap"),  format_feat = getOption("shapviz.format_feat"),  contrast = TRUE,  show_connection = TRUE,  show_annotation = TRUE,  annotation_size = 3.2,  ...)## S3 method for class 'mshapviz'sv_waterfall(  object,  row_id = 1L,  max_display = 10L,  order_fun = function(s) order(abs(s)),  fill_colors = c("#f7d13d", "#a52c60"),  format_shap = getOption("shapviz.format_shap"),  format_feat = getOption("shapviz.format_feat"),  contrast = TRUE,  show_connection = TRUE,  show_annotation = TRUE,  annotation_size = 3.2,  ...)

Arguments

Details

f(x) denotes the prediction on the SHAP scale, while E(f(x)) refers to thebaseline SHAP value.

Value

An object of class "ggplot" (or "patchwork") representing a waterfall plot.

Methods (by class)

• sv_waterfall(default): Default method.

• sv_waterfall(shapviz): SHAP waterfall plot for an object of class "shapviz".

• sv_waterfall(mshapviz): SHAP waterfall plot for an object of class "mshapviz".

See Also

sv_force()

Examples

dtrain <- xgboost::xgb.DMatrix(  data.matrix(iris[, -1]),  label = iris[, 1], nthread = 1)fit <- xgboost::xgb.train(data = dtrain, nrounds = 20, nthread = 1)x <- shapviz(fit, X_pred = dtrain, X = iris[, -1])sv_waterfall(x)sv_waterfall(x, row_id = 123, max_display = 2, size = 9, fill_colors = 4:5)# Ordered by colnames(x), combined with max_displaysv_waterfall(  x[, sort(colnames(x))],  order_fun = function(s) length(s):1, max_display = 3)# Aggregate over all observations with Petal.Length == 1.4sv_waterfall(x, row_id = x$X$Petal.Length == 1.4)# Two observations separatelysv_waterfall(c(x[1, ], x[2, ])) +  patchwork::plot_layout(ncol = 1)