| Title: | Prediction Explanation with Dependence-Aware Shapley Values |
|---|---|
| Description: | Complex machine learning models are often hard to interpret. However, in many situations it is crucial to understand and explain why a model made a specific prediction. Shapley values is the only method for such prediction explanation framework with a solid theoretical foundation. Previously known methods for estimating the Shapley values do, however, assume feature independence. This package implements methods which accounts for any feature dependence, and thereby produces more accurate estimates of the true Shapley values. An accompanying 'Python' wrapper ('shaprpy') is available through PyPI. |
| Authors: | Martin Jullum [cre, aut] (ORCID: <https://orcid.org/0000-0003-3908-5155>), Lars Henry Berge Olsen [aut] (ORCID: <https://orcid.org/0009-0006-9360-6993>), Annabelle Redelmeier [aut], Jon Lachmann [aut] (ORCID: <https://orcid.org/0000-0001-8396-5673>), Nikolai Sellereite [aut] (ORCID: <https://orcid.org/0000-0002-4671-0337>), Anders Løland [ctb], Jens Christian Wahl [ctb], Camilla Lingjærde [ctb], Norsk Regnesentral [cph, fnd] |
| Maintainer: | Martin Jullum <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.0.8.9000 |
| Built: | 2026-06-09 14:10:14 UTC |
| Source: | https://github.com/norskregnesentral/shapr |
Compute dependence-aware Shapley values for observations in x_explain from the specified
model using the method specified in approach to estimate the conditional expectation.
See Aas et al. (2021)
for a thorough introduction to dependence-aware prediction explanation with Shapley values.
For an overview of the methodology and capabilities of the package, see the software paper
Jullum et al. (2025), or the pkgdown site at
norskregnesentral.github.io/shapr/.
explain( model, x_explain, x_train, approach, phi0, iterative = NULL, max_n_coalitions = NULL, group = NULL, n_MC_samples = 1000, seed = NULL, verbose = "basic", predict_model = NULL, get_model_specs = NULL, prev_shapr_object = NULL, asymmetric = FALSE, causal_ordering = NULL, confounding = NULL, extra_computation_args = list(), iterative_args = list(), output_args = list(), ... )explain( model, x_explain, x_train, approach, phi0, iterative = NULL, max_n_coalitions = NULL, group = NULL, n_MC_samples = 1000, seed = NULL, verbose = "basic", predict_model = NULL, get_model_specs = NULL, prev_shapr_object = NULL, asymmetric = FALSE, causal_ordering = NULL, confounding = NULL, extra_computation_args = list(), iterative_args = list(), output_args = list(), ... )
model |
Model object.
The model whose predictions you want to explain.
Run |
x_explain |
Matrix or data.frame/data.table. Features for which predictions should be explained. |
x_train |
Matrix or data.frame/data.table. Data used to estimate the (conditional) feature distributions needed to properly estimate the conditional expectations in the Shapley formula. |
approach |
Character vector of length |
phi0 |
Numeric. The prediction value for unseen data, i.e., an estimate of the expected prediction without conditioning on any features. Typically set this equal to the mean of the response in the training data, but alternatives such as the mean of the training predictions are also reasonable. |
iterative |
Logical or NULL.
If |
max_n_coalitions |
Integer.
Upper limit on the number of unique feature/group coalitions to use in the iterative procedure
(if |
group |
List.
If |
n_MC_samples |
Positive integer.
For most approaches, it indicates the maximum number of samples to use in the Monte Carlo integration
of every conditional expectation.
For |
seed |
Positive integer.
Specifies the seed before any code involving randomness is run.
If |
verbose |
String vector or NULL.
Controls verbosity (printout detail level) via one or more of |
predict_model |
Function.
Prediction function to use when |
get_model_specs |
Function.
An optional function for checking model/data consistency when
If |
prev_shapr_object |
|
asymmetric |
Logical.
Not applicable for (regular) non-causal explanations.
If |
causal_ordering |
List.
Not applicable for (regular) non-causal or asymmetric explanations.
|
confounding |
Logical vector.
Not applicable for (regular) non-causal or asymmetric explanations.
|
extra_computation_args |
Named list.
Specifies extra arguments related to the computation of the Shapley values.
See the help file of |
iterative_args |
Named list.
Specifies the arguments for the iterative procedure.
See the help file of |
output_args |
Named list.
Specifies certain arguments related to the output of the function.
See the help file of |
... |
Arguments passed on to
|
The shapr package implements kernelSHAP estimation of dependence-aware Shapley values with
eight different Monte Carlo-based approaches for estimating the conditional distributions of the data.
These are all introduced in the
general usage vignette.
(From R: vignette("general_usage", package = "shapr")).
For an overview of the methodology and capabilities of the package, please also see the software paper
Jullum et al. (2025).
Moreover,
Aas et al. (2021)
gives a general introduction to dependence-aware Shapley values and the approaches "empirical",
"gaussian", "copula", and also discusses "independence".
Redelmeier et al. (2020) introduces the approach "ctree".
Olsen et al. (2022) introduces the "vaeac"
approach.
Approach "timeseries" is discussed in
Jullum et al. (2021).
shapr has also implemented two regression-based approaches "regression_separate" and "regression_surrogate",
as described in Olsen et al. (2024).
It is also possible to combine the different approaches, see the
general usage vignette for more information.
The package also supports the computation of causal and asymmetric Shapley values as introduced by
Heskes et al. (2020) and
Frye et al. (2020).
Asymmetric Shapley values were proposed by
Frye et al. (2020) as a way to incorporate causal knowledge in
the real world by restricting the possible feature combinations/coalitions when computing the Shapley values to
those consistent with a (partial) causal ordering.
Causal Shapley values were proposed by
Heskes et al. (2020) as a way to explain the total effect of features
on the prediction, taking into account their causal relationships, by adapting the sampling procedure in shapr.
The package allows parallelized computation with progress updates through the tightly connected
future::future and progressr::progressr packages.
See the examples below.
For iterative estimation (iterative=TRUE), intermediate results may be printed to the console
(according to the verbose argument).
Moreover, the intermediate results are written to disk.
This combined batch computation of the v(S) values enables fast and accurate estimation of the Shapley values
in a memory-friendly manner.
Object of class c("shapr", "list"). Contains the following items:
shapley_values_estdata.table with the estimated Shapley values with explained observation in the rows and
features along the columns.
The column none is the prediction not devoted to any of the features (given by the argument phi0)
shapley_values_sddata.table with the standard deviation of the Shapley values reflecting the uncertainty
in the coalition sampling part of the kernelSHAP procedure.
These are, by definition, 0 when all coalitions are used.
Only present when extra_computation_args$compute_sd=TRUE, which is the default when iterative = TRUE.
internalList with the different parameters, data, functions and other output used internally.
pred_explainNumeric vector with the predictions for the explained observations.
MSEvList with the values of the MSEv evaluation criterion for the approach. See the MSEv evaluation section in the general usage vignette for details.
timingList containing timing information for the different parts of the computation.
summary contains the time stamps for the start and end time in addition to the total execution time.
overall_timing_secs gives the time spent on different parts of the explanation computation.
main_computation_timing_secs further decomposes the main computation time into different parts of the
computation for each iteration of the iterative estimation routine, if used.
Martin Jullum, Lars Henry Berge Olsen
# Load example data data("airquality") airquality <- airquality[complete.cases(airquality), ] x_var <- c("Solar.R", "Wind", "Temp", "Month") y_var <- "Ozone" # Split data into test and training data data_train <- head(airquality, -3) data_explain <- tail(airquality, 3) x_train <- data_train[, x_var] x_explain <- data_explain[, x_var] # Fit a linear model lm_formula <- as.formula(paste0(y_var, " ~ ", paste0(x_var, collapse = " + "))) model <- lm(lm_formula, data = data_train) # Explain predictions p <- mean(data_train[, y_var]) # (Optionally) enable parallelization via the future package if (requireNamespace("future", quietly = TRUE)) { future::plan("multisession", workers = 2) } # (Optionally) enable progress updates within every iteration via the progressr package if (requireNamespace("progressr", quietly = TRUE)) { progressr::handlers(global = TRUE) } # Empirical approach explain1 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "empirical", phi0 = p, n_MC_samples = 1e2 ) # Gaussian approach explain2 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "gaussian", phi0 = p, n_MC_samples = 1e2 ) # Gaussian copula approach explain3 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "copula", phi0 = p, n_MC_samples = 1e2 ) if (requireNamespace("party", quietly = TRUE)) { # ctree approach explain4 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "ctree", phi0 = p, n_MC_samples = 1e2 ) } # Combined approach approach <- c("gaussian", "gaussian", "empirical") explain5 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = approach, phi0 = p, n_MC_samples = 1e2 ) ## Printing print(explain1) # The Shapley values print(explain1) # The Shapley values # The MSEv criterion (+sd). Smaller values indicate a better approach. print(explain1, what = "MSEv") print(explain2, what = "MSEv") print(explain3, what = "MSEv") ## Summary summary1 <- summary(explain1) summary1 # Provides a nicely formatted summary of the explanation # Various additional info stored in the summary object # Examples summary1$shapley_est # A data.table with the Shapley values summary1$timing$total_time_secs # Total computation time in seconds summary1$parameters$n_MC_samples # Number of Monte Carlo samples used for the numerical integration summary1$parameters$empirical.type # Type of empirical approach used # Plot the results if (requireNamespace("ggplot2", quietly = TRUE)) { plot(explain1) plot(explain1, plot_type = "waterfall") } # Group-wise explanations group_list <- list(A = c("Temp", "Month"), B = c("Wind", "Solar.R")) explain_groups <- explain( model = model, x_explain = x_explain, x_train = x_train, group = group_list, approach = "empirical", phi0 = p, n_MC_samples = 1e2 ) print(explain_groups) # Separate and surrogate regression approaches with linear regression models. req_pkgs <- c("parsnip", "recipes", "workflows", "rsample", "tune", "yardstick") if (requireNamespace(req_pkgs, quietly = TRUE)) { explain_separate_lm <- explain( model = model, x_explain = x_explain, x_train = x_train, phi0 = p, approach = "regression_separate", regression.model = parsnip::linear_reg() ) explain_surrogate_lm <- explain( model = model, x_explain = x_explain, x_train = x_train, phi0 = p, approach = "regression_surrogate", regression.model = parsnip::linear_reg() ) } # Iterative estimation # For illustration only. By default not used for such small dimensions as here. # Restricting the initial and maximum number of coalitions as well. explain_iterative <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "gaussian", phi0 = p, iterative = TRUE, iterative_args = list(initial_n_coalitions = 8), max_n_coalitions = 12 ) # When not using all coalitions, we can also get the SD of the Shapley values, # reflecting uncertainty in the coalition sampling part of the procedure. print(explain_iterative, what = "shapley_sd") ## Summary # For iterative estimation, convergence info is also provided summary_iterative <- summary(explain_iterative)# Load example data data("airquality") airquality <- airquality[complete.cases(airquality), ] x_var <- c("Solar.R", "Wind", "Temp", "Month") y_var <- "Ozone" # Split data into test and training data data_train <- head(airquality, -3) data_explain <- tail(airquality, 3) x_train <- data_train[, x_var] x_explain <- data_explain[, x_var] # Fit a linear model lm_formula <- as.formula(paste0(y_var, " ~ ", paste0(x_var, collapse = " + "))) model <- lm(lm_formula, data = data_train) # Explain predictions p <- mean(data_train[, y_var]) # (Optionally) enable parallelization via the future package if (requireNamespace("future", quietly = TRUE)) { future::plan("multisession", workers = 2) } # (Optionally) enable progress updates within every iteration via the progressr package if (requireNamespace("progressr", quietly = TRUE)) { progressr::handlers(global = TRUE) } # Empirical approach explain1 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "empirical", phi0 = p, n_MC_samples = 1e2 ) # Gaussian approach explain2 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "gaussian", phi0 = p, n_MC_samples = 1e2 ) # Gaussian copula approach explain3 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "copula", phi0 = p, n_MC_samples = 1e2 ) if (requireNamespace("party", quietly = TRUE)) { # ctree approach explain4 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "ctree", phi0 = p, n_MC_samples = 1e2 ) } # Combined approach approach <- c("gaussian", "gaussian", "empirical") explain5 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = approach, phi0 = p, n_MC_samples = 1e2 ) ## Printing print(explain1) # The Shapley values print(explain1) # The Shapley values # The MSEv criterion (+sd). Smaller values indicate a better approach. print(explain1, what = "MSEv") print(explain2, what = "MSEv") print(explain3, what = "MSEv") ## Summary summary1 <- summary(explain1) summary1 # Provides a nicely formatted summary of the explanation # Various additional info stored in the summary object # Examples summary1$shapley_est # A data.table with the Shapley values summary1$timing$total_time_secs # Total computation time in seconds summary1$parameters$n_MC_samples # Number of Monte Carlo samples used for the numerical integration summary1$parameters$empirical.type # Type of empirical approach used # Plot the results if (requireNamespace("ggplot2", quietly = TRUE)) { plot(explain1) plot(explain1, plot_type = "waterfall") } # Group-wise explanations group_list <- list(A = c("Temp", "Month"), B = c("Wind", "Solar.R")) explain_groups <- explain( model = model, x_explain = x_explain, x_train = x_train, group = group_list, approach = "empirical", phi0 = p, n_MC_samples = 1e2 ) print(explain_groups) # Separate and surrogate regression approaches with linear regression models. req_pkgs <- c("parsnip", "recipes", "workflows", "rsample", "tune", "yardstick") if (requireNamespace(req_pkgs, quietly = TRUE)) { explain_separate_lm <- explain( model = model, x_explain = x_explain, x_train = x_train, phi0 = p, approach = "regression_separate", regression.model = parsnip::linear_reg() ) explain_surrogate_lm <- explain( model = model, x_explain = x_explain, x_train = x_train, phi0 = p, approach = "regression_surrogate", regression.model = parsnip::linear_reg() ) } # Iterative estimation # For illustration only. By default not used for such small dimensions as here. # Restricting the initial and maximum number of coalitions as well. explain_iterative <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "gaussian", phi0 = p, iterative = TRUE, iterative_args = list(initial_n_coalitions = 8), max_n_coalitions = 12 ) # When not using all coalitions, we can also get the SD of the Shapley values, # reflecting uncertainty in the coalition sampling part of the procedure. print(explain_iterative, what = "shapley_sd") ## Summary # For iterative estimation, convergence info is also provided summary_iterative <- summary(explain_iterative)
Computes dependence-aware Shapley values for observations in explain_idx from the specified
model by using the method specified in approach to estimate the conditional expectation.
See
Aas, et. al (2021)
for a thorough introduction to dependence-aware prediction explanation with Shapley values.
For an overview of the methodology and capabilities of the shapr package, see the software paper
Jullum et al. (2025), or the pkgdown site at
norskregnesentral.github.io/shapr/.
explain_forecast( model, y, xreg = NULL, train_idx = NULL, explain_idx, explain_y_lags, explain_xreg_lags = explain_y_lags, horizon, approach, phi0, max_n_coalitions = NULL, iterative = NULL, group_lags = TRUE, group = NULL, n_MC_samples = 1000, seed = NULL, predict_model = NULL, get_model_specs = NULL, verbose = "basic", extra_computation_args = list(), iterative_args = list(), output_args = list(), ... )explain_forecast( model, y, xreg = NULL, train_idx = NULL, explain_idx, explain_y_lags, explain_xreg_lags = explain_y_lags, horizon, approach, phi0, max_n_coalitions = NULL, iterative = NULL, group_lags = TRUE, group = NULL, n_MC_samples = 1000, seed = NULL, predict_model = NULL, get_model_specs = NULL, verbose = "basic", extra_computation_args = list(), iterative_args = list(), output_args = list(), ... )
model |
Model object.
The model whose predictions you want to explain.
Run |
y |
Matrix, data.frame/data.table or a numeric vector. Contains the endogenous variables used to estimate the (conditional) distributions needed to properly estimate the conditional expectations in the Shapley formula including the observations to be explained. |
xreg |
Matrix, data.frame/data.table or a numeric vector. Contains the exogenous variables used to estimate the (conditional) distributions needed to properly estimate the conditional expectations in the Shapley formula including the observations to be explained. As exogenous variables are used contemporaneously when producing a forecast, this item should contain nrow(y) + horizon rows. |
train_idx |
Numeric vector.
The row indices in data and reg denoting points in time to use when estimating the conditional expectations in
the Shapley value formula.
If |
explain_idx |
Numeric vector. The row indices in data and reg denoting points in time to explain. |
explain_y_lags |
Numeric vector.
Denotes the number of lags that should be used for each variable in |
explain_xreg_lags |
Numeric vector.
If |
horizon |
Numeric.
The forecast horizon to explain. Passed to the |
approach |
Character vector of length |
phi0 |
Numeric. The prediction value for unseen data, i.e., an estimate of the expected prediction without conditioning on any features. Typically set this equal to the mean of the response in the training data, but alternatives such as the mean of the training predictions are also reasonable. |
max_n_coalitions |
Integer.
Upper limit on the number of unique feature/group coalitions to use in the iterative procedure
(if |
iterative |
Logical or NULL.
If |
group_lags |
Logical.
If |
group |
List.
If |
n_MC_samples |
Positive integer.
For most approaches, it indicates the maximum number of samples to use in the Monte Carlo integration
of every conditional expectation.
For |
seed |
Positive integer.
Specifies the seed before any code involving randomness is run.
If |
predict_model |
Function.
Prediction function to use when |
get_model_specs |
Function.
An optional function for checking model/data consistency when
If |
verbose |
String vector or NULL.
Controls verbosity (printout detail level) via one or more of |
extra_computation_args |
Named list.
Specifies extra arguments related to the computation of the Shapley values.
See the help file of |
iterative_args |
Named list.
Specifies the arguments for the iterative procedure.
See the help file of |
output_args |
Named list.
Specifies certain arguments related to the output of the function.
See the help file of |
... |
Arguments passed on to
|
This function explains a forecast of length horizon. The argument train_idx
is analogous to x_train in explain(), however, it just contains the time indices of where
in the data the forecast should start for each training sample. In the same way explain_idx
defines the time index (indices) which will precede a forecast to be explained.
As any autoregressive forecast model will require a set of lags to make a forecast at an
arbitrary point in time, explain_y_lags and explain_xreg_lags define how many lags
are required to "refit" the model at any given time index. This allows the different
approaches to work in the same way they do for time-invariant models.
See the forecasting section of the general usage vignette for further details. See also the software paper Jullum et al. (2025, Sec. 6) for a more detailed introduction to the methodology, and additional examples.
Object of class c("shapr", "list"). Contains the following items:
shapley_values_estdata.table with the estimated Shapley values with explained observation in the rows and
features along the columns.
The column none is the prediction not devoted to any of the features (given by the argument phi0)
shapley_values_sddata.table with the standard deviation of the Shapley values reflecting the uncertainty
in the coalition sampling part of the kernelSHAP procedure.
These are, by definition, 0 when all coalitions are used.
Only present when extra_computation_args$compute_sd=TRUE, which is the default when iterative = TRUE.
internalList with the different parameters, data, functions and other output used internally.
pred_explainNumeric vector with the predictions for the explained observations.
MSEvList with the values of the MSEv evaluation criterion for the approach. See the MSEv evaluation section in the general usage vignette for details.
timingList containing timing information for the different parts of the computation.
summary contains the time stamps for the start and end time in addition to the total execution time.
overall_timing_secs gives the time spent on different parts of the explanation computation.
main_computation_timing_secs further decomposes the main computation time into different parts of the
computation for each iteration of the iterative estimation routine, if used.
Jon Lachmann, Martin Jullum
# Load example data data("airquality") data <- data.table::as.data.table(airquality) # Fit an AR(2) model. model_ar_temp <- ar(data$Temp, order = 2) # Calculate the zero prediction values for a three step forecast. p0_ar <- rep(mean(data$Temp), 3) # Empirical approach, explaining forecasts starting at T = 152 and T = 153. explain_forecast( model = model_ar_temp, y = data[, "Temp"], train_idx = 2:151, explain_idx = 152:153, explain_y_lags = 2, horizon = 3, approach = "empirical", phi0 = p0_ar, group_lags = FALSE )# Load example data data("airquality") data <- data.table::as.data.table(airquality) # Fit an AR(2) model. model_ar_temp <- ar(data$Temp, order = 2) # Calculate the zero prediction values for a three step forecast. p0_ar <- rep(mean(data$Temp), 3) # Empirical approach, explaining forecasts starting at T = 152 and T = 153. explain_forecast( model = model_ar_temp, y = data[, "Temp"], train_idx = 2:151, explain_idx = 152:153, explain_y_lags = 2, horizon = 3, approach = "empirical", phi0 = p0_ar, group_lags = FALSE )
Get the Default Values for the Extra Computation Arguments
get_extra_comp_args_default( internal, paired_shap_sampling = isFALSE(internal$parameters$asymmetric), semi_deterministic_sampling = FALSE, kernelSHAP_reweighting = "on_all_cond", compute_sd = isFALSE(internal$parameters$exact), n_boot_samps = 100, vS_batching_method = "future", max_batch_size = 10, min_n_batches = 10 )get_extra_comp_args_default( internal, paired_shap_sampling = isFALSE(internal$parameters$asymmetric), semi_deterministic_sampling = FALSE, kernelSHAP_reweighting = "on_all_cond", compute_sd = isFALSE(internal$parameters$exact), n_boot_samps = 100, vS_batching_method = "future", max_batch_size = 10, min_n_batches = 10 )
internal |
List.
Not used directly, but passed through from |
paired_shap_sampling |
Logical.
If |
semi_deterministic_sampling |
Logical.
If |
kernelSHAP_reweighting |
String.
How to reweight the sampling frequency weights in the kernelSHAP solution after sampling.
The aim of this is to reduce the randomness and thereby the variance of the Shapley value estimates.
The options are one of |
compute_sd |
Logical. Whether to estimate the standard deviations of the Shapley value estimates. This is TRUE whenever sampling based kernelSHAP is applied (either iteratively or with a fixed number of coalitions). |
n_boot_samps |
Integer. The number of bootstrapped samples (i.e. samples with replacement) from the set of all coalitions used to estimate the standard deviations of the Shapley value estimates. |
vS_batching_method |
String. The method used to perform batch computing of vS.
|
max_batch_size |
Integer. The maximum number of coalitions to estimate simultaneously within each iteration. A larger number requires more memory, but may have a slight computational advantage. |
min_n_batches |
Integer. The minimum number of batches to split the computation into within each iteration. Larger numbers give more frequent progress updates. If parallelization is applied, this should be set no smaller than the number of parallel workers. |
A list with the default values for the extra computation arguments.
Martin Jullum
Function to specify arguments of the iterative estimation procedure
get_iterative_args_default( internal, initial_n_coalitions = ceiling(min(200, max(5, internal$parameters$n_features, (2^internal$parameters$n_features)/10), internal$parameters$max_n_coalitions)), fixed_n_coalitions_per_iter = NULL, max_iter = 20, convergence_tol = 0.02, n_coal_next_iter_factor_vec = c(seq(0.1, 1, by = 0.1), rep(1, max_iter - 10)) )get_iterative_args_default( internal, initial_n_coalitions = ceiling(min(200, max(5, internal$parameters$n_features, (2^internal$parameters$n_features)/10), internal$parameters$max_n_coalitions)), fixed_n_coalitions_per_iter = NULL, max_iter = 20, convergence_tol = 0.02, n_coal_next_iter_factor_vec = c(seq(0.1, 1, by = 0.1), rep(1, max_iter - 10)) )
internal |
List.
Not used directly, but passed through from |
initial_n_coalitions |
Integer. Number of coalitions to use in the first estimation iteration. |
fixed_n_coalitions_per_iter |
Integer. Number of |
max_iter |
Integer. Maximum number of estimation iterations |
convergence_tol |
Numeric. The t variable in the convergence threshold formula on page 6 in the paper Covert and Lee (2021), 'Improving KernelSHAP: Practical Shapley Value Estimation via Linear Regression' https://arxiv.org/pdf/2012.01536. Smaller values requires more coalitions before convergence is reached. |
n_coal_next_iter_factor_vec |
Numeric vector. The number of |
The functions sets default values for the iterative estimation procedure, according to the function
defaults.
If the argument iterative of explain() is FALSE, it sets parameters corresponding to the use of a
non-iterative estimation procedure
A list with the default values for the iterative estimation procedure
Martin Jullum
Get the Default Values for the Output Arguments
get_output_args_default( keep_samp_for_vS = FALSE, MSEv_uniform_comb_weights = TRUE, saving_path = tempfile("shapr_obj_", fileext = ".rds") )get_output_args_default( keep_samp_for_vS = FALSE, MSEv_uniform_comb_weights = TRUE, saving_path = tempfile("shapr_obj_", fileext = ".rds") )
keep_samp_for_vS |
Logical.
Indicates whether the samples used in the Monte Carlo estimation of |
MSEv_uniform_comb_weights |
Logical.
If |
saving_path |
String. The path to the directory where the results of the iterative estimation procedure should be saved. Defaults to a temporary directory. |
A list of default output arguments.
Martin Jullum
Extract Components from a Shapr Object
get_results( x, what = c("calling_function", "proglang", "approach", "shapley_est", "shapley_sd", "pred_explain", "MSEv", "MSEv_explicand", "MSEv_coalition", "iterative_info", "iterative_shapley_est", "iterative_shapley_sd", "saving_path", "timing_summary", "timing_details", "parameters", "x_train", "x_explain", "dt_vS", "dt_samp_for_vS", "dt_used_coalitions", "dt_valid_causal_coalitions", "dt_coal_samp_info"), ... )get_results( x, what = c("calling_function", "proglang", "approach", "shapley_est", "shapley_sd", "pred_explain", "MSEv", "MSEv_explicand", "MSEv_coalition", "iterative_info", "iterative_shapley_est", "iterative_shapley_sd", "saving_path", "timing_summary", "timing_details", "parameters", "x_train", "x_explain", "dt_vS", "dt_samp_for_vS", "dt_used_coalitions", "dt_valid_causal_coalitions", "dt_coal_samp_info"), ... )
x |
A |
what |
Character vector specifying one or more components to extract. Options: "calling_function", "proglang", "approach", "shapley_est", "shapley_sd", "pred_explain", "MSEv", "MSEv_explicand", "MSEv_coalition", "iterative_info", "iterative_shapley_est", "iterative_shapley_sd", "saving_path", "timing_summary", "timing_details", "parameters", "x_train", "x_explain", "dt_vS", "dt_samp_for_vS", "dt_used_coalitions", "dt_valid_causal_coalitions", "dt_coal_samp_info". The default is to return all components. See details for what each component contains. |
... |
Not used |
The function extracts a full suite of information related to the computation of the Shapley values from
a shapr object.
The allowed characters in what provides information as follows:
calling_functionName of function called to create the shapr object,
(explain() or explain_forecast()).
proglangProgramming language used to initiate the computations (R or Python).
approachApproach used to estimate the conditional expectations.
shapley_estdata.table with the estimated Shapley values.
shapley_sddata.table with the standard deviation of the Shapley values reflecting the uncertainty in the coalition sampling part of the kernelSHAP procedure.
pred_explainNumeric vector with the predictions for the explained observations.
MSEv/MSEv_explicand/MSEv_coalitionData.tables with MSEv evaluation criterion values overall/
per explicand/per coalition.
Smaller values indicate better estimates of v(S).
See the
MSEv evaluation section in the general usage vignette for details.
iterative_infoData.table with information about the iterative estimation procedure.
iterative_shapley_est/iterative_shapley_sdData.tables with the estimated Shapley values/their standard deviation for each iteration (when using the iterative estimation procedure).
saving_pathCharacter string with the path where the (temporary) results are saved.
timing_summaryData.table with one row and three columns: init_time and end_time give the time stamps
for the start and end of the computation, respectively, while total_time_secs gives the total time in seconds
for the full computation.
timing_detailsList containing timing information for the different parts of the computation.
summary contains the information from timing_summary.
overall_timing_secs gives the time spent on the different parts of the explanation computation.
main_computation_timing_secs further decomposes the main computation time into the different parts of the
computation for each iteration of the iterative estimation routine, if used.
parametersList with the parameters used in the computation.
x_train/x_explainData.tables with the training data used in the computation/observations to explain.
dt_vSData.table with the contribution function (v(S)) estimates for each coalition.
dt_samp_for_vSData.table with the samples used in the Monte Carlo estimation of the contribution function
(v(S)).
This is only available if output_args_default$keep_samp_for_vS = TRUE (defaults to FALSE) in explain().
dt_used_coalitionsData.table with an overview of the coalitions used in the computation.
dt_valid_causal_coalitionsData.table with the valid causal coalitions used in the computation.
dt_coal_samp_infoData.table with information related to the coalition sampling procedure being used.
Note that the summary.shapr() function provides a nicely formatted printout with the most important
information, to then invisibly return the output of the present function.
The print.shapr() allows direct printing of the main results.
If a single component is requested, returns that object. If multiple are requested, returns a named list.
Get the Implemented Approaches
get_supported_approaches()get_supported_approaches()
Character vector.
The names of the implemented approaches that can be passed to argument approach in explain().
data.table with the Supported ModelsProvide a data.table with the Supported Models
get_supported_models()get_supported_models()
A data.table with the supported models.
Make plots to visualize and compare the MSEv evaluation criterion for a list of
explain() objects applied to the same data and model. The function creates
bar plots and line plots with points to illustrate the overall MSEv evaluation
criterion, but also for each observation/explicand and coalition by only averaging over
the coalitions and observations/explicands, respectively.
plot_MSEv_eval_crit( explanation_list, index_x_explain = 1:10, id_coalition = NULL, CI_level = if (length(explanation_list[[1]]$pred_explain) < 20) NULL else 0.95, geom_col_width = 0.9, plot_type = "overall" )plot_MSEv_eval_crit( explanation_list, index_x_explain = 1:10, id_coalition = NULL, CI_level = if (length(explanation_list[[1]]$pred_explain) < 20) NULL else 0.95, geom_col_width = 0.9, plot_type = "overall" )
explanation_list |
A list of |
index_x_explain |
Integer vector.
Which of the test observations to plot. For example, if you have
explained 10 observations using |
id_coalition |
Integer vector. Which of the coalitions to plot.
E.g. if you used |
CI_level |
Positive numeric between zero and one. Default is |
geom_col_width |
Numeric. Bar width. By default, set to 90% of the |
plot_type |
Character vector. The possible options are "overall" (default), "coalition", and "explicand".
If |
Note that in contrast to plot.shapr(), plot_MSEv_eval_crit() always just returns the ggplot objects,
i.e. no force displaying through ggplot2::print.ggplot().
Either a single ggplot2::ggplot() object of the MSEv criterion when plot_type = "overall", or a list
of ggplot2::ggplot() objects based on the plot_type parameter.
Lars Henry Berge Olsen
if (requireNamespace("xgboost", quietly = TRUE) && requireNamespace("ggplot2", quietly = TRUE)) { # Get the data data("airquality") data <- data.table::as.data.table(airquality) data <- data[complete.cases(data), ] #' Define the features and the response x_var <- c("Solar.R", "Wind", "Temp", "Month") y_var <- "Ozone" # Split data into test and training data set ind_x_explain <- 1:25 x_train <- data[-ind_x_explain, ..x_var] y_train <- data[-ind_x_explain, get(y_var)] x_explain <- data[ind_x_explain, ..x_var] # Fitting a basic xgboost model to the training data model <- xgboost::xgboost( x = x_train, y = y_train, nround = 20, verbosity = 0 ) # Specifying the phi_0, i.e. the expected prediction without any features phi0 <- mean(y_train) # Independence approach explanation_independence <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "independence", phi0 = phi0, n_MC_samples = 1e2 ) # Gaussian 1e1 approach explanation_gaussian_1e1 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "gaussian", phi0 = phi0, n_MC_samples = 1e1 ) # Gaussian 1e2 approach explanation_gaussian_1e2 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "gaussian", phi0 = phi0, n_MC_samples = 1e2 ) # ctree approach explanation_ctree <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "ctree", phi0 = phi0, n_MC_samples = 1e2 ) # Combined approach explanation_combined <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = c("gaussian", "independence", "ctree"), phi0 = phi0, n_MC_samples = 1e2 ) # Create a list of explanations with names explanation_list_named <- list( "Ind." = explanation_independence, "Gaus. 1e1" = explanation_gaussian_1e1, "Gaus. 1e2" = explanation_gaussian_1e2, "Ctree" = explanation_ctree, "Combined" = explanation_combined ) # Create the default MSEv plot where we average over both the coalitions and observations # with approximate 95% confidence intervals plot_MSEv_eval_crit(explanation_list_named, CI_level = 0.95, plot_type = "overall") # Can also create plots of the MSEv criterion averaged only over the coalitions or observations. MSEv_figures <- plot_MSEv_eval_crit(explanation_list_named, CI_level = 0.95, plot_type = c("overall", "coalition", "explicand") ) MSEv_figures$MSEv_bar MSEv_figures$MSEv_coalition_bar MSEv_figures$MSEv_explicand_bar # When there are many coalitions or observations, then it can be easier to look at line plots MSEv_figures$MSEv_coalition_line_point MSEv_figures$MSEv_explicand_line_point # We can specify which observations or coalitions to plot plot_MSEv_eval_crit(explanation_list_named, plot_type = "explicand", index_x_explain = c(1, 3:4, 6), CI_level = 0.95 )$MSEv_explicand_bar plot_MSEv_eval_crit(explanation_list_named, plot_type = "coalition", id_coalition = c(3, 4, 9, 13:15), CI_level = 0.95 )$MSEv_coalition_bar # We can alter the figures if other palette schemes or design is wanted bar_text_n_decimals <- 1 MSEv_figures$MSEv_bar + ggplot2::scale_x_discrete(limits = rev(levels(MSEv_figures$MSEv_bar$data$Method))) + ggplot2::coord_flip() + ggplot2::scale_fill_discrete() + #' Default ggplot2 palette ggplot2::theme_minimal() + #' This must be set before the other theme call ggplot2::theme( plot.title = ggplot2::element_text(size = 10), legend.position = "bottom" ) + ggplot2::guides(fill = ggplot2::guide_legend(nrow = 1, ncol = 6)) + ggplot2::geom_text( ggplot2::aes(label = sprintf( paste("%.", sprintf("%d", bar_text_n_decimals), "f", sep = ""), round(MSEv, bar_text_n_decimals) )), vjust = -1.1, # This value must be altered based on the plot dimension hjust = 1.1, # This value must be altered based on the plot dimension color = "black", position = ggplot2::position_dodge(0.9), size = 5 ) }if (requireNamespace("xgboost", quietly = TRUE) && requireNamespace("ggplot2", quietly = TRUE)) { # Get the data data("airquality") data <- data.table::as.data.table(airquality) data <- data[complete.cases(data), ] #' Define the features and the response x_var <- c("Solar.R", "Wind", "Temp", "Month") y_var <- "Ozone" # Split data into test and training data set ind_x_explain <- 1:25 x_train <- data[-ind_x_explain, ..x_var] y_train <- data[-ind_x_explain, get(y_var)] x_explain <- data[ind_x_explain, ..x_var] # Fitting a basic xgboost model to the training data model <- xgboost::xgboost( x = x_train, y = y_train, nround = 20, verbosity = 0 ) # Specifying the phi_0, i.e. the expected prediction without any features phi0 <- mean(y_train) # Independence approach explanation_independence <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "independence", phi0 = phi0, n_MC_samples = 1e2 ) # Gaussian 1e1 approach explanation_gaussian_1e1 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "gaussian", phi0 = phi0, n_MC_samples = 1e1 ) # Gaussian 1e2 approach explanation_gaussian_1e2 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "gaussian", phi0 = phi0, n_MC_samples = 1e2 ) # ctree approach explanation_ctree <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "ctree", phi0 = phi0, n_MC_samples = 1e2 ) # Combined approach explanation_combined <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = c("gaussian", "independence", "ctree"), phi0 = phi0, n_MC_samples = 1e2 ) # Create a list of explanations with names explanation_list_named <- list( "Ind." = explanation_independence, "Gaus. 1e1" = explanation_gaussian_1e1, "Gaus. 1e2" = explanation_gaussian_1e2, "Ctree" = explanation_ctree, "Combined" = explanation_combined ) # Create the default MSEv plot where we average over both the coalitions and observations # with approximate 95% confidence intervals plot_MSEv_eval_crit(explanation_list_named, CI_level = 0.95, plot_type = "overall") # Can also create plots of the MSEv criterion averaged only over the coalitions or observations. MSEv_figures <- plot_MSEv_eval_crit(explanation_list_named, CI_level = 0.95, plot_type = c("overall", "coalition", "explicand") ) MSEv_figures$MSEv_bar MSEv_figures$MSEv_coalition_bar MSEv_figures$MSEv_explicand_bar # When there are many coalitions or observations, then it can be easier to look at line plots MSEv_figures$MSEv_coalition_line_point MSEv_figures$MSEv_explicand_line_point # We can specify which observations or coalitions to plot plot_MSEv_eval_crit(explanation_list_named, plot_type = "explicand", index_x_explain = c(1, 3:4, 6), CI_level = 0.95 )$MSEv_explicand_bar plot_MSEv_eval_crit(explanation_list_named, plot_type = "coalition", id_coalition = c(3, 4, 9, 13:15), CI_level = 0.95 )$MSEv_coalition_bar # We can alter the figures if other palette schemes or design is wanted bar_text_n_decimals <- 1 MSEv_figures$MSEv_bar + ggplot2::scale_x_discrete(limits = rev(levels(MSEv_figures$MSEv_bar$data$Method))) + ggplot2::coord_flip() + ggplot2::scale_fill_discrete() + #' Default ggplot2 palette ggplot2::theme_minimal() + #' This must be set before the other theme call ggplot2::theme( plot.title = ggplot2::element_text(size = 10), legend.position = "bottom" ) + ggplot2::guides(fill = ggplot2::guide_legend(nrow = 1, ncol = 6)) + ggplot2::geom_text( ggplot2::aes(label = sprintf( paste("%.", sprintf("%d", bar_text_n_decimals), "f", sep = ""), round(MSEv, bar_text_n_decimals) )), vjust = -1.1, # This value must be altered based on the plot dimension hjust = 1.1, # This value must be altered based on the plot dimension color = "black", position = ggplot2::position_dodge(0.9), size = 5 ) }
Make plots to visualize and compare the estimated Shapley values for a list of
explain() objects applied to the same data and model. For group-wise Shapley values,
the features values plotted are the mean feature values for all features in each group.
plot_SV_several_approaches( explanation_list, index_explicands = NULL, index_explicands_sort = FALSE, only_these_features = NULL, plot_phi0 = FALSE, digits = 4, print_ggplot = TRUE, add_zero_line = FALSE, axis_labels_n_dodge = NULL, axis_labels_rotate_angle = NULL, horizontal_bars = TRUE, facet_scales = "free", facet_ncol = 2, geom_col_width = 0.85, brewer_palette = NULL, include_group_feature_means = FALSE )plot_SV_several_approaches( explanation_list, index_explicands = NULL, index_explicands_sort = FALSE, only_these_features = NULL, plot_phi0 = FALSE, digits = 4, print_ggplot = TRUE, add_zero_line = FALSE, axis_labels_n_dodge = NULL, axis_labels_rotate_angle = NULL, horizontal_bars = TRUE, facet_scales = "free", facet_ncol = 2, geom_col_width = 0.85, brewer_palette = NULL, include_group_feature_means = FALSE )
explanation_list |
A list of |
index_explicands |
Integer vector. Which of the explicands (test observations) to plot.
E.g. if you have explained 10 observations using |
index_explicands_sort |
Boolean. If |
only_these_features |
String vector. Containing the names of the features which are to be included in the bar plots. |
plot_phi0 |
Boolean. If we are to include the |
digits |
Integer.
Number of significant digits to use in the feature description.
Applicable for |
print_ggplot |
Logical.
Whether to print the created |
add_zero_line |
Boolean. If we are to add a black line for a feature contribution of 0. |
axis_labels_n_dodge |
Integer. The number of rows that should be used to render the labels. This is useful for displaying labels that would otherwise overlap. |
axis_labels_rotate_angle |
Numeric. The angle of the axis label, where 0 means horizontal, 45 means tilted,
and 90 means vertical. Compared to setting the angle in |
horizontal_bars |
Boolean. Flip Cartesian coordinates so that horizontal becomes vertical,
and vertical, horizontal. This is primarily useful for converting geoms and statistics which display
y conditional on x, to x conditional on y. See |
facet_scales |
Should scales be free (" |
facet_ncol |
Integer. The number of columns in the facet grid. Default is |
geom_col_width |
Numeric. Bar width. By default, set to 85% of the |
brewer_palette |
String. Name of one of the color palettes from
|
include_group_feature_means |
Logical. Whether to include the average feature value in a group on the
y-axis or not. If |
A ggplot2::ggplot() object.
Lars Henry Berge Olsen
## Not run: if (requireNamespace("xgboost", quietly = TRUE) && requireNamespace("ggplot2", quietly = TRUE)) { # Get the data data("airquality") data <- data.table::as.data.table(airquality) data <- data[complete.cases(data), ] # Define the features and the response x_var <- c("Solar.R", "Wind", "Temp", "Month") y_var <- "Ozone" # Split data into test and training data set ind_x_explain <- 1:12 x_train <- data[-ind_x_explain, ..x_var] y_train <- data[-ind_x_explain, get(y_var)] x_explain <- data[ind_x_explain, ..x_var] # Fitting a basic xgboost model to the training data model <- xgboost::xgboost( x = x_train, y = y_train, nround = 20, verbosity = 0 ) # Specifying the phi_0, i.e. the expected prediction without any features phi0 <- mean(y_train) # Independence approach explanation_independence <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "independence", phi0 = phi0, n_MC_samples = 1e2 ) # Empirical approach explanation_empirical <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "empirical", phi0 = phi0, n_MC_samples = 1e2 ) # Gaussian 1e1 approach explanation_gaussian_1e1 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "gaussian", phi0 = phi0, n_MC_samples = 1e1 ) # Gaussian 1e2 approach explanation_gaussian_1e2 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "gaussian", phi0 = phi0, n_MC_samples = 1e2 ) # Combined approach explanation_combined <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = c("gaussian", "ctree", "empirical"), phi0 = phi0, n_MC_samples = 1e2 ) # Create a list of explanations with names explanation_list <- list( "Ind." = explanation_independence, "Emp." = explanation_empirical, "Gaus. 1e1" = explanation_gaussian_1e1, "Gaus. 1e2" = explanation_gaussian_1e2, "Combined" = explanation_combined ) # The function uses the provided names. plot_SV_several_approaches(explanation_list) # We can change the number of columns in the grid of plots and add other visual alterations # Set `print_ggplot = FALSE` to avoid force displaying the ggplot object before the modifications # outside plot_SV_several_approaches() plot_SV_several_approaches(explanation_list, facet_ncol = 3, facet_scales = "free_y", add_zero_line = TRUE, digits = 2, brewer_palette = "Paired", geom_col_width = 0.6, print_ggplot = FALSE ) + ggplot2::theme_minimal() + ggplot2::theme(legend.position = "bottom", plot.title = ggplot2::element_text(size = 10)) # We can specify which explicands to plot to get less chaotic plots and make the bars vertical plot_SV_several_approaches(explanation_list, index_explicands = c(1:2, 5, 10), horizontal_bars = FALSE, axis_labels_rotate_angle = 45 ) # We can change the order of the features by specifying the # order using the `only_these_features` parameter. plot_SV_several_approaches(explanation_list, index_explicands = c(1:2, 5, 10), only_these_features = c("Temp", "Solar.R", "Month", "Wind") ) # We can also remove certain features if we are not interested in them # or want to focus on, e.g., two features. The function will give a # message to if the user specifies non-valid feature names. plot_SV_several_approaches(explanation_list, index_explicands = c(1:2, 5, 10), only_these_features = c("Temp", "Solar.R"), plot_phi0 = TRUE ) } ## End(Not run)## Not run: if (requireNamespace("xgboost", quietly = TRUE) && requireNamespace("ggplot2", quietly = TRUE)) { # Get the data data("airquality") data <- data.table::as.data.table(airquality) data <- data[complete.cases(data), ] # Define the features and the response x_var <- c("Solar.R", "Wind", "Temp", "Month") y_var <- "Ozone" # Split data into test and training data set ind_x_explain <- 1:12 x_train <- data[-ind_x_explain, ..x_var] y_train <- data[-ind_x_explain, get(y_var)] x_explain <- data[ind_x_explain, ..x_var] # Fitting a basic xgboost model to the training data model <- xgboost::xgboost( x = x_train, y = y_train, nround = 20, verbosity = 0 ) # Specifying the phi_0, i.e. the expected prediction without any features phi0 <- mean(y_train) # Independence approach explanation_independence <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "independence", phi0 = phi0, n_MC_samples = 1e2 ) # Empirical approach explanation_empirical <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "empirical", phi0 = phi0, n_MC_samples = 1e2 ) # Gaussian 1e1 approach explanation_gaussian_1e1 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "gaussian", phi0 = phi0, n_MC_samples = 1e1 ) # Gaussian 1e2 approach explanation_gaussian_1e2 <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "gaussian", phi0 = phi0, n_MC_samples = 1e2 ) # Combined approach explanation_combined <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = c("gaussian", "ctree", "empirical"), phi0 = phi0, n_MC_samples = 1e2 ) # Create a list of explanations with names explanation_list <- list( "Ind." = explanation_independence, "Emp." = explanation_empirical, "Gaus. 1e1" = explanation_gaussian_1e1, "Gaus. 1e2" = explanation_gaussian_1e2, "Combined" = explanation_combined ) # The function uses the provided names. plot_SV_several_approaches(explanation_list) # We can change the number of columns in the grid of plots and add other visual alterations # Set `print_ggplot = FALSE` to avoid force displaying the ggplot object before the modifications # outside plot_SV_several_approaches() plot_SV_several_approaches(explanation_list, facet_ncol = 3, facet_scales = "free_y", add_zero_line = TRUE, digits = 2, brewer_palette = "Paired", geom_col_width = 0.6, print_ggplot = FALSE ) + ggplot2::theme_minimal() + ggplot2::theme(legend.position = "bottom", plot.title = ggplot2::element_text(size = 10)) # We can specify which explicands to plot to get less chaotic plots and make the bars vertical plot_SV_several_approaches(explanation_list, index_explicands = c(1:2, 5, 10), horizontal_bars = FALSE, axis_labels_rotate_angle = 45 ) # We can change the order of the features by specifying the # order using the `only_these_features` parameter. plot_SV_several_approaches(explanation_list, index_explicands = c(1:2, 5, 10), only_these_features = c("Temp", "Solar.R", "Month", "Wind") ) # We can also remove certain features if we are not interested in them # or want to focus on, e.g., two features. The function will give a # message to if the user specifies non-valid feature names. plot_SV_several_approaches(explanation_list, index_explicands = c(1:2, 5, 10), only_these_features = c("Temp", "Solar.R"), plot_phi0 = TRUE ) } ## End(Not run)
vaeac modelsThis function makes (ggplot2::ggplot()) figures of the training VLB and the validation IWAE for a list
of explain() objects with approach = "vaeac". See setup_approach() for more information about the
vaeac approach. Two figures are returned by the function. In the figure, each object in explanation_list gets
its own facet, while in the second figure, we plot the criteria in each facet for all objects.
plot_vaeac_eval_crit( explanation_list, plot_from_nth_epoch = 1, plot_every_nth_epoch = 1, criteria = c("VLB", "IWAE"), plot_type = c("method", "criterion"), facet_wrap_scales = "fixed", facet_wrap_ncol = NULL )plot_vaeac_eval_crit( explanation_list, plot_from_nth_epoch = 1, plot_every_nth_epoch = 1, criteria = c("VLB", "IWAE"), plot_type = c("method", "criterion"), facet_wrap_scales = "fixed", facet_wrap_ncol = NULL )
explanation_list |
A list of |
plot_from_nth_epoch |
Integer. If we are only plot the results form the nth epoch and so forth. The first epochs can be large in absolute value and make the rest of the plot difficult to interpret. |
plot_every_nth_epoch |
Integer. If we are only to plot every nth epoch. Usefully to illustrate the overall trend, as there can be a lot of fluctuation and oscillation in the values between each epoch. |
criteria |
Character vector. The possible options are "VLB", "IWAE", "IWAE_running". Default is the first two. |
plot_type |
Character vector. The possible options are "method" and "criterion". Default is to plot both. |
facet_wrap_scales |
String. Should the scales be fixed (" |
facet_wrap_ncol |
Integer. Number of columns in the facet wrap. |
See Olsen et al. (2022) or the blog post for a summary of the VLB and IWAE.
Either a single ggplot2::ggplot() object or a list of ggplot2::ggplot() objects based on the
plot_type parameter.
Lars Henry Berge Olsen
if (requireNamespace("xgboost", quietly = TRUE) && requireNamespace("torch", quietly = TRUE) && torch::torch_is_installed()) { data("airquality") data <- data.table::as.data.table(airquality) data <- data[complete.cases(data), ] x_var <- c("Solar.R", "Wind", "Temp", "Month") y_var <- "Ozone" ind_x_explain <- 1:6 x_train <- data[-ind_x_explain, ..x_var] y_train <- data[-ind_x_explain, get(y_var)] x_explain <- data[ind_x_explain, ..x_var] # Fitting a basic xgboost model to the training data model <- xgboost::xgboost( x = x_train, y = y_train, nround = 100, verbosity = 0 ) # Specifying the phi_0, i.e. the expected prediction without any features p0 <- mean(y_train) # Train vaeac with and without paired sampling explanation_paired <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "vaeac", phi0 = p0, n_MC_samples = 1, # As we are only interested in the training of the vaeac vaeac.epochs = 10, # Should be higher in applications. vaeac.n_vaeacs_initialize = 1, vaeac.width = 16, vaeac.depth = 2, vaeac.extra_parameters = list(vaeac.paired_sampling = TRUE) ) explanation_regular <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "vaeac", phi0 = p0, n_MC_samples = 1, # As we are only interested in the training of the vaeac vaeac.epochs = 10, # Should be higher in applications. vaeac.width = 16, vaeac.depth = 2, vaeac.n_vaeacs_initialize = 1, vaeac.extra_parameters = list(vaeac.paired_sampling = FALSE) ) # Collect the explanation objects in an named list explanation_list <- list( "Regular sampling" = explanation_regular, "Paired sampling" = explanation_paired ) # Call the function with the named list, will use the provided names plot_vaeac_eval_crit(explanation_list = explanation_list) # The function also works if we have only one method, # but then one should only look at the method plot. plot_vaeac_eval_crit( explanation_list = explanation_list[2], plot_type = "method" ) # Can alter the plot plot_vaeac_eval_crit( explanation_list = explanation_list, plot_from_nth_epoch = 2, plot_every_nth_epoch = 2, facet_wrap_scales = "free" ) # If we only want the VLB plot_vaeac_eval_crit( explanation_list = explanation_list, criteria = "VLB", plot_type = "criterion" ) # If we want only want the criterion version tmp_fig_criterion <- plot_vaeac_eval_crit(explanation_list = explanation_list, plot_type = "criterion") # Since tmp_fig_criterion is a ggplot2 object, we can alter it # by, e.g,. adding points or smooths with se bands tmp_fig_criterion + ggplot2::geom_point(shape = "circle", size = 1, ggplot2::aes(col = Method)) tmp_fig_criterion$layers[[1]] <- NULL tmp_fig_criterion + ggplot2::geom_smooth(method = "loess", formula = y ~ x, se = TRUE) + ggplot2::scale_color_brewer(palette = "Set1") + ggplot2::theme_minimal() }if (requireNamespace("xgboost", quietly = TRUE) && requireNamespace("torch", quietly = TRUE) && torch::torch_is_installed()) { data("airquality") data <- data.table::as.data.table(airquality) data <- data[complete.cases(data), ] x_var <- c("Solar.R", "Wind", "Temp", "Month") y_var <- "Ozone" ind_x_explain <- 1:6 x_train <- data[-ind_x_explain, ..x_var] y_train <- data[-ind_x_explain, get(y_var)] x_explain <- data[ind_x_explain, ..x_var] # Fitting a basic xgboost model to the training data model <- xgboost::xgboost( x = x_train, y = y_train, nround = 100, verbosity = 0 ) # Specifying the phi_0, i.e. the expected prediction without any features p0 <- mean(y_train) # Train vaeac with and without paired sampling explanation_paired <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "vaeac", phi0 = p0, n_MC_samples = 1, # As we are only interested in the training of the vaeac vaeac.epochs = 10, # Should be higher in applications. vaeac.n_vaeacs_initialize = 1, vaeac.width = 16, vaeac.depth = 2, vaeac.extra_parameters = list(vaeac.paired_sampling = TRUE) ) explanation_regular <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "vaeac", phi0 = p0, n_MC_samples = 1, # As we are only interested in the training of the vaeac vaeac.epochs = 10, # Should be higher in applications. vaeac.width = 16, vaeac.depth = 2, vaeac.n_vaeacs_initialize = 1, vaeac.extra_parameters = list(vaeac.paired_sampling = FALSE) ) # Collect the explanation objects in an named list explanation_list <- list( "Regular sampling" = explanation_regular, "Paired sampling" = explanation_paired ) # Call the function with the named list, will use the provided names plot_vaeac_eval_crit(explanation_list = explanation_list) # The function also works if we have only one method, # but then one should only look at the method plot. plot_vaeac_eval_crit( explanation_list = explanation_list[2], plot_type = "method" ) # Can alter the plot plot_vaeac_eval_crit( explanation_list = explanation_list, plot_from_nth_epoch = 2, plot_every_nth_epoch = 2, facet_wrap_scales = "free" ) # If we only want the VLB plot_vaeac_eval_crit( explanation_list = explanation_list, criteria = "VLB", plot_type = "criterion" ) # If we want only want the criterion version tmp_fig_criterion <- plot_vaeac_eval_crit(explanation_list = explanation_list, plot_type = "criterion") # Since tmp_fig_criterion is a ggplot2 object, we can alter it # by, e.g,. adding points or smooths with se bands tmp_fig_criterion + ggplot2::geom_point(shape = "circle", size = 1, ggplot2::aes(col = Method)) tmp_fig_criterion$layers[[1]] <- NULL tmp_fig_criterion + ggplot2::geom_smooth(method = "loess", formula = y ~ x, se = TRUE) + ggplot2::scale_color_brewer(palette = "Set1") + ggplot2::theme_minimal() }
A function that creates a matrix of plots (GGally::ggpairs()) from
generated imputations from the unconditioned distribution estimated by
a vaeac model, and then compares the imputed values with data from the true distribution (if provided).
See ggpairs for an
introduction to GGally::ggpairs(), and the corresponding
vignette.
plot_vaeac_imputed_ggpairs( explanation, which_vaeac_model = "best", x_true = NULL, add_title = TRUE, alpha = 0.5, upper_cont = c("cor", "points", "smooth", "smooth_loess", "density", "blank"), upper_cat = c("count", "cross", "ratio", "facetbar", "blank"), upper_mix = c("box", "box_no_facet", "dot", "dot_no_facet", "facethist", "facetdensity", "denstrip", "blank"), lower_cont = c("points", "smooth", "smooth_loess", "density", "cor", "blank"), lower_cat = c("facetbar", "ratio", "count", "cross", "blank"), lower_mix = c("facetdensity", "box", "box_no_facet", "dot", "dot_no_facet", "facethist", "denstrip", "blank"), diag_cont = c("densityDiag", "barDiag", "blankDiag"), diag_cat = c("barDiag", "blankDiag"), cor_method = c("pearson", "kendall", "spearman") )plot_vaeac_imputed_ggpairs( explanation, which_vaeac_model = "best", x_true = NULL, add_title = TRUE, alpha = 0.5, upper_cont = c("cor", "points", "smooth", "smooth_loess", "density", "blank"), upper_cat = c("count", "cross", "ratio", "facetbar", "blank"), upper_mix = c("box", "box_no_facet", "dot", "dot_no_facet", "facethist", "facetdensity", "denstrip", "blank"), lower_cont = c("points", "smooth", "smooth_loess", "density", "cor", "blank"), lower_cat = c("facetbar", "ratio", "count", "cross", "blank"), lower_mix = c("facetdensity", "box", "box_no_facet", "dot", "dot_no_facet", "facethist", "denstrip", "blank"), diag_cont = c("densityDiag", "barDiag", "blankDiag"), diag_cat = c("barDiag", "blankDiag"), cor_method = c("pearson", "kendall", "spearman") )
explanation |
Shapr list. The output list from the |
which_vaeac_model |
String. Indicating which |
x_true |
Data.table containing the data from the distribution that the |
add_title |
Logical. If |
alpha |
Numeric between |
upper_cont |
String. Type of plot to use in upper triangle for continuous features, see |
upper_cat |
String. Type of plot to use in upper triangle for categorical features, see |
upper_mix |
String. Type of plot to use in upper triangle for mixed features, see |
lower_cont |
String. Type of plot to use in lower triangle for continuous features, see |
lower_cat |
String. Type of plot to use in lower triangle for categorical features, see |
lower_mix |
String. Type of plot to use in lower triangle for mixed features, see |
diag_cont |
String. Type of plot to use on the diagonal for continuous features, see |
diag_cat |
String. Type of plot to use on the diagonal for categorical features, see |
cor_method |
String. Type of correlation measure, see |
A GGally::ggpairs() figure.
Lars Henry Berge Olsen
if (requireNamespace("xgboost", quietly = TRUE) && requireNamespace("ggplot2", quietly = TRUE) && requireNamespace("torch", quietly = TRUE) && torch::torch_is_installed()) { data("airquality") data <- data.table::as.data.table(airquality) data <- data[complete.cases(data), ] x_var <- c("Solar.R", "Wind", "Temp", "Month") y_var <- "Ozone" ind_x_explain <- 1:6 x_train <- data[-ind_x_explain, ..x_var] y_train <- data[-ind_x_explain, get(y_var)] x_explain <- data[ind_x_explain, ..x_var] # Fitting a basic xgboost model to the training data model <- xgboost::xgboost( x = x_train, y = y_train, nround = 100, verbosity = 0 ) explanation <- shapr::explain( model = model, x_explain = x_explain, x_train = x_train, approach = "vaeac", phi0 = mean(y_train), n_MC_samples = 1, vaeac.epochs = 10, vaeac.n_vaeacs_initialize = 1 ) # Plot the results figure <- shapr::plot_vaeac_imputed_ggpairs( explanation = explanation, which_vaeac_model = "best", x_true = x_train, add_title = TRUE ) figure # Note that this is an ggplot2 object which we can alter, e.g., we can change the colors. figure + ggplot2::scale_color_manual(values = c("#E69F00", "#999999")) + ggplot2::scale_fill_manual(values = c("#E69F00", "#999999")) }if (requireNamespace("xgboost", quietly = TRUE) && requireNamespace("ggplot2", quietly = TRUE) && requireNamespace("torch", quietly = TRUE) && torch::torch_is_installed()) { data("airquality") data <- data.table::as.data.table(airquality) data <- data[complete.cases(data), ] x_var <- c("Solar.R", "Wind", "Temp", "Month") y_var <- "Ozone" ind_x_explain <- 1:6 x_train <- data[-ind_x_explain, ..x_var] y_train <- data[-ind_x_explain, get(y_var)] x_explain <- data[ind_x_explain, ..x_var] # Fitting a basic xgboost model to the training data model <- xgboost::xgboost( x = x_train, y = y_train, nround = 100, verbosity = 0 ) explanation <- shapr::explain( model = model, x_explain = x_explain, x_train = x_train, approach = "vaeac", phi0 = mean(y_train), n_MC_samples = 1, vaeac.epochs = 10, vaeac.n_vaeacs_initialize = 1 ) # Plot the results figure <- shapr::plot_vaeac_imputed_ggpairs( explanation = explanation, which_vaeac_model = "best", x_true = x_train, add_title = TRUE ) figure # Note that this is an ggplot2 object which we can alter, e.g., we can change the colors. figure + ggplot2::scale_color_manual(values = c("#E69F00", "#999999")) + ggplot2::scale_fill_manual(values = c("#E69F00", "#999999")) }
Plots the individual prediction explanations.
## S3 method for class 'shapr' plot( x, plot_type = "bar", digits = 3, print_ggplot = TRUE, index_x_explain = NULL, top_k_features = NULL, col = NULL, bar_plot_phi0 = TRUE, bar_plot_order = "largest_first", scatter_features = NULL, scatter_hist = TRUE, include_group_feature_means = FALSE, beeswarm_cex = 1/length(index_x_explain)^(1/4), ... )## S3 method for class 'shapr' plot( x, plot_type = "bar", digits = 3, print_ggplot = TRUE, index_x_explain = NULL, top_k_features = NULL, col = NULL, bar_plot_phi0 = TRUE, bar_plot_order = "largest_first", scatter_features = NULL, scatter_hist = TRUE, include_group_feature_means = FALSE, beeswarm_cex = 1/length(index_x_explain)^(1/4), ... )
x |
An |
plot_type |
Character.
Specifies the type of plot to produce.
|
digits |
Integer.
Number of significant digits to use in the feature description.
Applicable for |
print_ggplot |
Logical.
Whether to print the created |
index_x_explain |
Integer vector.
Which of the test observations to plot. For example, if you have
explained 10 observations using |
top_k_features |
Integer.
How many features to include in the plot.
E.g. if you have 15 features in your model you can plot the 5 most important features,
for each explanation, by setting |
col |
Character vector (where length depends on plot type).
The color codes (hex codes or other names understood by If you want to alter the colors in the plot, the length of the |
bar_plot_phi0 |
Logical.
Whether to include |
bar_plot_order |
Character.
Specifies what order to plot the features with respect to the magnitude of the Shapley values with
|
scatter_features |
Integer or character vector.
Only used for |
scatter_hist |
Logical.
Only used for |
include_group_feature_means |
Logical.
Whether to include the average feature value in a group on the y-axis or not.
If |
beeswarm_cex |
Numeric.
The cex argument of |
... |
Other arguments passed to underlying functions,
like |
See the examples below, or vignette("general_usage", package = "shapr") for examples of
how to use the function.
ggplot object with plots of the Shapley value explanations
Martin Jullum, Vilde Ung, Lars Henry Berge Olsen
if (requireNamespace("party", quietly = TRUE)) { data("airquality") airquality <- airquality[complete.cases(airquality), ] x_var <- c("Solar.R", "Wind", "Temp", "Month") y_var <- "Ozone" # Split data into test- and training data data_train <- head(airquality, -50) data_explain <- tail(airquality, 50) x_train <- data_train[, x_var] x_explain <- data_explain[, x_var] # Fit a linear model lm_formula <- as.formula(paste0(y_var, " ~ ", paste0(x_var, collapse = " + "))) model <- lm(lm_formula, data = data_train) # Explain predictions p <- mean(data_train[, y_var]) # Empirical approach x <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "empirical", phi0 = p, n_MC_samples = 1e2 ) if (requireNamespace(c("ggplot2", "ggbeeswarm"), quietly = TRUE)) { # The default plotting option is a bar plot of the Shapley values # We draw bar plots for the first 4 observations plot(x, index_x_explain = 1:4) # We can also make waterfall plots plot(x, plot_type = "waterfall", index_x_explain = 1:4) # And only showing the two features with the largest contributions plot(x, plot_type = "waterfall", index_x_explain = 1:4, top_k_features = 2) # Or scatter plots showing the distribution of the Shapley values and feature values plot(x, plot_type = "scatter") # And only for a specific feature plot(x, plot_type = "scatter", scatter_features = "Temp") # Or a beeswarm plot summarising the Shapley values and feature values for all features plot(x, plot_type = "beeswarm") plot(x, plot_type = "beeswarm", col = c("red", "black")) # we can change colors # Additional arguments can be passed to ggbeeswarm::geom_beeswarm() using the '...' argument. # For instance, sometimes the beeswarm plots overlap too much. # This can be fixed with the 'corral="wrap" argument. # See ?ggbeeswarm::geom_beeswarm for more information. plot(x, plot_type = "beeswarm", corral = "wrap") } # Example of scatter and beeswarm plot with factor variables airquality$Month_factor <- as.factor(month.abb[airquality$Month]) airquality <- airquality[complete.cases(airquality), ] x_var <- c("Solar.R", "Wind", "Temp", "Month_factor") y_var <- "Ozone" # Split data into test- and training data data_train <- airquality data_explain <- tail(airquality, 50) x_train <- data_train[, x_var] x_explain <- data_explain[, x_var] # Fit a linear model lm_formula <- as.formula(paste0(y_var, " ~ ", paste0(x_var, collapse = " + "))) model <- lm(lm_formula, data = data_train) # Explain predictions p <- mean(data_train[, y_var]) # Empirical approach x <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "ctree", phi0 = p, n_MC_samples = 1e2 ) if (requireNamespace(c("ggplot2", "ggbeeswarm"), quietly = TRUE)) { plot(x, plot_type = "scatter") plot(x, plot_type = "beeswarm") } # Example of further modification of the output from plot.shapr plt <- plot(x, index_x_explain = 1:4, print_ggplot = FALSE) # Storing without printing # Displays the modified ggplot object plt + ggplot2::ggtitle("My custom title") + ggplot2::ylab("Variable influence") + ggplot2::xlab("Variable") }if (requireNamespace("party", quietly = TRUE)) { data("airquality") airquality <- airquality[complete.cases(airquality), ] x_var <- c("Solar.R", "Wind", "Temp", "Month") y_var <- "Ozone" # Split data into test- and training data data_train <- head(airquality, -50) data_explain <- tail(airquality, 50) x_train <- data_train[, x_var] x_explain <- data_explain[, x_var] # Fit a linear model lm_formula <- as.formula(paste0(y_var, " ~ ", paste0(x_var, collapse = " + "))) model <- lm(lm_formula, data = data_train) # Explain predictions p <- mean(data_train[, y_var]) # Empirical approach x <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "empirical", phi0 = p, n_MC_samples = 1e2 ) if (requireNamespace(c("ggplot2", "ggbeeswarm"), quietly = TRUE)) { # The default plotting option is a bar plot of the Shapley values # We draw bar plots for the first 4 observations plot(x, index_x_explain = 1:4) # We can also make waterfall plots plot(x, plot_type = "waterfall", index_x_explain = 1:4) # And only showing the two features with the largest contributions plot(x, plot_type = "waterfall", index_x_explain = 1:4, top_k_features = 2) # Or scatter plots showing the distribution of the Shapley values and feature values plot(x, plot_type = "scatter") # And only for a specific feature plot(x, plot_type = "scatter", scatter_features = "Temp") # Or a beeswarm plot summarising the Shapley values and feature values for all features plot(x, plot_type = "beeswarm") plot(x, plot_type = "beeswarm", col = c("red", "black")) # we can change colors # Additional arguments can be passed to ggbeeswarm::geom_beeswarm() using the '...' argument. # For instance, sometimes the beeswarm plots overlap too much. # This can be fixed with the 'corral="wrap" argument. # See ?ggbeeswarm::geom_beeswarm for more information. plot(x, plot_type = "beeswarm", corral = "wrap") } # Example of scatter and beeswarm plot with factor variables airquality$Month_factor <- as.factor(month.abb[airquality$Month]) airquality <- airquality[complete.cases(airquality), ] x_var <- c("Solar.R", "Wind", "Temp", "Month_factor") y_var <- "Ozone" # Split data into test- and training data data_train <- airquality data_explain <- tail(airquality, 50) x_train <- data_train[, x_var] x_explain <- data_explain[, x_var] # Fit a linear model lm_formula <- as.formula(paste0(y_var, " ~ ", paste0(x_var, collapse = " + "))) model <- lm(lm_formula, data = data_train) # Explain predictions p <- mean(data_train[, y_var]) # Empirical approach x <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "ctree", phi0 = p, n_MC_samples = 1e2 ) if (requireNamespace(c("ggplot2", "ggbeeswarm"), quietly = TRUE)) { plot(x, plot_type = "scatter") plot(x, plot_type = "beeswarm") } # Example of further modification of the output from plot.shapr plt <- plot(x, index_x_explain = 1:4, print_ggplot = FALSE) # Storing without printing # Displays the modified ggplot object plt + ggplot2::ggtitle("My custom title") + ggplot2::ylab("Variable influence") + ggplot2::xlab("Variable") }
Print Method for Shapr Objects
## S3 method for class 'shapr' print( x, what = c("shapley_est", "shapley_sd", "MSEv", "MSEv_explicand", "MSEv_coalition", "timing_summary"), digits = 3L, ... )## S3 method for class 'shapr' print( x, what = c("shapley_est", "shapley_sd", "MSEv", "MSEv_explicand", "MSEv_coalition", "timing_summary"), digits = 3L, ... )
x |
A shapr object |
what |
Character. Which component to print.
Options are "shapley_est", "shapley_sd", "MSEv", "MSEv_explicand", "MSEv_coalition", and "timing_summary".
Defaults to "shapley_est".
Only one component can be printed at a time.
See the details section of |
digits |
Integer. Number of significant digits to display. Defaults to 3. |
... |
Further arguments passed to |
The object is returned invisibly after printing selected output.
Print Method for summary.shapr Objects
## S3 method for class 'summary.shapr' print(x, ...)## S3 method for class 'summary.shapr' print(x, ...)
x |
A summary.shapr object. |
... |
Currently unused. |
Invisibly returns the summary object.
Provides a formatted summary of a shapr object and returns an object of class
summary.shapr containing the same information as returned by get_results().
## S3 method for class 'shapr' summary(object, digits = 2L, ...)## S3 method for class 'shapr' summary(object, digits = 2L, ...)
object |
A shapr object. |
digits |
Integer. (Maximum) number of digits to be displayed after the decimal point. Defaults to 2. |
... |
Currently unused. |
An object of class summary.shapr, which is a named list
with the same accessible components as returned by get_results().
See get_results() for details about each component.
# Load example data data("airquality") airquality <- airquality[complete.cases(airquality), ] x_var <- c("Solar.R", "Wind", "Temp", "Month") y_var <- "Ozone" # Split data into test and training data data_train <- head(airquality, -3) data_explain <- tail(airquality, 3) x_train <- data_train[, x_var] x_explain <- data_explain[, x_var] # Fit a linear model lm_formula <- as.formula(paste0(y_var, " ~ ", paste0(x_var, collapse = " + "))) model <- lm(lm_formula, data = data_train) # Explain predictions p <- mean(data_train[, y_var]) explanation <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "gaussian", phi0 = p, n_MC_samples = 1e2 ) # Call summary without assignment - prints formatted output to console summary(explanation) # Assign to variable - returns shapr.summary with summary information for later use expl_summary <- summary(explanation) # print(expl_summary) provides the formatted output # Access components from the summary object expl_summary$shapley_est # Estimated Shapley values expl_summary$timing_summary$total_time_secs # Total computation time expl_summary$approach # Approach used# Load example data data("airquality") airquality <- airquality[complete.cases(airquality), ] x_var <- c("Solar.R", "Wind", "Temp", "Month") y_var <- "Ozone" # Split data into test and training data data_train <- head(airquality, -3) data_explain <- tail(airquality, 3) x_train <- data_train[, x_var] x_explain <- data_explain[, x_var] # Fit a linear model lm_formula <- as.formula(paste0(y_var, " ~ ", paste0(x_var, collapse = " + "))) model <- lm(lm_formula, data = data_train) # Explain predictions p <- mean(data_train[, y_var]) explanation <- explain( model = model, x_explain = x_explain, x_train = x_train, approach = "gaussian", phi0 = p, n_MC_samples = 1e2 ) # Call summary without assignment - prints formatted output to console summary(explanation) # Assign to variable - returns shapr.summary with summary information for later use expl_summary <- summary(explanation) # print(expl_summary) provides the formatted output # Access components from the summary object expl_summary$shapley_est # Estimated Shapley values expl_summary$timing_summary$total_time_secs # Total computation time expl_summary$approach # Approach used
vaeac ModelIn this function, we specify the default values for the extra parameters used in explain()
for approach = "vaeac".
vaeac_get_extra_para_default( vaeac.model_description = make.names(Sys.time()), vaeac.folder_to_save_model = tempdir(), vaeac.pretrained_vaeac_model = NULL, vaeac.cuda = FALSE, vaeac.epochs_initiation_phase = 2, vaeac.epochs_early_stopping = NULL, vaeac.save_every_nth_epoch = NULL, vaeac.val_ratio = 0.25, vaeac.val_iwae_n_samples = 25, vaeac.batch_size = 64, vaeac.batch_size_sampling = NULL, vaeac.running_avg_n_values = 5, vaeac.skip_conn_layer = TRUE, vaeac.skip_conn_masked_enc_dec = TRUE, vaeac.batch_normalization = FALSE, vaeac.paired_sampling = TRUE, vaeac.masking_ratio = 0.5, vaeac.mask_gen_coalitions = NULL, vaeac.mask_gen_coalitions_prob = NULL, vaeac.sigma_mu = 10000, vaeac.sigma_sigma = 1e-04, vaeac.sample_random = TRUE, vaeac.save_data = FALSE, vaeac.log_exp_cont_feat = FALSE, vaeac.which_vaeac_model = "best", vaeac.save_model = TRUE )vaeac_get_extra_para_default( vaeac.model_description = make.names(Sys.time()), vaeac.folder_to_save_model = tempdir(), vaeac.pretrained_vaeac_model = NULL, vaeac.cuda = FALSE, vaeac.epochs_initiation_phase = 2, vaeac.epochs_early_stopping = NULL, vaeac.save_every_nth_epoch = NULL, vaeac.val_ratio = 0.25, vaeac.val_iwae_n_samples = 25, vaeac.batch_size = 64, vaeac.batch_size_sampling = NULL, vaeac.running_avg_n_values = 5, vaeac.skip_conn_layer = TRUE, vaeac.skip_conn_masked_enc_dec = TRUE, vaeac.batch_normalization = FALSE, vaeac.paired_sampling = TRUE, vaeac.masking_ratio = 0.5, vaeac.mask_gen_coalitions = NULL, vaeac.mask_gen_coalitions_prob = NULL, vaeac.sigma_mu = 10000, vaeac.sigma_sigma = 1e-04, vaeac.sample_random = TRUE, vaeac.save_data = FALSE, vaeac.log_exp_cont_feat = FALSE, vaeac.which_vaeac_model = "best", vaeac.save_model = TRUE )
vaeac.model_description |
String (default is |
vaeac.folder_to_save_model |
String (default is |
vaeac.pretrained_vaeac_model |
List or String (default is |
vaeac.cuda |
Logical (default is |
vaeac.epochs_initiation_phase |
Positive integer (default is |
vaeac.epochs_early_stopping |
Positive integer (default is |
vaeac.save_every_nth_epoch |
Positive integer (default is |
vaeac.val_ratio |
Numeric (default is |
vaeac.val_iwae_n_samples |
Positive integer (default is |
vaeac.batch_size |
Positive integer (default is |
vaeac.batch_size_sampling |
Positive integer (default is |
vaeac.running_avg_n_values |
Positive integer (default is |
vaeac.skip_conn_layer |
Logical (default is |
vaeac.skip_conn_masked_enc_dec |
Logical (default is |
vaeac.batch_normalization |
Logical (default is |
vaeac.paired_sampling |
Logical (default is |
vaeac.masking_ratio |
Numeric (default is |
vaeac.mask_gen_coalitions |
Matrix (default is |
vaeac.mask_gen_coalitions_prob |
Numeric array (default is |
vaeac.sigma_mu |
Numeric (default is |
vaeac.sigma_sigma |
Numeric (default is |
vaeac.sample_random |
Logical (default is |
vaeac.save_data |
Logical (default is |
vaeac.log_exp_cont_feat |
Logical (default is |
vaeac.which_vaeac_model |
String (default is |
vaeac.save_model |
Boolean. If |
The vaeac model consists of three neural network (a full encoder, a masked encoder, and a decoder) based
on the provided vaeac.depth and vaeac.width. The encoders map the full and masked input
representations to latent representations, respectively, where the dimension is given by vaeac.latent_dim.
The latent representations are sent to the decoder to go back to the real feature space and
provide a samplable probabilistic representation, from which the Monte Carlo samples are generated.
We use the vaeac method at the epoch with the lowest validation error (IWAE) by default, but
other possibilities are available by setting the vaeac.which_vaeac_model parameter. See
Olsen et al. (2022) for more details.
Named list of the default values vaeac extra parameter arguments specified in this function call.
Note that both vaeac.model_description and vaeac.folder_to_save_model will change with time and R session.
Lars Henry Berge Olsen
vaeac ModelFunction that loads a previously trained vaeac model and continue the training, either on new data or on the same dataset as it was trained on before. If we are given a new dataset, then we assume that new dataset has the same distribution and one_hot_max_sizes as the original dataset.
vaeac_train_model_continue( explanation, epochs_new, lr_new = NULL, x_train = NULL, save_data = FALSE, verbose = NULL, seed = 1 )vaeac_train_model_continue( explanation, epochs_new, lr_new = NULL, x_train = NULL, save_data = FALSE, verbose = NULL, seed = 1 )
explanation |
A |
epochs_new |
Positive integer. The number of extra epochs to conduct. |
lr_new |
Positive numeric. If we are to overwrite the old learning rate in the adam optimizer. |
x_train |
A data.table containing the training data. Categorical data must have class names |
save_data |
Logical (default is |
verbose |
String vector or NULL.
Controls verbosity (printout detail level) via one or more of |
seed |
Positive integer (default is |
A list containing the training/validation errors and paths to where the vaeac models are saved on the disk.
Lars Henry Berge Olsen