List. Not used directly, but passed through from explain().

numeric specifying the scaling (sigma)

List. Contains matrices with the appropriate features of the training data

List. Contains the covariance matrices of the matrices in X_list

Logical. Indicates whether Mahalanobis distance should be scaled with the number of variables.

List. Contains the appropriate (temporary) response variables.

Logical. Whether to return the negative of the AICc value.

matrix.

matrix The covariance matrix of X.

logical. Indicating whether the Mahalanobis distance should be scaled with the number of variables

numeric specifying the scaling (sigma)

Vector Representing the (temporary) response variable

List Output from compute_vS()

List. Not used directly, but passed through from explain().

A torch tensor of dimension n_features containing the one hot sizes of the n_features features. That is, if the ith feature is a categorical feature with 5 levels, then one_hot_max_sizes[i] = 5. While the size for continuous features can either be 0 or 1.

Optional list which contains indices of columns which is_nan masks are to be appended to the result tensor. This option is necessary for the full encoder to distinguish whether value is to be reconstructed or not.

Data.table containing the generated MC samples (and conditional values) after each sampling step

Positive integer. For most approaches, it indicates the maximum number of samples to use in the Monte Carlo integration of every conditional expectation. For approach="ctree", n_MC_samples corresponds to the number of samples from the leaf node (see an exception related to the ctree.sample argument setup_approach.ctree()). For approach="empirical", n_MC_samples is the K parameter in equations (14-15) of Aas et al. (2021), i.e. the maximum number of observations (with largest weights) that is used, see also the empirical.eta argument setup_approach.empirical().

List. Not used directly, but passed through from explain().

String vector or NULL. Specifies the verbosity (printout detail level) through one or more of strings "basic", "progress", "convergence", "shapley" and "vS_details". "basic" (default) displays basic information about the computation which is being performed, in addition to some messages about parameters being sets or checks being unavailable due to specific input. ⁠"progress⁠ displays information about where in the calculation process the function currently is. #' "convergence" displays information on how close to convergence the Shapley value estimates are (only when iterative = TRUE) . "shapley" displays intermediate Shapley value estimates and standard deviations (only when iterative = TRUE) and the final estimates. "vS_details" displays information about the v_S estimates. This is most relevant for ⁠approach %in% c("regression_separate", "regression_surrogate", "vaeac"⁠). NULL means no printout. Note that any combination of four strings can be used. E.g. verbose = c("basic", "vS_details") will display basic information + details about the v(S)-estimation process.

List. Not used directly, but passed through from explain().

String vector or NULL. Specifies the verbosity (printout detail level) through one or more of strings "basic", "progress", "convergence", "shapley" and "vS_details". "basic" (default) displays basic information about the computation which is being performed, in addition to some messages about parameters being sets or checks being unavailable due to specific input. ⁠"progress⁠ displays information about where in the calculation process the function currently is. #' "convergence" displays information on how close to convergence the Shapley value estimates are (only when iterative = TRUE) . "shapley" displays intermediate Shapley value estimates and standard deviations (only when iterative = TRUE) and the final estimates. "vS_details" displays information about the v_S estimates. This is most relevant for ⁠approach %in% c("regression_separate", "regression_surrogate", "vaeac"⁠). NULL means no printout. Note that any combination of four strings can be used. E.g. verbose = c("basic", "vS_details") will display basic information + details about the v(S)-estimation process.

List. Not used directly, but passed through from explain().

Integer. The iteration number. Only used internally.

List. Not used directly, but passed through from explain().

String. Class of the model as a string

String vector or NULL. Specifies the verbosity (printout detail level) through one or more of strings "basic", "progress", "convergence", "shapley" and "vS_details". "basic" (default) displays basic information about the computation which is being performed, in addition to some messages about parameters being sets or checks being unavailable due to specific input. ⁠"progress⁠ displays information about where in the calculation process the function currently is. #' "convergence" displays information on how close to convergence the Shapley value estimates are (only when iterative = TRUE) . "shapley" displays intermediate Shapley value estimates and standard deviations (only when iterative = TRUE) and the final estimates. "vS_details" displays information about the v_S estimates. This is most relevant for ⁠approach %in% c("regression_separate", "regression_surrogate", "vaeac"⁠). NULL means no printout. Note that any combination of four strings can be used. E.g. verbose = c("basic", "vS_details") will display basic information + details about the v(S)-estimation process.

String vector or NULL. Specifies the verbosity (printout detail level) through one or more of strings "basic", "progress", "convergence", "shapley" and "vS_details". "basic" (default) displays basic information about the computation which is being performed, in addition to some messages about parameters being sets or checks being unavailable due to specific input. ⁠"progress⁠ displays information about where in the calculation process the function currently is. #' "convergence" displays information on how close to convergence the Shapley value estimates are (only when iterative = TRUE) . "shapley" displays intermediate Shapley value estimates and standard deviations (only when iterative = TRUE) and the final estimates. "vS_details" displays information about the v_S estimates. This is most relevant for ⁠approach %in% c("regression_separate", "regression_surrogate", "vaeac"⁠). NULL means no printout. Note that any combination of four strings can be used. E.g. verbose = c("basic", "vS_details") will display basic information + details about the v(S)-estimation process.

Logical. Only use to remove random components like timing from the object output when comparing output with testthat. Defaults to FALSE.

POSIXct object. The time when the explain() function was called, as outputted by Sys.time(). Used to calculate the time it took to run the full explain call.

Character. Either "regular" or "forecast" corresponding to function setup() is called from, correspondingly the type of explanation that should be generated.

Logical. Indicates whether the function is called from the Python wrapper. Default is FALSE which is never changed when calling the function via explain() in R. The parameter is later used to disallow running the AICc-versions of the empirical method as that requires data based optimization, which is not supported in shaprpy.

List. Each of the elements equals an integer vector representing a valid combination of features/feature groups.

Integer. Number of features/feature groups.

List. Holds all parameters, data, functions and computed objects used within explain() The list contains one or more of the elements parameters, data, objects, iter_list, timing_list, main_timing_list, output, and iter_timing_list.

Data.table of dimension n_coalitions times n_explain + 1 containing the contribution function estimates. The first column is assumed to be named id_coalition and containing the ids of the coalitions. The last row is assumed to be the full coalition, i.e., it contains the predicted responses for the observations which are to be explained.

Logical. If TRUE (default), then the function weights the coalitions uniformly when computing the MSEv criterion. If FALSE, then the function use the Shapley kernel weights to weight the coalitions when computing the MSEv criterion. Note that the Shapley kernel weights are replaced by the sampling frequency when not all coalitions are considered.

Logical. If TRUE (default), we exclude the empty and grand coalitions when computing the MSEv evaluation criterion. This is reasonable as they are identical for all methods, i.e., their contribution function is independent of the used method as they are special cases not effected by the used method. If FALSE, we include the empty and grand coalitions. In this situation, we also recommend setting MSEv_uniform_comb_weights = TRUE, as otherwise the large weights for the empty and grand coalitions will outweigh all other coalitions and make the MSEv criterion uninformative.

List. Not used directly, but passed through from explain().

List Output from compute_vS()

List. Holds all parameters, data, functions and computed objects used within explain() The list contains one or more of the elements parameters, data, objects, iter_list, timing_list, main_timing_list, output, and iter_timing_list.

The contribution matrix.

List. Not used directly, but passed through from explain().

List. Not used directly, but passed through from explain().

List. Not applicable for (regular) non-causal or asymmetric explanations. causal_ordering is an unnamed list of vectors specifying the components of the partial causal ordering that the coalitions must respect. Each vector represents a component and contains one or more features/groups identified by their names (strings) or indices (integers). If causal_ordering is NULL (default), no causal ordering is assumed and all possible coalitions are allowed. No causal ordering is equivalent to a causal ordering with a single component that includes all features (list(1:n_features)) or groups (list(1:n_groups)) for feature-wise and group-wise Shapley values, respectively. For feature-wise Shapley values and causal_ordering = list(c(1, 2), c(3, 4)), the interpretation is that features 1 and 2 are the ancestors of features 3 and 4, while features 3 and 4 are on the same level. Note: All features/groups must be included in the causal_ordering without any duplicates.

Vector of strings containing (the order of) the feature names.

String that is either "feature" or "group" based on if shapr is computing feature- or group-wise Shapley values

numeric The trace of H

numeric The number of rows in H

Positive integer. Total number of features/groups.

Logical. If TRUE all 2^m coalitions are generated, otherwise a subsample of the coalitions is used.

Positive integer. Note that if exact = TRUE, n_coalitions is ignored.

Vector of integers of length m-1. The number of valid coalitions of each coalition size 1, 2,..., m-1. For symmetric Shapley values, this is choose(m, seq(m-1)) (default). While for asymmetric Shapley values, this is the number of valid coalitions of each size in the causal ordering. Used to correctly normalize the Shapley weights.

Numeric. The value to use as a replacement for infinite coalition weights when doing numerical operations.

Logical. Whether to do paired sampling of coalitions.

data.table. The X data.table from the previous iteration.

Positive integer. Integer that scales the number of coalitions n_coalitions to sample as sampling is cheap, while checking for n_coalitions unique coalitions is expensive, thus we over sample the number of coalitions by a factor of n_samps_scale and determine when we have n_coalitions unique coalitions and only use the coalitions up to this point and throw away the remaining coalitions.

List. A list mapping each coalition to the features it contains.

Character vector. Contains the approach to be used for estimation of each coalition size. Same as approach in explain().

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 'none', 'on_N', 'on_all', 'on_all_cond' (default). 'none' means no reweighting, i.e. the sampling frequency weights are used as is. 'on_N' means the sampling frequencies are averaged over all coalitions with the same original sampling probabilities. 'on_all' means the original sampling probabilities are used for all coalitions. 'on_all_cond' means the original sampling probabilities are used for all coalitions, while adjusting for the probability that they are sampled at least once. 'on_all_cond' is preferred as it performs the best in simulation studies, see Olsen & Jullum (2024).

Logical. If FALSE (default), then we sample from all coalitions. If TRUE, the sampling of coalitions is semi-deterministic, i.e. the sampling is done in a way that ensures that coalitions that are expected to be sampled based on the number of coalitions are deterministically included such that we sample among fewer coalitions. This is done to reduce the variance of the Shapley value estimates, and corresponds to the PySHAP* strategy in the paper Olsen & Jullum (2024).

data.table. The data.table contains information about the which coalitions should be deterministically included and which can be sampled, in addition to the sampling probabilities of each available coalition size, and the weight given to the sampled and deterministically included coalitions (excluding empty and grand coalitions which are given the weight_zero_m weight).

data.table. Only applicable for asymmetric Shapley values explanations, and is NULL for symmetric Shapley values. The data.table contains information about the coalitions that respects the causal ordering.

Integer vector. Indicates which features are conditioned on.

Data.table with training data.

String. In some semi-rare cases party::ctree() runs into an error related to the LINPACK used by R. To get around this problem, one may fall back to using the newer (but slower) partykit::ctree() function, which is a reimplementation of the same method. Setting this parameter to "on_error" (default) falls back to partykit::ctree(), if party::ctree() fails. Other options are "never", which always uses party::ctree(), and "always", which always uses partykit::ctree(). A warning message is created whenever partykit::ctree() is used.

Positive integer. For most approaches, it indicates the maximum number of samples to use in the Monte Carlo integration of every conditional expectation. For approach="ctree", n_MC_samples corresponds to the number of samples from the leaf node (see an exception related to the ctree.sample argument setup_approach.ctree()). For approach="empirical", n_MC_samples is the K parameter in equations (14-15) of Aas et al. (2021), i.e. the maximum number of observations (with largest weights) that is used, see also the empirical.eta argument setup_approach.empirical().

Matrix or data.frame/data.table. Contains the the features, whose predictions ought to be explained.

Vector of integers containing the features indices to generate marginal observations for. That is, if Sbar_features is c(1,4), then we sample n_MC_samples observations from P(X_1, X_4). That is, we sample the first and fourth feature values from the same valid feature coalition using the marginal probability, so we do not break the dependence between them.

Vector of integers containing the features indices of the original coalition S. I.e., not the features in the current sampling step, but the features are known to us before starting the chain of sampling steps.

Integer. The number of samples to generate.

Vector of integers indicating which marginals to sample from.

Numeric vector containing the expected values for all features in the multivariate Gaussian distribution.

Numeric matrix containing the covariance between all features in the multivariate Gaussian distribution.

Data.table with training data.

Vector of integers containing the features indices to generate marginal observations for. That is, if Sbar_features is c(1,4), then we sample n_MC_samples observations from P(X_1, X_4) using the empirical training observations (with replacements). That is, we sample the first and fourth feature values from the same training observation, so we do not break the dependence between them.

Logical. If TRUE and n_MC_samples > n_train, then we include each training observation n_MC_samples %/% n_train times and then sample the remaining ⁠n_MC_samples %% n_train samples⁠. Only the latter is done when n_MC_samples < n_train. This is done separately for each explicand. If FALSE, we randomly sample the from the observations.

List. Not used directly, but passed through from explain().

Integer. The iteration number. Only used internally.

Positive integer vector. Specifies the id_coalition to apply to the present method. NULL means all coalitions. Only used internally.

List. Holds all parameters, data, functions and computed objects used within explain() The list contains one or more of the elements parameters, data, objects, iter_list, timing_list, main_timing_list, output, and iter_timing_list.

Objects. The model object that ought to be explained. See the documentation of explain() for details.

Function. The prediction function used when model is not natively supported. See the documentation of explain() for details.

Data.table with the features of the observation whose predictions ought to be explained (test data).

Data.table with training data.

Positive integer. The number of features.

Numeric matrix. Contains all nonscaled weights between training and test observations for all coalitions. The dimension equals ⁠n_train x m⁠.

Integer matrix of dimension ⁠n_coalitions x m⁠, where n_coalitions and m equals the total number of sampled/non-sampled coalitions and the total number of unique features, respectively. Note that m = ncol(x_train).

Data.table of dimension n_coalitions times n_explain + 1 containing the contribution function estimates. The first column is assumed to be named id_coalition and containing the ids of the coalitions. The last row is assumed to be the full coalition, i.e., it contains the predicted responses for the observations which are to be explained.

Scalar integer. Specifies the dimension of the output from the prediction model for every observation.

Further arguments passed to approach-specific functions.

Positive integer. Total number of features/groups.

data.table. Only applicable for asymmetric Shapley values explanations, and is NULL for symmetric Shapley values. The data.table contains information about the coalitions that respects the causal ordering.

Numeric. The value to use as a replacement for infinite coalition weights when doing numerical operations.

Model object. Specifies the model whose predictions we want to explain. Run get_supported_models() for a table of which models explain supports natively. Unsupported models can still be explained by passing predict_model and (optionally) get_model_specs, see details for more information.

Matrix or data.frame/data.table. Contains the the features, whose predictions ought to be explained.

Matrix or data.frame/data.table. Contains the data used to estimate the (conditional) distributions for the features needed to properly estimate the conditional expectations in the Shapley formula.

Character vector of length 1 or one less than the number of features. All elements should, either be "gaussian", "copula", "empirical", "ctree", "vaeac", "categorical", "timeseries", "independence", "regression_separate", or "regression_surrogate". The two regression approaches can not be combined with any other approach. See details for more information.

Numeric. The prediction value for unseen data, i.e. an estimate of the expected prediction without conditioning on any features. Typically we set this value equal to the mean of the response variable in our training data, but other choices such as the mean of the predictions in the training data are also reasonable.

Logical or NULL If NULL (default), the argument is set to TRUE if there are more than 5 features/groups, and FALSE otherwise. If eventually TRUE, the Shapley values are estimated iteratively in an iterative manner. This provides sufficiently accurate Shapley value estimates faster. First an initial number of coalitions is sampled, then bootsrapping is used to estimate the variance of the Shapley values. A convergence criterion is used to determine if the variances of the Shapley values are sufficiently small. If the variances are too high, we estimate the number of required samples to reach convergence, and thereby add more coalitions. The process is repeated until the variances are below the threshold. Specifics related to the iterative process and convergence criterion are set through iterative_args.

Integer. The upper limit on the number of unique feature/group coalitions to use in the iterative procedure (if iterative = TRUE). If iterative = FALSE it represents the number of feature/group coalitions to use directly. The quantity refers to the number of unique feature coalitions if group = NULL, and group coalitions if group != NULL. max_n_coalitions = NULL corresponds to max_n_coalitions=2^n_features.

List. If NULL regular feature wise Shapley values are computed. If provided, group wise Shapley values are computed. group then has length equal to the number of groups. The list element contains character vectors with the features included in each of the different groups. See Jullum et al. (2021) for more information on group wise Shapley values.

Positive integer. For most approaches, it indicates the maximum number of samples to use in the Monte Carlo integration of every conditional expectation. For approach="ctree", n_MC_samples corresponds to the number of samples from the leaf node (see an exception related to the ctree.sample argument setup_approach.ctree()). For approach="empirical", n_MC_samples is the K parameter in equations (14-15) of Aas et al. (2021), i.e. the maximum number of observations (with largest weights) that is used, see also the empirical.eta argument setup_approach.empirical().

Positive integer. Specifies the seed before any randomness based code is being run. If NULL (default) no seed is set in the calling environment.

String vector or NULL. Specifies the verbosity (printout detail level) through one or more of strings "basic", "progress", "convergence", "shapley" and "vS_details". "basic" (default) displays basic information about the computation which is being performed, in addition to some messages about parameters being sets or checks being unavailable due to specific input. ⁠"progress⁠ displays information about where in the calculation process the function currently is. #' "convergence" displays information on how close to convergence the Shapley value estimates are (only when iterative = TRUE) . "shapley" displays intermediate Shapley value estimates and standard deviations (only when iterative = TRUE) and the final estimates. "vS_details" displays information about the v_S estimates. This is most relevant for ⁠approach %in% c("regression_separate", "regression_surrogate", "vaeac"⁠). NULL means no printout. Note that any combination of four strings can be used. E.g. verbose = c("basic", "vS_details") will display basic information + details about the v(S)-estimation process.

Function. The prediction function used when model is not natively supported. (Run get_supported_models() for a list of natively supported models.) The function must have two arguments, model and newdata which specify, respectively, the model and a data.frame/data.table to compute predictions for. The function must give the prediction as a numeric vector. NULL (the default) uses functions specified internally. Can also be used to override the default function for natively supported model classes.

Function. An optional function for checking model/data consistency when model is not natively supported. (Run get_supported_models() for a list of natively supported models.) The function takes model as argument and provides a list with 3 elements:

labels

Character vector with the names of each feature.

classes

Character vector with the classes of each features.

factor_levels

Character vector with the levels for any categorical features.

If NULL (the default) internal functions are used for natively supported model classes, and the checking is disabled for unsupported model classes. Can also be used to override the default function for natively supported model classes.

shapr object or string. If an object of class shapr is provided, or string with a path to where intermediate results are stored, then the function will use the previous object to continue the computation. This is useful if the computation is interrupted or you want higher accuracy than already obtained, and therefore want to continue the iterative estimation. See the general usage vignette for examples.

Logical. Not applicable for (regular) non-causal or asymmetric explanations. If FALSE (default), explain computes regular symmetric Shapley values, If TRUE, then explain compute asymmetric Shapley values based on the (partial) causal ordering given by causal_ordering. That is, explain only uses the feature combinations/coalitions that respect the causal ordering when computing the asymmetric Shapley values. If asymmetric is TRUE and confounding is NULL (default), then explain computes asymmetric conditional Shapley values as specified in Frye et al. (2020). If confounding is provided, i.e., not NULL, then explain computes asymmetric causal Shapley values as specified in Heskes et al. (2020).

List. Not applicable for (regular) non-causal or asymmetric explanations. causal_ordering is an unnamed list of vectors specifying the components of the partial causal ordering that the coalitions must respect. Each vector represents a component and contains one or more features/groups identified by their names (strings) or indices (integers). If causal_ordering is NULL (default), no causal ordering is assumed and all possible coalitions are allowed. No causal ordering is equivalent to a causal ordering with a single component that includes all features (list(1:n_features)) or groups (list(1:n_groups)) for feature-wise and group-wise Shapley values, respectively. For feature-wise Shapley values and causal_ordering = list(c(1, 2), c(3, 4)), the interpretation is that features 1 and 2 are the ancestors of features 3 and 4, while features 3 and 4 are on the same level. Note: All features/groups must be included in the causal_ordering without any duplicates.

Logical vector. Not applicable for (regular) non-causal or asymmetric explanations. confounding is a vector of logicals specifying whether confounding is assumed or not for each component in the causal_ordering. If NULL (default), then no assumption about the confounding structure is made and explain computes asymmetric/symmetric conditional Shapley values, depending on the value of asymmetric. If confounding is a single logical, i.e., FALSE or TRUE, then this assumption is set globally for all components in the causal ordering. Otherwise, confounding must be a vector of logicals of the same length as causal_ordering, indicating the confounding assumption for each component. When confounding is specified, then explain computes asymmetric/symmetric causal Shapley values, depending on the value of asymmetric. The approach cannot be regression_separate and regression_surrogate as the regression-based approaches are not applicable to the causal Shapley value methodology.

Named list. Specifies extra arguments related to the computation of the Shapley values. See get_extra_comp_args_default() for description of the arguments and their default values.

Named list. Specifies the arguments for the iterative procedure. See get_iterative_args_default() for description of the arguments and their default values.

Named list. Specifies certain arguments related to the output of the function. See get_output_args_default() for description of the arguments and their default values.

Arguments passed on to setup_approach.categorical, setup_approach.copula, setup_approach.ctree, setup_approach.empirical, setup_approach.gaussian, setup_approach.independence, setup_approach.regression_separate, setup_approach.regression_surrogate, setup_approach.timeseries, setup_approach.vaeac

categorical.joint_prob_dt

Data.table. (Optional) Containing the joint probability distribution for each combination of feature values. NULL means it is estimated from the x_train and x_explain.

categorical.epsilon

Numeric value. (Optional) If categorical.joint_probability_dt is not supplied, probabilities/frequencies are estimated using x_train. If certain observations occur in x_explain and NOT in x_train, then epsilon is used as the proportion of times that these observations occurs in the training data. In theory, this proportion should be zero, but this causes an error later in the Shapley computation.

internal

List. Not used directly, but passed through from explain().

ctree.mincriterion

Numeric scalar or vector. Either a scalar or vector of length equal to the number of features in the model. The value is equal to 1 - \alpha where \alpha is the nominal level of the conditional independence tests. If it is a vector, this indicates which value to use when conditioning on various numbers of features. The default value is 0.95.

ctree.minsplit

Numeric scalar. Determines minimum value that the sum of the left and right daughter nodes required for a split. The default value is 20.

ctree.minbucket

Numeric scalar. Determines the minimum sum of weights in a terminal node required for a split The default value is 7.

ctree.sample

Boolean. If TRUE (default), then the method always samples n_MC_samples observations from the leaf nodes (with replacement). If FALSE and the number of observations in the leaf node is less than n_MC_samples, the method will take all observations in the leaf. If FALSE and the number of observations in the leaf node is more than n_MC_samples, the method will sample n_MC_samples observations (with replacement). This means that there will always be sampling in the leaf unless sample = FALSE and the number of obs in the node is less than n_MC_samples.

empirical.type

Character. (default = "fixed_sigma") Should be equal to either "independence","fixed_sigma", "AICc_each_k" "AICc_full". "independence" is deprecated. Use approach = "independence" instead. "fixed_sigma" uses a fixed bandwidth (set through empirical.fixed_sigma) in the kernel density estimation. "AICc_each_k" and "AICc_full" optimize the bandwidth using the AICc criterion, with respectively one bandwidth per coalition size and one bandwidth for all coalition sizes.

empirical.eta

Numeric scalar. Needs to be ⁠0 < eta <= 1⁠. The default value is 0.95. Represents the minimum proportion of the total empirical weight that data samples should use. If e.g. eta = .8 we will choose the K samples with the largest weight so that the sum of the weights accounts for 80\ eta is the \eta parameter in equation (15) of Aas et al. (2021).

empirical.fixed_sigma

Positive numeric scalar. The default value is 0.1. Represents the kernel bandwidth in the distance computation used when conditioning on all different coalitions. Only used when empirical.type = "fixed_sigma"

empirical.n_samples_aicc

Positive integer. Number of samples to consider in AICc optimization. The default value is 1000. Only used for empirical.type is either "AICc_each_k" or "AICc_full".

empirical.eval_max_aicc

Positive integer. Maximum number of iterations when optimizing the AICc. The default value is 20. Only used for empirical.type is either "AICc_each_k" or "AICc_full".

empirical.start_aicc

Numeric. Start value of the sigma parameter when optimizing the AICc. The default value is 0.1. Only used for empirical.type is either "AICc_each_k" or "AICc_full".

empirical.cov_mat

Numeric matrix. (Optional) The covariance matrix of the data generating distribution used to define the Mahalanobis distance. NULL means it is estimated from x_train.

gaussian.mu

Numeric vector. (Optional) Containing the mean of the data generating distribution. NULL means it is estimated from the x_train.

gaussian.cov_mat

Numeric matrix. (Optional) Containing the covariance matrix of the data generating distribution. NULL means it is estimated from the x_train.

regression.model

A tidymodels object of class model_specs. Default is a linear regression model, i.e., parsnip::linear_reg(). See tidymodels for all possible models, and see the vignette for how to add new/own models. Note, to make it easier to call explain() from Python, the regression.model parameter can also be a string specifying the model which will be parsed and evaluated. For example, ⁠"parsnip::rand_forest(mtry = hardhat::tune(), trees = 100, engine = "ranger", mode = "regression")"⁠ is also a valid input. It is essential to include the package prefix if the package is not loaded.

regression.tune_values

Either NULL (default), a data.frame/data.table/tibble, or a function. The data.frame must contain the possible hyperparameter value combinations to try. The column names must match the names of the tunable parameters specified in regression.model. If regression.tune_values is a function, then it should take one argument x which is the training data for the current coalition and returns a data.frame/data.table/tibble with the properties described above. Using a function allows the hyperparameter values to change based on the size of the coalition See the regression vignette for several examples. Note, to make it easier to call explain() from Python, the regression.tune_values can also be a string containing an R function. For example, "function(x) return(dials::grid_regular(dials::mtry(c(1, ncol(x)))), levels = 3))" is also a valid input. It is essential to include the package prefix if the package is not loaded.

regression.vfold_cv_para

Either NULL (default) or a named list containing the parameters to be sent to rsample::vfold_cv(). See the regression vignette for several examples.

regression.recipe_func

Either NULL (default) or a function that that takes in a recipes::recipe() object and returns a modified recipes::recipe() with potentially additional recipe steps. See the regression vignette for several examples. Note, to make it easier to call explain() from Python, the regression.recipe_func can also be a string containing an R function. For example, "function(recipe) return(recipes::step_ns(recipe, recipes::all_numeric_predictors(), deg_free = 2))" is also a valid input. It is essential to include the package prefix if the package is not loaded.

regression.surrogate_n_comb

Positive integer. Specifies the number of unique coalitions to apply to each training observation. The default is the number of sampled coalitions in the present iteration. Any integer between 1 and the default is allowed. Larger values requires more memory, but may improve the surrogate model. If the user sets a value lower than the maximum, we sample this amount of unique coalitions separately for each training observations. That is, on average, all coalitions should be equally trained.

timeseries.fixed_sigma

Positive numeric scalar. Represents the kernel bandwidth in the distance computation. The default value is 2.

timeseries.bounds

Numeric vector of length two. Specifies the lower and upper bounds of the timeseries. The default is c(NULL, NULL), i.e. no bounds. If one or both of these bounds are not NULL, we restrict the sampled time series to be between these bounds. This is useful if the underlying time series are scaled between 0 and 1, for example.

vaeac.depth

Positive integer (default is 3). The number of hidden layers in the neural networks of the masked encoder, full encoder, and decoder.

vaeac.width

Positive integer (default is 32). The number of neurons in each hidden layer in the neural networks of the masked encoder, full encoder, and decoder.

vaeac.latent_dim

Positive integer (default is 8). The number of dimensions in the latent space.

vaeac.lr

Positive numeric (default is 0.001). The learning rate used in the torch::optim_adam() optimizer.

vaeac.activation_function

An torch::nn_module() representing an activation function such as, e.g., torch::nn_relu() (default), torch::nn_leaky_relu(), torch::nn_selu(), or torch::nn_sigmoid().

vaeac.n_vaeacs_initialize

Positive integer (default is 4). The number of different vaeac models to initiate in the start. Pick the best performing one after vaeac.extra_parameters$epochs_initiation_phase epochs (default is 2) and continue training that one.

vaeac.epochs

Positive integer (default is 100). The number of epochs to train the final vaeac model. This includes vaeac.extra_parameters$epochs_initiation_phase, where the default is 2.

vaeac.extra_parameters

Named list with extra parameters to the vaeac approach. See vaeac_get_extra_para_default() for description of possible additional parameters and their default values.

Model object. Specifies the model whose predictions we want to explain. Run get_supported_models() for a table of which models explain supports natively. Unsupported models can still be explained by passing predict_model and (optionally) get_model_specs, see details for more information.

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.

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.

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 train_idx = NULL (default) all indices not selected to be explained will be used.

Numeric vector. The row indices in data and reg denoting points in time to explain.

Numeric vector. Denotes the number of lags that should be used for each variable in y when making a forecast.

Numeric vector. If xreg != NULL, denotes the number of lags that should be used for each variable in xreg when making a forecast.

Numeric. The forecast horizon to explain. Passed to the predict_model function.

Character vector of length 1 or one less than the number of features. All elements should, either be "gaussian", "copula", "empirical", "ctree", "vaeac", "categorical", "timeseries", "independence", "regression_separate", or "regression_surrogate". The two regression approaches can not be combined with any other approach. See details for more information.

Numeric. The prediction value for unseen data, i.e. an estimate of the expected prediction without conditioning on any features. Typically we set this value equal to the mean of the response variable in our training data, but other choices such as the mean of the predictions in the training data are also reasonable.

Integer. The upper limit on the number of unique feature/group coalitions to use in the iterative procedure (if iterative = TRUE). If iterative = FALSE it represents the number of feature/group coalitions to use directly. The quantity refers to the number of unique feature coalitions if group = NULL, and group coalitions if group != NULL. max_n_coalitions = NULL corresponds to max_n_coalitions=2^n_features.

Logical or NULL If NULL (default), the argument is set to TRUE if there are more than 5 features/groups, and FALSE otherwise. If eventually TRUE, the Shapley values are estimated iteratively in an iterative manner. This provides sufficiently accurate Shapley value estimates faster. First an initial number of coalitions is sampled, then bootsrapping is used to estimate the variance of the Shapley values. A convergence criterion is used to determine if the variances of the Shapley values are sufficiently small. If the variances are too high, we estimate the number of required samples to reach convergence, and thereby add more coalitions. The process is repeated until the variances are below the threshold. Specifics related to the iterative process and convergence criterion are set through iterative_args.

Logical. If TRUE all lags of each variable are grouped together and explained as a group. If FALSE all lags of each variable are explained individually.

List. If NULL regular feature wise Shapley values are computed. If provided, group wise Shapley values are computed. group then has length equal to the number of groups. The list element contains character vectors with the features included in each of the different groups. See Jullum et al. (2021) for more information on group wise Shapley values.

Positive integer. For most approaches, it indicates the maximum number of samples to use in the Monte Carlo integration of every conditional expectation. For approach="ctree", n_MC_samples corresponds to the number of samples from the leaf node (see an exception related to the ctree.sample argument setup_approach.ctree()). For approach="empirical", n_MC_samples is the K parameter in equations (14-15) of Aas et al. (2021), i.e. the maximum number of observations (with largest weights) that is used, see also the empirical.eta argument setup_approach.empirical().

Positive integer. Specifies the seed before any randomness based code is being run. If NULL (default) no seed is set in the calling environment.

Function. The prediction function used when model is not natively supported. (Run get_supported_models() for a list of natively supported models.) The function must have two arguments, model and newdata which specify, respectively, the model and a data.frame/data.table to compute predictions for. The function must give the prediction as a numeric vector. NULL (the default) uses functions specified internally. Can also be used to override the default function for natively supported model classes.

Function. An optional function for checking model/data consistency when model is not natively supported. (Run get_supported_models() for a list of natively supported models.) The function takes model as argument and provides a list with 3 elements:

labels

Character vector with the names of each feature.

classes

Character vector with the classes of each features.

factor_levels

Character vector with the levels for any categorical features.

If NULL (the default) internal functions are used for natively supported model classes, and the checking is disabled for unsupported model classes. Can also be used to override the default function for natively supported model classes.

String vector or NULL. Specifies the verbosity (printout detail level) through one or more of strings "basic", "progress", "convergence", "shapley" and "vS_details". "basic" (default) displays basic information about the computation which is being performed, in addition to some messages about parameters being sets or checks being unavailable due to specific input. ⁠"progress⁠ displays information about where in the calculation process the function currently is. #' "convergence" displays information on how close to convergence the Shapley value estimates are (only when iterative = TRUE) . "shapley" displays intermediate Shapley value estimates and standard deviations (only when iterative = TRUE) and the final estimates. "vS_details" displays information about the v_S estimates. This is most relevant for ⁠approach %in% c("regression_separate", "regression_surrogate", "vaeac"⁠). NULL means no printout. Note that any combination of four strings can be used. E.g. verbose = c("basic", "vS_details") will display basic information + details about the v(S)-estimation process.

Named list. Specifies extra arguments related to the computation of the Shapley values. See get_extra_comp_args_default() for description of the arguments and their default values.

Named list. Specifies the arguments for the iterative procedure. See get_iterative_args_default() for description of the arguments and their default values.

Named list. Specifies certain arguments related to the output of the function. See get_output_args_default() for description of the arguments and their default values.

Arguments passed on to setup_approach.categorical, setup_approach.copula, setup_approach.ctree, setup_approach.empirical, setup_approach.gaussian, setup_approach.independence, setup_approach.timeseries, setup_approach.vaeac

categorical.joint_prob_dt

Data.table. (Optional) Containing the joint probability distribution for each combination of feature values. NULL means it is estimated from the x_train and x_explain.

categorical.epsilon

Numeric value. (Optional) If categorical.joint_probability_dt is not supplied, probabilities/frequencies are estimated using x_train. If certain observations occur in x_explain and NOT in x_train, then epsilon is used as the proportion of times that these observations occurs in the training data. In theory, this proportion should be zero, but this causes an error later in the Shapley computation.

internal

List. Not used directly, but passed through from explain().

ctree.mincriterion

Numeric scalar or vector. Either a scalar or vector of length equal to the number of features in the model. The value is equal to 1 - \alpha where \alpha is the nominal level of the conditional independence tests. If it is a vector, this indicates which value to use when conditioning on various numbers of features. The default value is 0.95.

ctree.minsplit

Numeric scalar. Determines minimum value that the sum of the left and right daughter nodes required for a split. The default value is 20.

ctree.minbucket

Numeric scalar. Determines the minimum sum of weights in a terminal node required for a split The default value is 7.

ctree.sample

Boolean. If TRUE (default), then the method always samples n_MC_samples observations from the leaf nodes (with replacement). If FALSE and the number of observations in the leaf node is less than n_MC_samples, the method will take all observations in the leaf. If FALSE and the number of observations in the leaf node is more than n_MC_samples, the method will sample n_MC_samples observations (with replacement). This means that there will always be sampling in the leaf unless sample = FALSE and the number of obs in the node is less than n_MC_samples.

empirical.type

Character. (default = "fixed_sigma") Should be equal to either "independence","fixed_sigma", "AICc_each_k" "AICc_full". "independence" is deprecated. Use approach = "independence" instead. "fixed_sigma" uses a fixed bandwidth (set through empirical.fixed_sigma) in the kernel density estimation. "AICc_each_k" and "AICc_full" optimize the bandwidth using the AICc criterion, with respectively one bandwidth per coalition size and one bandwidth for all coalition sizes.

empirical.eta

Numeric scalar. Needs to be ⁠0 < eta <= 1⁠. The default value is 0.95. Represents the minimum proportion of the total empirical weight that data samples should use. If e.g. eta = .8 we will choose the K samples with the largest weight so that the sum of the weights accounts for 80\ eta is the \eta parameter in equation (15) of Aas et al. (2021).

empirical.fixed_sigma

Positive numeric scalar. The default value is 0.1. Represents the kernel bandwidth in the distance computation used when conditioning on all different coalitions. Only used when empirical.type = "fixed_sigma"

empirical.n_samples_aicc

Positive integer. Number of samples to consider in AICc optimization. The default value is 1000. Only used for empirical.type is either "AICc_each_k" or "AICc_full".

empirical.eval_max_aicc

Positive integer. Maximum number of iterations when optimizing the AICc. The default value is 20. Only used for empirical.type is either "AICc_each_k" or "AICc_full".

empirical.start_aicc

Numeric. Start value of the sigma parameter when optimizing the AICc. The default value is 0.1. Only used for empirical.type is either "AICc_each_k" or "AICc_full".

empirical.cov_mat

Numeric matrix. (Optional) The covariance matrix of the data generating distribution used to define the Mahalanobis distance. NULL means it is estimated from x_train.

gaussian.mu

Numeric vector. (Optional) Containing the mean of the data generating distribution. NULL means it is estimated from the x_train.

gaussian.cov_mat

Numeric matrix. (Optional) Containing the covariance matrix of the data generating distribution. NULL means it is estimated from the x_train.

timeseries.fixed_sigma

Positive numeric scalar. Represents the kernel bandwidth in the distance computation. The default value is 2.

timeseries.bounds

Numeric vector of length two. Specifies the lower and upper bounds of the timeseries. The default is c(NULL, NULL), i.e. no bounds. If one or both of these bounds are not NULL, we restrict the sampled time series to be between these bounds. This is useful if the underlying time series are scaled between 0 and 1, for example.

vaeac.depth

Positive integer (default is 3). The number of hidden layers in the neural networks of the masked encoder, full encoder, and decoder.

vaeac.width

Positive integer (default is 32). The number of neurons in each hidden layer in the neural networks of the masked encoder, full encoder, and decoder.

vaeac.latent_dim

Positive integer (default is 8). The number of dimensions in the latent space.

vaeac.lr

Positive numeric (default is 0.001). The learning rate used in the torch::optim_adam() optimizer.

vaeac.activation_function

An torch::nn_module() representing an activation function such as, e.g., torch::nn_relu() (default), torch::nn_leaky_relu(), torch::nn_selu(), or torch::nn_sigmoid().

vaeac.n_vaeacs_initialize

Positive integer (default is 4). The number of different vaeac models to initiate in the start. Pick the best performing one after vaeac.extra_parameters$epochs_initiation_phase epochs (default is 2) and continue training that one.

vaeac.epochs

Positive integer (default is 100). The number of epochs to train the final vaeac model. This includes vaeac.extra_parameters$epochs_initiation_phase, where the default is 2.

vaeac.extra_parameters

Named list with extra parameters to the vaeac approach. See vaeac_get_extra_para_default() for description of possible additional parameters and their default values.

List. Not used directly, but passed through from explain().

A torch tensor of dimension n_features containing the one hot sizes of the n_features features. That is, if the ith feature is a categorical feature with 5 levels, then one_hot_max_sizes[i] = 5. While the size for continuous features can either be 0 or 1.

For stability it might be desirable that the minimal sigma is not too close to zero.

For stability it might be desirable that the minimal probability is not too close to zero.

A torch tensor of dimension n_features containing the one hot sizes of the n_features features. That is, if the ith feature is a categorical feature with 5 levels, then one_hot_max_sizes[i] = 5. While the size for continuous features can either be 0 or 1.

For stability it might be desirable that the minimal sigma is not too close to zero.

For stability it might be desirable that the minimal probability is not too close to zero.

A torch tensor of dimension n_features containing the one hot sizes of the n_features features. That is, if the ith feature is a categorical feature with 5 levels, then one_hot_max_sizes[i] = 5. While the size for continuous features can either be 0 or 1.

For stability it might be desirable that the minimal sigma is not too close to zero.

For stability it might be desirable that the minimal probability is not too close to zero.

A torch tensor of dimension n_features containing the one hot sizes of the n_features features. That is, if the ith feature is a categorical feature with 5 levels, then one_hot_max_sizes[i] = 5. While the size for continuous features can either be 0 or 1.

For stability it might be desirable that the minimal sigma is not too close to zero.

For stability it might be desirable that the minimal probability is not too close to zero.

Numeric vector.The data which should be transformed to a standard normal distribution.

Numeric vector. The first n_y items is the data that is transformed, and last part is the data with the original transformation.

Positive integer. Number of elements of yx that belongs to the Gaussian data.

Integer matrix of dimension n_coalitions_valid x m, where n_coalitions_valid equals the total number of valid coalitions that respect the causal ordering given in causal_ordering and m equals the total number of features.

List. Not applicable for (regular) non-causal or asymmetric explanations. causal_ordering is an unnamed list of vectors specifying the components of the partial causal ordering that the coalitions must respect. Each vector represents a component and contains one or more features/groups identified by their names (strings) or indices (integers). If causal_ordering is NULL (default), no causal ordering is assumed and all possible coalitions are allowed. No causal ordering is equivalent to a causal ordering with a single component that includes all features (list(1:n_features)) or groups (list(1:n_groups)) for feature-wise and group-wise Shapley values, respectively. For feature-wise Shapley values and causal_ordering = list(c(1, 2), c(3, 4)), the interpretation is that features 1 and 2 are the ancestors of features 3 and 4, while features 3 and 4 are on the same level. Note: All features/groups must be included in the causal_ordering without any duplicates.

Logical vector. Not applicable for (regular) non-causal or asymmetric explanations. confounding is a vector of logicals specifying whether confounding is assumed or not for each component in the causal_ordering. If NULL (default), then no assumption about the confounding structure is made and explain computes asymmetric/symmetric conditional Shapley values, depending on the value of asymmetric. If confounding is a single logical, i.e., FALSE or TRUE, then this assumption is set globally for all components in the causal ordering. Otherwise, confounding must be a vector of logicals of the same length as causal_ordering, indicating the confounding assumption for each component. When confounding is specified, then explain computes asymmetric/symmetric causal Shapley values, depending on the value of asymmetric. The approach cannot be regression_separate and regression_surrogate as the regression-based approaches are not applicable to the causal Shapley value methodology.

Boolean. If the returned object is to be a list of lists of integers or a list of vectors of strings.

Matrix or data.frame/data.table. Contains the data used to estimate the (conditional) distributions for the features needed to properly estimate the conditional expectations in the Shapley formula.

Numeric Specifies the smallest allowed eigen value before the covariance matrix of x_train is assumed to not be positive definite, and Matrix::nearPD() is used to find the nearest one.

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.

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.

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 train_idx = NULL (default) all indices not selected to be explained will be used.

Numeric vector. The row indices in data and reg denoting points in time to explain.

Numeric vector. Denotes the number of lags that should be used for each variable in y when making a forecast.

Numeric vector. If xreg != NULL, denotes the number of lags that should be used for each variable in xreg when making a forecast.

Numeric. The forecast horizon to explain. Passed to the predict_model function.

data.frame or data.table. The data to extract feature information from.

List. Not used directly, but passed through from explain().

Logical. If TRUE paired versions of all sampled coalitions are also included in the computation. That is, if there are 5 features and e.g. coalitions (1,3,5) are sampled, then also coalition (2,4) is used for computing the Shapley values. This is done to reduce the variance of the Shapley value estimates. TRUE is the default and is recommended for highest accuracy. For asymmetric, FALSE is the default and the only legal value.

Logical. If FALSE (default), then we sample from all coalitions. If TRUE, the sampling of coalitions is semi-deterministic, i.e. the sampling is done in a way that ensures that coalitions that are expected to be sampled based on the number of coalitions are deterministically included such that we sample among fewer coalitions. This is done to reduce the variance of the Shapley value estimates, and corresponds to the PySHAP* strategy in the paper Olsen & Jullum (2024).

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 'none', 'on_N', 'on_all', 'on_all_cond' (default). 'none' means no reweighting, i.e. the sampling frequency weights are used as is. 'on_N' means the sampling frequencies are averaged over all coalitions with the same original sampling probabilities. 'on_all' means the original sampling probabilities are used for all coalitions. 'on_all_cond' means the original sampling probabilities are used for all coalitions, while adjusting for the probability that they are sampled at least once. 'on_all_cond' is preferred as it performs the best in simulation studies, see Olsen & Jullum (2024).

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).

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.

String. The method used to perform batch computing of vS. "future" (default), utilizes future.apply::future_apply (via the future::future package), enabling parallelized computation and progress updates via progressr::progressr. Alternatively, "forloop" can be used for straight forward sequential computation, which is mainly useful for package development and debugging purposes.

Integer. The maximum number of coalitions to estimate simultaneously within each iteration. A larger numbers requires more memory, but may have a slight computational advantage.

Integer. The minimum number of batches to split the computation into within each iteration. Larger numbers gives more frequent progress updates. If parallelization is applied, this should be set no smaller than the number of parallel workers.

Function. An optional function for checking model/data consistency when model is not natively supported. (Run get_supported_models() for a list of natively supported models.) The function takes model as argument and provides a list with 3 elements:

labels

Character vector with the names of each feature.

classes

Character vector with the classes of each features.

factor_levels

Character vector with the levels for any categorical features.

If NULL (the default) internal functions are used for natively supported model classes, and the checking is disabled for unsupported model classes. Can also be used to override the default function for natively supported model classes.

Model object. Specifies the model whose predictions we want to explain. Run get_supported_models() for a table of which models explain supports natively. Unsupported models can still be explained by passing predict_model and (optionally) get_model_specs, see details for more information.

List. Not used directly, but passed through from explain().

Integer. Number of coalitions to use in the first estimation iteration.

Integer. Number of n_coalitions to use in each iteration. NULL (default) means setting it based on estimates based on a set convergence threshold.

Integer. Maximum number of estimation iterations

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.

Numeric vector. The number of n_coalitions that must be used to reach convergence in the next iteration is estimated. The number of n_coalitions actually used in the next iteration is set to this estimate multiplied by n_coal_next_iter_factor_vec[i] for iteration i. It is wise to start with smaller numbers to avoid using too many n_coalitions due to uncertain estimates in the first iterations.

List. Not applicable for (regular) non-causal or asymmetric explanations. causal_ordering is an unnamed list of vectors specifying the components of the partial causal ordering that the coalitions must respect. Each vector represents a component and contains one or more features/groups identified by their names (strings) or indices (integers). If causal_ordering is NULL (default), no causal ordering is assumed and all possible coalitions are allowed. No causal ordering is equivalent to a causal ordering with a single component that includes all features (list(1:n_features)) or groups (list(1:n_groups)) for feature-wise and group-wise Shapley values, respectively. For feature-wise Shapley values and causal_ordering = list(c(1, 2), c(3, 4)), the interpretation is that features 1 and 2 are the ancestors of features 3 and 4, while features 3 and 4 are on the same level. Note: All features/groups must be included in the causal_ordering without any duplicates.

Model object for the model to be explained.

Matrix or data.frame/data.table. Contains the data used to estimate the (conditional) distributions for the features needed to properly estimate the conditional expectations in the Shapley formula.

Logical. Indicates whether the samples used in the Monte Carlo estimation of v_S should be returned (in internal$output). Not used for approach="regression_separate" or approach="regression_surrogate".

Logical. If TRUE (default), then the function weights the coalitions uniformly when computing the MSEv criterion. If FALSE, then the function use the Shapley kernel weights to weight the coalitions when computing the MSEv criterion. Note that the Shapley kernel weights are replaced by the sampling frequency when not all coalitions are considered.

String. The path to the directory where the results of the iterative estimation procedure should be saved. Defaults to a temporary directory.

Function. The prediction function used when model is not natively supported. See the documentation of explain() for details.

Objects. The model object that ought to be explained. See the documentation of explain() for details.

List. Not applicable for (regular) non-causal or asymmetric explanations. causal_ordering is an unnamed list of vectors specifying the components of the partial causal ordering that the coalitions must respect. Each vector represents a component and contains one or more features/groups identified by their names (strings) or indices (integers). If causal_ordering is NULL (default), no causal ordering is assumed and all possible coalitions are allowed. No causal ordering is equivalent to a causal ordering with a single component that includes all features (list(1:n_features)) or groups (list(1:n_groups)) for feature-wise and group-wise Shapley values, respectively. For feature-wise Shapley values and causal_ordering = list(c(1, 2), c(3, 4)), the interpretation is that features 1 and 2 are the ancestors of features 3 and 4, while features 3 and 4 are on the same level. Note: All features/groups must be included in the causal_ordering without any duplicates.

Boolean. If TRUE, then the feature indices in the coalitions are sorted in increasing order. If FALSE, then the function maintains the order of features within each group given in causal_ordering.

The list of groups to be explained.

A list of features per horizon, to split appropriate groups over.

matrix.

matrix The covariance matrix of X.

logical. Indicating whether the Mahalanobis distance should be scaled with the number of variables

numeric specifying the scaling (sigma)

arma::mat. The data are the Gaussian Monte Carlos samples to transform.

arma::mat. The data with the original transformation. Used to conduct the transformation of z.

The matrix of variables (one variable per column).

A numeric vector denoting how many lags each variable should have.

List. Contains the vectors indicating all factor combinations that should be included in the computations. Assumes that the first one is empty.

Matrix Training data in matrix form

Matrix Explanation data in matrix form.

matrix The covariance matrix of X.

logical. Indicating whether the Mahalanobis distance should be scaled with the number of variables

Numeric between 0 and 1. The probability for an entry in the generated mask to be 1 (masked).

Boolean. If we are doing paired sampling. So include both S and \bar{S}. If TRUE, then batch must be sampled using paired_sampler() which ensures that the batch contains two instances for each original observation. That is, batch = [X_1, X_1, X_2, X_2, X_3, X_3, ...], where each entry X_j is a row of dimension p (i.e., the number of features).

A unique id to use as a key in the storage list.

A shared environment for all instances of memory_layer where the inputs are stored.

Boolean variable indicating if the memory layer is to store input in storage or extract from storage.

Boolean variable indicating if the extracted value are to be added or concatenated to the input. Only applicable when output = TRUE.

Boolean variable indicating if we want to give printouts to the user.

Model object for the model to be explained.

Numeric matrix. Contains all nonscaled weights between training and test observations for all coalitions. The dimension equals ⁠n_train x m⁠.

Integer matrix of dimension ⁠n_coalitions x m⁠, where n_coalitions and m equals the total number of sampled/non-sampled coalitions and the total number of unique features, respectively. Note that m = ncol(x_train).

Data.table with training data.

Data.table with the features of the observation whose predictions ought to be explained (test data).

Positive integer. Represents a sequence of row indices from x_train, i.e. min(index_xtrain) >= 1 and max(index_xtrain) <= nrow(x_train).

Positive integer. Represents a sequence of row indices from S, i.e. min(index_s) >= 1 and max(index_s) <= nrow(S).

Matrix. Contains the training data.

Matrix with 1 row. Contains the features of the observation for a single prediction.

arma::mat. Matrix of dimension (n_coalitions, n_features) containing binary representations of the used coalitions. S cannot contain the empty or grand coalition, i.e., a row containing only zeros or ones. This is not a problem internally in shapr as the empty and grand coalitions are treated differently.

A vaeac_dataset() object containing the data.

Boolean. If TRUE, then the data is shuffled. If FALSE, then the data is returned in chronological order.

An shapr object. The output from explain().

Character. Specifies the type of plot to produce. "bar" (the default) gives a regular horizontal bar plot of the Shapley value magnitudes. "waterfall" gives a waterfall plot indicating the changes in the prediction score due to each features contribution (their Shapley values). "scatter" plots the feature values on the x-axis and Shapley values on the y-axis, as well as (optionally) a background scatter_hist showing the distribution of the feature data. "beeswarm" summarizes the distribution of the Shapley values along the x-axis for all the features. Each point gives the shapley value of a given instance, where the points are colored by the feature value of that instance.

Integer. Number of significant digits to use in the feature description. Applicable for plot_type "bar" and "waterfall"

Integer vector. Which of the test observations to plot. E.g. if you have explained 10 observations using explain(), you can generate a plot for the first 5 observations by setting index_x_explain = 1:5.

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 top_k_features = 1:5. Applicable for plot_type "bar" and "waterfall"

Character vector (where length depends on plot type). The color codes (hex codes or other names understood by ggplot2::ggplot()) for positive and negative Shapley values, respectively. The default is col=NULL, plotting with the default colors respective to the plot type. For plot_type = "bar" and plot_type = "waterfall", the default is c("#00BA38","#F8766D"). For plot_type = "beeswarm", the default is c("#F8766D","yellow","#00BA38"). For plot_type = "scatter", the default is "#619CFF".

If you want to alter the colors i the plot, the length of the col vector depends on plot type. For plot_type = "bar" or plot_type = "waterfall", two colors should be provided, first for positive and then for negative Shapley values. For plot_type = "beeswarm", either two or three colors can be given. If two colors are given, then the first color determines the color that points with high feature values will have, and the second determines the color of points with low feature values. If three colors are given, then the first colors high feature values, the second colors mid-range feature values, and the third colors low feature values. For instance, col = c("red", "yellow", "blue") will make high values red, mid-range values yellow, and low values blue. For plot_type = "scatter", a single color is to be given, which determines the color of the points on the scatter plot.

Logical. Whether to include phi0 in the plot for plot_type = "bar".

Character. Specifies what order to plot the features with respect to the magnitude of the shapley values with plot_type = "bar": "largest_first" (the default) plots the features ordered from largest to smallest absolute Shapley value. "smallest_first" plots the features ordered from smallest to largest absolute Shapley value. "original" plots the features in the original order of the data table.

Integer or character vector. Only used for plot_type = "scatter". Specifies what features to include in (scatter) plot. Can be a numerical vector indicating feature index, or a character vector, indicating the name(s) of the feature(s) to plot.

Logical. Only used for plot_type = "scatter". Whether to include a scatter_hist indicating the distribution of the data when making the scatter plot. Note that the bins are scaled so that when all the bins are stacked they fit the span of the y-axis of the plot.

Logical. Whether to include the average feature value in a group on the y-axis or not. If FALSE (default), then no value is shown for the groups. If TRUE, then shapr includes the mean of the features in each group.

Numeric. The cex argument of ggbeeswarm::geom_beeswarm(), controlling the spacing in the beeswarm plots.

Other arguments passed to underlying functions, like ggbeeswarm::geom_beeswarm() for plot_type = "beeswarm".

A list of explain() objects applied to the same data and model. If the entries in the list are named, then the function use these names. Otherwise, they default to the approach names (with integer suffix for duplicates) for the explanation objects in explanation_list.

Integer vector. Which of the test observations to plot. E.g. if you have explained 10 observations using explain(), you can generate a plot for the first 5 observations by setting index_x_explain = 1:5.

Integer vector. Which of the coalitions to plot. E.g. if you used n_coalitions = 16 in explain(), you can generate a plot for the first 5 coalitions and the 10th by setting id_coalition = c(1:5, 10).

Positive numeric between zero and one. Default is 0.95 if the number of observations to explain is larger than 20, otherwise CI_level = NULL, which removes the confidence intervals. The level of the approximate confidence intervals for the overall MSEv and the MSEv_coalition. The confidence intervals are based on that the MSEv scores are means over the observations/explicands, and that means are approximation normal. Since the standard deviations are estimated, we use the quantile t from the T distribution with N_explicands - 1 degrees of freedom corresponding to the provided level. Here, N_explicands is the number of observations/explicands. MSEv +/- tSD(MSEv)/sqrt(N_explicands). Note that the explain() function already scales the standard deviation by sqrt(N_explicands), thus, the CI are MSEv \/- tMSEv_sd, where the values MSEv and MSEv_sd are extracted from the MSEv data.tables in the objects in the explanation_list.

Numeric. Bar width. By default, set to 90% of the ggplot2::resolution() of the data.

Character vector. The possible options are "overall" (default), "comb", and "explicand". If plot_type = "overall", then the plot (one bar plot) associated with the overall MSEv evaluation criterion for each method is created, i.e., when averaging over both the coalitions and observations/explicands. If plot_type = "comb", then the plots (one line plot and one bar plot) associated with the MSEv evaluation criterion for each coalition are created, i.e., when we only average over the observations/explicands. If plot_type = "explicand", then the plots (one line plot and one bar plot) associated with the MSEv evaluation criterion for each observations/explicands are created, i.e., when we only average over the coalitions. If plot_type is a vector of one or several of "overall", "comb", and "explicand", then the associated plots are created.

A list of explain() objects applied to the same data and model. If the entries in the list are named, then the function use these names. Otherwise, they default to the approach names (with integer suffix for duplicates) for the explanation objects in explanation_list.

Integer vector. Which of the explicands (test observations) to plot. E.g. if you have explained 10 observations using explain(), you can generate a plot for the first 5 observations/explicands and the 10th by setting index_x_explain = c(1:5, 10). The argument index_explicands_sort must be FALSE to plot the explicand in the order specified in index_x_explain.

Boolean. If FALSE (default), then shapr plots the explicands in the order specified in index_explicands. If TRUE, then shapr sort the indices in increasing order based on their id.

String vector. Containing the names of the features which are to be included in the bar plots.

Boolean. If we are to include the \phi_0 in the bar plots or not.

Integer. Number of significant digits to use in the feature description. Applicable for plot_type "bar" and "waterfall"

Boolean. If we are to add a black line for a feature contribution of 0.

Integer. The number of rows that should be used to render the labels. This is useful for displaying labels that would otherwise overlap.

Numeric. The angle of the axis label, where 0 means horizontal, 45 means tilted, and 90 means vertical. Compared to setting the angle in ggplot2::theme() / ggplot2::element_text(), this also uses some heuristics to automatically pick the hjust and vjust that you probably want.

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 ggplot2::coord_flip().

Should scales be free ("free", the default), fixed ("fixed"), or free in one dimension ("free_x", "free_y")? The user has to change the latter manually depending on the value of horizontal_bars.

Integer. The number of columns in the facet grid. Default is facet_ncol = 2.

Numeric. Bar width. By default, set to 85% of the ggplot2::resolution() of the data.

String. Name of one of the color palettes from RColorBrewer::RColorBrewer(). If NULL, then the function uses the default ggplot2::ggplot() color scheme. The following palettes are available for use with these scales:

Diverging

BrBG, PiYG, PRGn, PuOr, RdBu, RdGy, RdYlBu, RdYlGn, Spectral

Qualitative

Accent, Dark2, Paired, Pastel1, Pastel2, Set1, Set2, Set3

Sequential

Blues, BuGn, BuPu, GnBu, Greens, Greys, Oranges, OrRd, PuBu, PuBuGn, PuRd, Purples, RdPu, Reds, YlGn, YlGnBu, YlOrBr, YlOrRd

Logical. Whether to include the average feature value in a group on the y-axis or not. If FALSE (default), then no value is shown for the groups. If TRUE, then shapr includes the mean of the features in each group.

A list of explain() objects applied to the same data, model, and vaeac must be the used approach. If the entries in the list is named, then the function use these names. Otherwise, it defaults to the approach names (with integer suffix for duplicates) for the explanation objects in explanation_list.

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.

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.

Character vector. The possible options are "VLB", "IWAE", "IWAE_running". Default is the first two.

Character vector. The possible options are "method" and "criterion". Default is to plot both.

String. Should the scales be fixed ("fixed", the default), free ("free"), or free in one dimension ("free_x", "free_y").

Integer. Number of columns in the facet wrap.

Shapr list. The output list from the explain() function.

String. Indicating which vaeac model to use when generating the samples. Possible options are always 'best', 'best_running', and 'last'. All possible options can be obtained by calling names(explanation$internal$parameters$vaeac$models).

Data.table containing the data from the distribution that the vaeac model is fitted to.

Logical. If TRUE, then a title is added to the plot based on the internal description of the vaeac model specified in which_vaeac_model.

Numeric between 0 and 1 (default is 0.5). The degree of color transparency.

String. Type of plot to use in upper triangle for continuous features, see GGally::ggpairs(). Possible options are: 'cor' (default), 'points', 'smooth', 'smooth_loess', 'density', and 'blank'.

String. Type of plot to use in upper triangle for categorical features, see GGally::ggpairs(). Possible options are: 'count' (default), 'cross', 'ratio', 'facetbar', and 'blank'.

String. Type of plot to use in upper triangle for mixed features, see GGally::ggpairs(). Possible options are: 'box' (default), 'box_no_facet', 'dot', 'dot_no_facet', 'facethist', 'facetdensity', 'denstrip', and 'blank'

String. Type of plot to use in lower triangle for continuous features, see GGally::ggpairs(). Possible options are: 'points' (default), 'smooth', 'smooth_loess', 'density', 'cor', and 'blank'.

String. Type of plot to use in lower triangle for categorical features, see GGally::ggpairs(). Possible options are: 'facetbar' (default), 'ratio', 'count', 'cross', and 'blank'.

String. Type of plot to use in lower triangle for mixed features, see GGally::ggpairs(). Possible options are: 'facetdensity' (default), 'box', 'box_no_facet', 'dot', 'dot_no_facet', 'facethist', 'denstrip', and 'blank'.

String. Type of plot to use on the diagonal for continuous features, see GGally::ggpairs(). Possible options are: 'densityDiag' (default), 'barDiag', and 'blankDiag'.

String. Type of plot to use on the diagonal for categorical features, see GGally::ggpairs(). Possible options are: 'barDiag' (default) and 'blankDiag'.

String. Type of correlation measure, see GGally::ggpairs(). Possible options are: 'pearson' (default), 'kendall', and 'spearman'.

Model object for the model to be explained.

A data.frame/data.table with the features to predict from.

newreg and horizon parameters used in models passed to ⁠[explain_forecast()]⁠

Numeric. The forecast horizon to explain. Passed to the predict_model function.

Numeric vector. The row indices in data and reg denoting points in time to explain.

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.

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.

List. Not used directly, but passed through from explain().

Positive integer vector. Specifies the id_coalition to apply to the present method. NULL means all coalitions. Only used internally.

Currently not used.

List. Not used directly, but passed through from explain().

Positive integer vector. Specifies the id_coalition to apply to the present method. NULL means all coalitions. Only used internally.

Currently not used.

arma::mat. Matrix of dimension (n_MC_samples, n_features) containing samples from the univariate standard normal.

arma::mat. Matrix of dimension (n_explain, n_features) containing the observations to explain.

arma::mat. Matrix of dimension (n_explain, n_features) containing the observations to explain after being transformed using the Gaussian transform, i.e., the samples have been transformed to a standardized normal distribution.

arma::mat. Matrix of dimension (n_train, n_features) containing the training observations.

arma::mat. Matrix of dimension (n_coalitions, n_features) containing binary representations of the used coalitions. S cannot contain the empty or grand coalition, i.e., a row containing only zeros or ones. This is not a problem internally in shapr as the empty and grand coalitions are treated differently.

arma::vec. Vector of length n_features containing the mean of each feature after being transformed using the Gaussian transform, i.e., the samples have been transformed to a standardized normal distribution.

arma::mat. Matrix of dimension (n_features, n_features) containing the pairwise covariance between all pairs of features after being transformed using the Gaussian transform, i.e., the samples have been transformed to a standardized normal distribution.

arma::mat. Matrix of dimension (n_MC_samples, n_features) containing samples from the univariate standard normal.

arma::mat. Matrix of dimension (n_explain, n_features) containing the observations to explain.

arma::mat. Matrix of dimension (n_explain, n_features) containing the observations to explain after being transformed using the Gaussian transform, i.e., the samples have been transformed to a standardized normal distribution.

arma::mat. Matrix of dimension (n_train, n_features) containing the training observations.

arma::mat. Matrix of dimension (n_coalitions, n_features) containing binary representations of the used coalitions. S cannot contain the empty or grand coalition, i.e., a row containing only zeros or ones. This is not a problem internally in shapr as the empty and grand coalitions are treated differently.

arma::vec. Vector of length n_features containing the mean of each feature after being transformed using the Gaussian transform, i.e., the samples have been transformed to a standardized normal distribution.

arma::mat. Matrix of dimension (n_features, n_features) containing the pairwise covariance between all pairs of features after being transformed using the Gaussian transform, i.e., the samples have been transformed to a standardized normal distribution.

arma::mat. Matrix of dimension (n_MC_samples, n_features) containing samples from the univariate standard normal.

arma::mat. Matrix of dimension (n_explain, n_features) containing the observations to explain.

arma::mat. Matrix of dimension (n_coalitions, n_features) containing binary representations of the used coalitions. S cannot contain the empty or grand coalition, i.e., a row containing only zeros or ones. This is not a problem internally in shapr as the empty and grand coalitions are treated differently.

arma::vec. Vector of length n_features containing the mean of each feature.

arma::mat. Matrix of dimension (n_features, n_features) containing the covariance matrix of the features.

arma::mat. Matrix of dimension (n_MC_samples, n_features) containing samples from the univariate standard normal.

arma::mat. Matrix of dimension (n_explain, n_features) containing the observations to explain.

arma::mat. Matrix of dimension (n_coalitions, n_features) containing binary representations of the used coalitions. S cannot contain the empty or grand coalition, i.e., a row containing only zeros or ones. This is not a problem internally in shapr as the empty and grand coalitions are treated differently.

arma::vec. Vector of length n_features containing the mean of each feature.

arma::mat. Matrix of dimension (n_features, n_features) containing the covariance matrix of the features.

List. Holds all parameters, data, functions and computed objects used within explain() The list contains one or more of the elements parameters, data, objects, iter_list, timing_list, main_timing_list, output, and iter_timing_list.

List. Not used directly, but passed through from explain().

A shapr object

Scalar Integer. Number of digits to display to the console

Unused

List. Not used directly, but passed through from explain().

data.table to plot

Columns that are factors or character

arma::vec. Numeric vector whose sample quantiles are wanted.

arma::vec. Numeric vector of probabilities with values between zero and one.

A matrix with the exogenous variables.

Numeric. The forecast horizon to explain. Passed to the predict_model function.

The list of endogenous groups, to append exogenous groups to.

List. Holds all parameters, data, functions and computed objects used within explain() The list contains one or more of the elements parameters, data, objects, iter_list, timing_list, main_timing_list, output, and iter_timing_list.

Either NULL (default) or a function that that takes in a recipes::recipe() object and returns a modified recipes::recipe() with potentially additional recipe steps. See the regression vignette for several examples. Note, to make it easier to call explain() from Python, the regression.recipe_func can also be a string containing an R function. For example, "function(recipe) return(recipes::step_ns(recipe, recipes::all_numeric_predictors(), deg_free = 2))" is also a valid input. It is essential to include the package prefix if the package is not loaded.

Data.table with the features of the observation whose predictions ought to be explained (test data).

Positive integer. Specifies the number of unique coalitions to apply to each training observation. The default is the number of sampled coalitions in the present iteration. Any integer between 1 and the default is allowed. Larger values requires more memory, but may improve the surrogate model. If the user sets a value lower than the maximum, we sample this amount of unique coalitions separately for each training observations. That is, on average, all coalitions should be equally trained.

Integer. The number of used coalitions (including the empty and grand coalition).

Either NULL (default) or a named list containing the parameters to be sent to rsample::vfold_cv(). See the regression vignette for several examples.

The results of the CV procedures.

Object containing the hyperparameter values.

Integer (default is 10) specifying the number of CV hyperparameter configurations to print.

Integer vector. The current combination of features, passed to verbosity printing function.

A character vector/string containing the text to convert into R code.

A tidymodels object of class model_specs. Default is a linear regression model, i.e., parsnip::linear_reg(). See tidymodels for all possible models, and see the vignette for how to add new/own models. Note, to make it easier to call explain() from Python, the regression.model parameter can also be a string specifying the model which will be parsed and evaluated. For example, ⁠"parsnip::rand_forest(mtry = hardhat::tune(), trees = 100, engine = "ranger", mode = "regression")"⁠ is also a valid input. It is essential to include the package prefix if the package is not loaded.

Either NULL (default), a data.frame/data.table/tibble, or a function. The data.frame must contain the possible hyperparameter value combinations to try. The column names must match the names of the tunable parameters specified in regression.model. If regression.tune_values is a function, then it should take one argument x which is the training data for the current coalition and returns a data.frame/data.table/tibble with the properties described above. Using a function allows the hyperparameter values to change based on the size of the coalition See the regression vignette for several examples. Note, to make it easier to call explain() from Python, the regression.tune_values can also be a string containing an R function. For example, "function(x) return(dials::grid_regular(dials::mtry(c(1, ncol(x)))), levels = 3))" is also a valid input. It is essential to include the package prefix if the package is not loaded.

Data.table with training data.

List. Holds all parameters, data, functions and computed objects used within explain() The list contains one or more of the elements parameters, data, objects, iter_list, timing_list, main_timing_list, output, and iter_timing_list.

Objects. The model object that ought to be explained. See the documentation of explain() for details.

Function. The prediction function used when model is not natively supported. See the documentation of explain() for details.

List. Holds all parameters, data, functions and computed objects used within explain() The list contains one or more of the elements parameters, data, objects, iter_list, timing_list, main_timing_list, output, and iter_timing_list.

Data.table containing the training data.

Vector of numerics (optional) containing the predicted responses for the observations in x.

Array of integers (optional) containing which coalitions to consider. Must be provided if x is the explicands.

Logical (default is FALSE). If TRUE, then the binary masks are converted to factors. If FALSE, then the binary masks are numerics.

Logical (default is FALSE). If TRUE, then the grand coalition is included. If index_features are provided, then augment_include_grand has no effect. Note that if we sample the coalitions then the grand coalition is equally likely to be samples as the other coalitions (or weighted if augment_comb_prob is provided).

Logical (default is FALSE). If TRUE, an additional column is adding containing which coalition was applied.

Array of numerics (default is NULL). The length of the array must match the number of coalitions being considered, where each entry specifies the probability of sampling the corresponding coalition. This is useful if we want to generate more training data for some specific coalitions. One possible choice would be augment_comb_prob = if (use_Shapley_weights) internal$objects$X$shapley_weight[2:actual_n_coalitions] else NULL.

String (optional). Specifying which type of weights to add to the observations. If NULL (default), then no weights are added. If "Shapley", then the Shapley weights for the different coalitions are added to corresponding observations where the coalitions was applied. If uniform, then all observations get an equal weight of one.

Data.table containing the training data.

Positive integer. Specifies the seed before any randomness based code is being run. If NULL (default) no seed is set in the calling environment.

String vector or NULL. Specifies the verbosity (printout detail level) through one or more of strings "basic", "progress", "convergence", "shapley" and "vS_details". "basic" (default) displays basic information about the computation which is being performed, in addition to some messages about parameters being sets or checks being unavailable due to specific input. ⁠"progress⁠ displays information about where in the calculation process the function currently is. #' "convergence" displays information on how close to convergence the Shapley value estimates are (only when iterative = TRUE) . "shapley" displays intermediate Shapley value estimates and standard deviations (only when iterative = TRUE) and the final estimates. "vS_details" displays information about the v_S estimates. This is most relevant for ⁠approach %in% c("regression_separate", "regression_surrogate", "vaeac"⁠). NULL means no printout. Note that any combination of four strings can be used. E.g. verbose = c("basic", "vS_details") will display basic information + details about the v(S)-estimation process.

A tidymodels object of class model_specs. Default is a linear regression model, i.e., parsnip::linear_reg(). See tidymodels for all possible models, and see the vignette for how to add new/own models. Note, to make it easier to call explain() from Python, the regression.model parameter can also be a string specifying the model which will be parsed and evaluated. For example, ⁠"parsnip::rand_forest(mtry = hardhat::tune(), trees = 100, engine = "ranger", mode = "regression")"⁠ is also a valid input. It is essential to include the package prefix if the package is not loaded.

Logical (default is FALSE). If TRUE, then we are to tune the hyperparemeters based on the values provided in regression.tune_values. Note that no checks are conducted as this is checked earlier in setup_approach.regression_separate and setup_approach.regression_surrogate.

Either NULL (default), a data.frame/data.table/tibble, or a function. The data.frame must contain the possible hyperparameter value combinations to try. The column names must match the names of the tunable parameters specified in regression.model. If regression.tune_values is a function, then it should take one argument x which is the training data for the current coalition and returns a data.frame/data.table/tibble with the properties described above. Using a function allows the hyperparameter values to change based on the size of the coalition See the regression vignette for several examples. Note, to make it easier to call explain() from Python, the regression.tune_values can also be a string containing an R function. For example, "function(x) return(dials::grid_regular(dials::mtry(c(1, ncol(x)))), levels = 3))" is also a valid input. It is essential to include the package prefix if the package is not loaded.

Either NULL (default) or a named list containing the parameters to be sent to rsample::vfold_cv(). See the regression vignette for several examples.

Either NULL (default) or a function that that takes in a recipes::recipe() object and returns a modified recipes::recipe() with potentially additional recipe steps. See the regression vignette for several examples. Note, to make it easier to call explain() from Python, the regression.recipe_func can also be a string containing an R function. For example, "function(recipe) return(recipes::step_ns(recipe, recipes::all_numeric_predictors(), deg_free = 2))" is also a valid input. It is essential to include the package prefix if the package is not loaded.

String (default is y_hat) containing the name of the response variable.

Integer (default is NULL). The number of times each training observations has been augmented. If NULL, then we assume that we are doing separate regression.

Integer vector. The current combination of features, passed to verbosity printing function.

Matrix. Output from hat_matrix_cpp()

Vector Representing the (temporary) response variable

Positive integer. Total number of features/groups.

Positive integer. Note that if exact = TRUE, n_coalitions is ignored.

Vector of integers of length m-1. The number of valid coalitions of each coalition size 1, 2,..., m-1. For symmetric Shapley values, this is choose(m, seq(m-1)) (default). While for asymmetric Shapley values, this is the number of valid coalitions of each size in the causal ordering. Used to correctly normalize the Shapley weights.

Numeric. The value to use as a replacement for infinite coalition weights when doing numerical operations.

Logical. Whether to do paired sampling of coalitions.

data.table. The X data.table from the previous iteration.

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 'none', 'on_N', 'on_all', 'on_all_cond' (default). 'none' means no reweighting, i.e. the sampling frequency weights are used as is. 'on_N' means the sampling frequencies are averaged over all coalitions with the same original sampling probabilities. 'on_all' means the original sampling probabilities are used for all coalitions. 'on_all_cond' means the original sampling probabilities are used for all coalitions, while adjusting for the probability that they are sampled at least once. 'on_all_cond' is preferred as it performs the best in simulation studies, see Olsen & Jullum (2024).

Logical. If FALSE (default), then we sample from all coalitions. If TRUE, the sampling of coalitions is semi-deterministic, i.e. the sampling is done in a way that ensures that coalitions that are expected to be sampled based on the number of coalitions are deterministically included such that we sample among fewer coalitions. This is done to reduce the variance of the Shapley value estimates, and corresponds to the PySHAP* strategy in the paper Olsen & Jullum (2024).

data.table. The data.table contains information about the which coalitions should be deterministically included and which can be sampled, in addition to the sampling probabilities of each available coalition size, and the weight given to the sampled and deterministically included coalitions (excluding empty and grand coalitions which are given the weight_zero_m weight).

data.table. Only applicable for asymmetric Shapley values explanations, and is NULL for symmetric Shapley values. The data.table contains information about the coalitions that respects the causal ordering.

Positive integer. Integer that scales the number of coalitions n_coalitions to sample as sampling is cheap, while checking for n_coalitions unique coalitions is expensive, thus we over sample the number of coalitions by a factor of n_samps_scale and determine when we have n_coalitions unique coalitions and only use the coalitions up to this point and throw away the remaining coalitions.

Positive integer. Total number of features/groups.

IntegerVector. The number of features to sample for each feature combination.

Logical. Whether to do paired sampling of coalitions.

Positive integer. Number of training observations to sample from.

Positive integer. Number of test observations to sample from.

Positive integer. Number of samples.

Logical. Indicates whether train- and test data should be sampled separately or in a joint sampling space. If they are sampled separately (which typically would be used when optimizing more than one distribution at once) we sample with replacement if nsamples > ntrain. Note that this solution is not optimal. Be careful if you're doing optimization over every test observation when nsamples > ntrain.

List. Contains tree which is an object of type ctree built from the party package. Also contains given_ind, the features to condition upon.

Scalar integer. Corresponds to the number of samples from the leaf node. See an exception when sample = FALSE in setup_approach.ctree().

Data.table with the features of the observation whose predictions ought to be explained (test data).

Data.table with training data.

Positive integer. The number of features.

List. Not used directly, but passed through from explain().

Matrix or data.frame/data.table. Contains the data used to estimate the (conditional) distributions for the features needed to properly estimate the conditional expectations in the Shapley formula.

Matrix or data.frame/data.table. Contains the the features, whose predictions ought to be explained.

Character vector of length 1 or one less than the number of features. All elements should, either be "gaussian", "copula", "empirical", "ctree", "vaeac", "categorical", "timeseries", "independence", "regression_separate", or "regression_surrogate". The two regression approaches can not be combined with any other approach. See details for more information.

Numeric. The prediction value for unseen data, i.e. an estimate of the expected prediction without conditioning on any features. Typically we set this value equal to the mean of the response variable in our training data, but other choices such as the mean of the predictions in the training data are also reasonable.

Scalar integer. Specifies the dimension of the output from the prediction model for every observation.

Integer. The upper limit on the number of unique feature/group coalitions to use in the iterative procedure (if iterative = TRUE). If iterative = FALSE it represents the number of feature/group coalitions to use directly. The quantity refers to the number of unique feature coalitions if group = NULL, and group coalitions if group != NULL. max_n_coalitions = NULL corresponds to max_n_coalitions=2^n_features.

List. If NULL regular feature wise Shapley values are computed. If provided, group wise Shapley values are computed. group then has length equal to the number of groups. The list element contains character vectors with the features included in each of the different groups. See Jullum et al. (2021) for more information on group wise Shapley values.

Positive integer. For most approaches, it indicates the maximum number of samples to use in the Monte Carlo integration of every conditional expectation. For approach="ctree", n_MC_samples corresponds to the number of samples from the leaf node (see an exception related to the ctree.sample argument setup_approach.ctree()). For approach="empirical", n_MC_samples is the K parameter in equations (14-15) of Aas et al. (2021), i.e. the maximum number of observations (with largest weights) that is used, see also the empirical.eta argument setup_approach.empirical().

Positive integer. Specifies the seed before any randomness based code is being run. If NULL (default) no seed is set in the calling environment.

List. The output from get_model_specs() or get_data_specs(). Contains the 3 elements:

labels

Character vector with the names of each feature.

classes

Character vector with the classes of each features.

factor_levels

Character vector with the levels for any categorical features.

Character. Either "regular" or "forecast" corresponding to function setup() is called from, correspondingly the type of explanation that should be generated.

Numeric. The forecast horizon to explain. Passed to the predict_model function.

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.

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.

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 train_idx = NULL (default) all indices not selected to be explained will be used.

Numeric vector. The row indices in data and reg denoting points in time to explain.

Numeric vector. Denotes the number of lags that should be used for each variable in y when making a forecast.

Numeric vector. If xreg != NULL, denotes the number of lags that should be used for each variable in xreg when making a forecast.

Logical. If TRUE all lags of each variable are grouped together and explained as a group. If FALSE all lags of each variable are explained individually.

String vector or NULL. Specifies the verbosity (printout detail level) through one or more of strings "basic", "progress", "convergence", "shapley" and "vS_details". "basic" (default) displays basic information about the computation which is being performed, in addition to some messages about parameters being sets or checks being unavailable due to specific input. ⁠"progress⁠ displays information about where in the calculation process the function currently is. #' "convergence" displays information on how close to convergence the Shapley value estimates are (only when iterative = TRUE) . "shapley" displays intermediate Shapley value estimates and standard deviations (only when iterative = TRUE) and the final estimates. "vS_details" displays information about the v_S estimates. This is most relevant for ⁠approach %in% c("regression_separate", "regression_surrogate", "vaeac"⁠). NULL means no printout. Note that any combination of four strings can be used. E.g. verbose = c("basic", "vS_details") will display basic information + details about the v(S)-estimation process.

Logical or NULL If NULL (default), the argument is set to TRUE if there are more than 5 features/groups, and FALSE otherwise. If eventually TRUE, the Shapley values are estimated iteratively in an iterative manner. This provides sufficiently accurate Shapley value estimates faster. First an initial number of coalitions is sampled, then bootsrapping is used to estimate the variance of the Shapley values. A convergence criterion is used to determine if the variances of the Shapley values are sufficiently small. If the variances are too high, we estimate the number of required samples to reach convergence, and thereby add more coalitions. The process is repeated until the variances are below the threshold. Specifics related to the iterative process and convergence criterion are set through iterative_args.

Named list. Specifies the arguments for the iterative procedure. See get_iterative_args_default() for description of the arguments and their default values.

Logical. Indicates whether the function is called from the Python wrapper. Default is FALSE which is never changed when calling the function via explain() in R. The parameter is later used to disallow running the AICc-versions of the empirical method as that requires data based optimization, which is not supported in shaprpy.

Logical. Only use to remove random components like timing from the object output when comparing output with testthat. Defaults to FALSE.

POSIXct object. The time when the explain() function was called, as outputted by Sys.time(). Used to calculate the time it took to run the full explain call.

shapr object or string. If an object of class shapr is provided, or string with a path to where intermediate results are stored, then the function will use the previous object to continue the computation. This is useful if the computation is interrupted or you want higher accuracy than already obtained, and therefore want to continue the iterative estimation. See the general usage vignette for examples.

Logical. Not applicable for (regular) non-causal or asymmetric explanations. If FALSE (default), explain computes regular symmetric Shapley values, If TRUE, then explain compute asymmetric Shapley values based on the (partial) causal ordering given by causal_ordering. That is, explain only uses the feature combinations/coalitions that respect the causal ordering when computing the asymmetric Shapley values. If asymmetric is TRUE and confounding is NULL (default), then explain computes asymmetric conditional Shapley values as specified in Frye et al. (2020). If confounding is provided, i.e., not NULL, then explain computes asymmetric causal Shapley values as specified in Heskes et al. (2020).

List. Not applicable for (regular) non-causal or asymmetric explanations. causal_ordering is an unnamed list of vectors specifying the components of the partial causal ordering that the coalitions must respect. Each vector represents a component and contains one or more features/groups identified by their names (strings) or indices (integers). If causal_ordering is NULL (default), no causal ordering is assumed and all possible coalitions are allowed. No causal ordering is equivalent to a causal ordering with a single component that includes all features (list(1:n_features)) or groups (list(1:n_groups)) for feature-wise and group-wise Shapley values, respectively. For feature-wise Shapley values and causal_ordering = list(c(1, 2), c(3, 4)), the interpretation is that features 1 and 2 are the ancestors of features 3 and 4, while features 3 and 4 are on the same level. Note: All features/groups must be included in the causal_ordering without any duplicates.

Logical vector. Not applicable for (regular) non-causal or asymmetric explanations. confounding is a vector of logicals specifying whether confounding is assumed or not for each component in the causal_ordering. If NULL (default), then no assumption about the confounding structure is made and explain computes asymmetric/symmetric conditional Shapley values, depending on the value of asymmetric. If confounding is a single logical, i.e., FALSE or TRUE, then this assumption is set globally for all components in the causal ordering. Otherwise, confounding must be a vector of logicals of the same length as causal_ordering, indicating the confounding assumption for each component. When confounding is specified, then explain computes asymmetric/symmetric causal Shapley values, depending on the value of asymmetric. The approach cannot be regression_separate and regression_surrogate as the regression-based approaches are not applicable to the causal Shapley value methodology.

Named list. Specifies certain arguments related to the output of the function. See get_output_args_default() for description of the arguments and their default values.

Named list. Specifies extra arguments related to the computation of the Shapley values. See get_extra_comp_args_default() for description of the arguments and their default values.

Further arguments passed to specific approaches, see below.

List. Not used directly, but passed through from explain().

Arguments passed to specific classes. See below

Data.table. (Optional) Containing the joint probability distribution for each combination of feature values. NULL means it is estimated from the x_train and x_explain.

Numeric value. (Optional) If categorical.joint_probability_dt is not supplied, probabilities/frequencies are estimated using x_train. If certain observations occur in x_explain and NOT in x_train, then epsilon is used as the proportion of times that these observations occurs in the training data. In theory, this proportion should be zero, but this causes an error later in the Shapley computation.

Numeric scalar or vector. Either a scalar or vector of length equal to the number of features in the model. The value is equal to 1 - \alpha where \alpha is the nominal level of the conditional independence tests. If it is a vector, this indicates which value to use when conditioning on various numbers of features. The default value is 0.95.

Numeric scalar. Determines minimum value that the sum of the left and right daughter nodes required for a split. The default value is 20.

Numeric scalar. Determines the minimum sum of weights in a terminal node required for a split The default value is 7.

Boolean. If TRUE (default), then the method always samples n_MC_samples observations from the leaf nodes (with replacement). If FALSE and the number of observations in the leaf node is less than n_MC_samples, the method will take all observations in the leaf. If FALSE and the number of observations in the leaf node is more than n_MC_samples, the method will sample n_MC_samples observations (with replacement). This means that there will always be sampling in the leaf unless sample = FALSE and the number of obs in the node is less than n_MC_samples.

Character. (default = "fixed_sigma") Should be equal to either "independence","fixed_sigma", "AICc_each_k" "AICc_full". "independence" is deprecated. Use approach = "independence" instead. "fixed_sigma" uses a fixed bandwidth (set through empirical.fixed_sigma) in the kernel density estimation. "AICc_each_k" and "AICc_full" optimize the bandwidth using the AICc criterion, with respectively one bandwidth per coalition size and one bandwidth for all coalition sizes.

Numeric scalar. Needs to be ⁠0 < eta <= 1⁠. The default value is 0.95. Represents the minimum proportion of the total empirical weight that data samples should use. If e.g. eta = .8 we will choose the K samples with the largest weight so that the sum of the weights accounts for 80\ eta is the \eta parameter in equation (15) of Aas et al. (2021).

Positive numeric scalar. The default value is 0.1. Represents the kernel bandwidth in the distance computation used when conditioning on all different coalitions. Only used when empirical.type = "fixed_sigma"

Positive integer. Number of samples to consider in AICc optimization. The default value is 1000. Only used for empirical.type is either "AICc_each_k" or "AICc_full".

Positive integer. Maximum number of iterations when optimizing the AICc. The default value is 20. Only used for empirical.type is either "AICc_each_k" or "AICc_full".

Numeric. Start value of the sigma parameter when optimizing the AICc. The default value is 0.1. Only used for empirical.type is either "AICc_each_k" or "AICc_full".

Numeric matrix. (Optional) The covariance matrix of the data generating distribution used to define the Mahalanobis distance. NULL means it is estimated from x_train.

Objects. The model object that ought to be explained. See the documentation of explain() for details.

Function. The prediction function used when model is not natively supported. See the documentation of explain() for details.

Numeric vector. (Optional) Containing the mean of the data generating distribution. NULL means it is estimated from the x_train.

Numeric matrix. (Optional) Containing the covariance matrix of the data generating distribution. NULL means it is estimated from the x_train.

A tidymodels object of class model_specs. Default is a linear regression model, i.e., parsnip::linear_reg(). See tidymodels for all possible models, and see the vignette for how to add new/own models. Note, to make it easier to call explain() from Python, the regression.model parameter can also be a string specifying the model which will be parsed and evaluated. For example, ⁠"parsnip::rand_forest(mtry = hardhat::tune(), trees = 100, engine = "ranger", mode = "regression")"⁠ is also a valid input. It is essential to include the package prefix if the package is not loaded.

Either NULL (default), a data.frame/data.table/tibble, or a function. The data.frame must contain the possible hyperparameter value combinations to try. The column names must match the names of the tunable parameters specified in regression.model. If regression.tune_values is a function, then it should take one argument x which is the training data for the current coalition and returns a data.frame/data.table/tibble with the properties described above. Using a function allows the hyperparameter values to change based on the size of the coalition See the regression vignette for several examples. Note, to make it easier to call explain() from Python, the regression.tune_values can also be a string containing an R function. For example, "function(x) return(dials::grid_regular(dials::mtry(c(1, ncol(x)))), levels = 3))" is also a valid input. It is essential to include the package prefix if the package is not loaded.

Either NULL (default) or a named list containing the parameters to be sent to rsample::vfold_cv(). See the regression vignette for several examples.

Either NULL (default) or a function that that takes in a recipes::recipe() object and returns a modified recipes::recipe() with potentially additional recipe steps. See the regression vignette for several examples. Note, to make it easier to call explain() from Python, the regression.recipe_func can also be a string containing an R function. For example, "function(recipe) return(recipes::step_ns(recipe, recipes::all_numeric_predictors(), deg_free = 2))" is also a valid input. It is essential to include the package prefix if the package is not loaded.

Positive integer. Specifies the number of unique coalitions to apply to each training observation. The default is the number of sampled coalitions in the present iteration. Any integer between 1 and the default is allowed. Larger values requires more memory, but may improve the surrogate model. If the user sets a value lower than the maximum, we sample this amount of unique coalitions separately for each training observations. That is, on average, all coalitions should be equally trained.

Positive numeric scalar. Represents the kernel bandwidth in the distance computation. The default value is 2.

Numeric vector of length two. Specifies the lower and upper bounds of the timeseries. The default is c(NULL, NULL), i.e. no bounds. If one or both of these bounds are not NULL, we restrict the sampled time series to be between these bounds. This is useful if the underlying time series are scaled between 0 and 1, for example.

Positive integer (default is 3). The number of hidden layers in the neural networks of the masked encoder, full encoder, and decoder.

Positive integer (default is 32). The number of neurons in each hidden layer in the neural networks of the masked encoder, full encoder, and decoder.

Positive integer (default is 8). The number of dimensions in the latent space.

An torch::nn_module() representing an activation function such as, e.g., torch::nn_relu() (default), torch::nn_leaky_relu(), torch::nn_selu(), or torch::nn_sigmoid().

Positive numeric (default is 0.001). The learning rate used in the torch::optim_adam() optimizer.

Positive integer (default is 4). The number of different vaeac models to initiate in the start. Pick the best performing one after vaeac.extra_parameters$epochs_initiation_phase epochs (default is 2) and continue training that one.

Positive integer (default is 100). The number of epochs to train the final vaeac model. This includes vaeac.extra_parameters$epochs_initiation_phase, where the default is 2.

Named list with extra parameters to the vaeac approach. See vaeac_get_extra_para_default() for description of possible additional parameters and their default values.

List. Not used directly, but passed through from explain().

Positive integer. Total number of features/groups.

Positive integer. The number of unique coalitions when sampling n_components features/feature groups, without replacement, from a sample space consisting of m different features/feature groups.

Positive integer. Represents the number of features/feature groups you want to sample from a feature space consisting of m unique features/feature groups. Note that ⁠ 0 < = n_components <= m⁠.

Numeric. The value to use as a replacement for infinite coalition weights when doing numerical operations.

network modules such as, e.g., torch::nn_linear(), torch::nn_relu(), and memory_layer() objects. See vaeac() for more information.

Matrix/Tensor of possible/allowed 'masks' which we sample from.

Array of 'probabilities' for each of the masks specified in 'masks'. Note that they do not need to be between 0 and 1 (e.g. sampling frequency). They are scaled, hence, they only need to be positive.

Boolean. If we are doing paired sampling. So include both S and \bar{S}. If TRUE, then batch must be sampled using 'paired_sampler' which creates batches where the first half and second half of the rows are duplicates of each other. That is, ⁠batch = [row1, row1, row2, row2, row3, row3, ...]⁠.

An M+1 numerics containing the probabilities masking 'd' of the (0,...M) entries for each observation.

Boolean. If we are doing paired sampling. So include both S and \bar{S}. If TRUE, then batch must be sampled using 'paired_sampler' which creates batches where the first half and second half of the rows are duplicates of each other. That is, ⁠batch = [row1, row1, row2, row2, row3, row3, ...]⁠.

Function. The prediction function used when model is not natively supported. See the documentation of explain() for details.

Objects. The model object that ought to be explained. See the documentation of explain() for details.

List. Holds all parameters, data, functions and computed objects used within explain() The list contains one or more of the elements parameters, data, objects, iter_list, timing_list, main_timing_list, output, and iter_timing_list.

A torch tensor of dimension n_features containing the one hot sizes of the n_features features. That is, if the ith feature is a categorical feature with 5 levels, then one_hot_max_sizes[i] = 5. While the size for continuous features can either be 0 or 1.

Integer. The number of neurons in each hidden layer in the neural networks of the masked encoder, full encoder, and decoder.

Integer. The number of hidden layers in the neural networks of the masked encoder, full encoder, and decoder.

Integer. The number of dimensions in the latent space.

A torch::nn_module() representing an activation function such as, e.g., torch::nn_relu(), torch::nn_leaky_relu(), torch::nn_selu(), torch::nn_sigmoid().

Boolean. If we are to use skip connections in each layer, see skip_connection(). If TRUE, then we add the input to the outcome of each hidden layer, so the output becomes X + \operatorname{activation}(WX + b). I.e., the identity skip connection.

Boolean. If we are to apply concatenating skip connections between the layers in the masked encoder and decoder. The first layer of the masked encoder will be linked to the last layer of the decoder. The second layer of the masked encoder will be linked to the second to last layer of the decoder, and so on.

Boolean. If we are to use batch normalization after the activation function. Note that if skip_conn_layer is TRUE, then the normalization is done after the adding from the skip connection. I.e, we batch normalize the whole quantity X + activation(WX + b).

Boolean. If we are doing paired sampling. I.e., if we are to include both coalition S and \bar{S} when we sample coalitions during training for each batch.

String specifying the type of mask generator to use. Need to be one of 'mcar_mask_generator', 'specified_prob_mask_generator', and 'specified_masks_mask_generator'.

Scalar. The probability for an entry in the generated mask to be 1 (masked). Not used if mask_gen_coalitions is given.

Matrix containing the different coalitions to learn. Must be given if mask_generator_name = 'specified_masks_mask_generator'.

Numerics containing the probabilities for sampling each mask in mask_gen_coalitions. Array containing the probabilities for sampling the coalitions in mask_gen_coalitions.

Numeric representing a hyperparameter in the normal-gamma prior used on the masked encoder, see Section 3.3.1 in Olsen et al. (2022).

Numeric representing a hyperparameter in the normal-gamma prior used on the masked encoder, see Section 3.3.1 in Olsen et al. (2022).

Tensor of dimension batch_size x K containing the logits for each of the K classes and batch_size observations.

For stability it might be desirable that the minimal probability is not too close to zero.

For stability it might be desirable that the maximal probability is not too close to one.

An torch::nn_module() representing an activation function such as, e.g., torch::nn_relu() (default), torch::nn_leaky_relu(), torch::nn_selu(), or torch::nn_sigmoid().

Logical (default is FALSE). If TRUE, then the vaeac model will be trained using cuda/GPU. If torch::cuda_is_available() is FALSE, the we fall back to use CPU. If FALSE, we use the CPU. Using a GPU for smaller tabular dataset often do not improve the efficiency. See vignette("installation", package = "torch") fo help to enable running on the GPU (only Linux and Windows).

String vector or NULL. Specifies the verbosity (printout detail level) through one or more of strings "basic", "progress", "convergence", "shapley" and "vS_details". "basic" (default) displays basic information about the computation which is being performed, in addition to some messages about parameters being sets or checks being unavailable due to specific input. ⁠"progress⁠ displays information about where in the calculation process the function currently is. #' "convergence" displays information on how close to convergence the Shapley value estimates are (only when iterative = TRUE) . "shapley" displays intermediate Shapley value estimates and standard deviations (only when iterative = TRUE) and the final estimates. "vS_details" displays information about the v_S estimates. This is most relevant for ⁠approach %in% c("regression_separate", "regression_surrogate", "vaeac"⁠). NULL means no printout. Note that any combination of four strings can be used. E.g. verbose = c("basic", "vS_details") will display basic information + details about the v(S)-estimation process.

Positive integer (default is 100). The number of epochs to train the final vaeac model. This includes epochs_initiation_phase, where the default is 2.

Positive integer (default is 2). The number of epochs to run each of the n_vaeacs_initialize vaeac models before continuing to train only the best performing model.

Positive integer (default is NULL). The training stops if there has been no improvement in the validation IWAE for epochs_early_stopping epochs. If the user wants the training process to be solely based on this training criterion, then epochs in explain() should be set to a large number. If NULL, then shapr will internally set epochs_early_stopping = vaeac.epochs such that early stopping does not occur.

Positive integer (default is NULL). If provided, then the vaeac model after every save_every_nth_epochth epoch will be saved.

String vector or NULL. Specifies the verbosity (printout detail level) through one or more of strings "basic", "progress", "convergence", "shapley" and "vS_details". "basic" (default) displays basic information about the computation which is being performed, in addition to some messages about parameters being sets or checks being unavailable due to specific input. ⁠"progress⁠ displays information about where in the calculation process the function currently is. #' "convergence" displays information on how close to convergence the Shapley value estimates are (only when iterative = TRUE) . "shapley" displays intermediate Shapley value estimates and standard deviations (only when iterative = TRUE) and the final estimates. "vS_details" displays information about the v_S estimates. This is most relevant for ⁠approach %in% c("regression_separate", "regression_surrogate", "vaeac"⁠). NULL means no printout. Note that any combination of four strings can be used. E.g. verbose = c("basic", "vS_details") will display basic information + details about the v(S)-estimation process.

List containing the extra parameters to the vaeac approach

List containing named entries. I.e., list(a = TRUE, b = FALSE).

Matrix (default is NULL). Matrix containing the coalitions that the vaeac model will be trained on, see specified_masks_mask_generator(). This parameter is used internally in shapr when we only consider a subset of coalitions, i.e., when n_coalitions < 2^{n_{\text{features}}}, and for group Shapley, i.e., when group is specified in explain().

Numeric array (default is NULL). Array of length equal to the height of mask_gen_coalitions containing the probabilities of sampling the corresponding coalitions in mask_gen_coalitions.

A data.table containing the training data. Categorical data must have class names 1,2,\dots,K.

Numeric (default is 0.5). Probability of masking a feature in the mcar_mask_generator() (MCAR = Missing Completely At Random). The MCAR masking scheme ensures that vaeac model can do arbitrary conditioning as all coalitions will be trained. masking_ratio will be overruled if mask_gen_coalitions is specified.

The number of features, i.e., the number of columns in the training data.

A data.table containing the training data. Categorical data must have class names 1,2,\dots,K.

String (default is make.names(Sys.time())). String containing, e.g., the name of the data distribution or additional parameter information. Used in the save name of the fitted model. If not provided, then a name will be generated based on base::Sys.time() to ensure a unique name. We use base::make.names() to ensure a valid file name for all operating systems.

String (default is base::tempdir()). String specifying a path to a folder where the function is to save the fitted vaeac model. Note that the path will be removed from the returned explain() object if vaeac.save_model = FALSE.

Logical (default is FALSE). If TRUE, then the vaeac model will be trained using cuda/GPU. If torch::cuda_is_available() is FALSE, the we fall back to use CPU. If FALSE, we use the CPU. Using a GPU for smaller tabular dataset often do not improve the efficiency. See vignette("installation", package = "torch") fo help to enable running on the GPU (only Linux and Windows).

Positive integer (default is 4). The number of different vaeac models to initiate in the start. Pick the best performing one after epochs_initiation_phase epochs (default is 2) and continue training that one.

Positive integer (default is 2). The number of epochs to run each of the n_vaeacs_initialize vaeac models before continuing to train only the best performing model.

Positive integer (default is 100). The number of epochs to train the final vaeac model. This includes epochs_initiation_phase, where the default is 2.

Positive integer (default is NULL). The training stops if there has been no improvement in the validation IWAE for epochs_early_stopping epochs. If the user wants the training process to be solely based on this training criterion, then epochs in explain() should be set to a large number. If NULL, then shapr will internally set epochs_early_stopping = vaeac.epochs such that early stopping does not occur.

Positive integer (default is NULL). If provided, then the vaeac model after every save_every_nth_epochth epoch will be saved.

Numeric (default is 0.25). Scalar between 0 and 1 indicating the ratio of instances from the input data which will be used as validation data. That is, val_ratio = 0.25 means that ⁠75%⁠ of the provided data is used as training data, while the remaining ⁠25%⁠ is used as validation data.

Positive integer (default is 25). The number of generated samples used to compute the IWAE criterion when validating the vaeac model on the validation data.

Positive integer (default is 3). The number of hidden layers in the neural networks of the masked encoder, full encoder, and decoder.

Positive integer (default is 32). The number of neurons in each hidden layer in the neural networks of the masked encoder, full encoder, and decoder.

Positive integer (default is 8). The number of dimensions in the latent space.

Positive numeric (default is 0.001). The learning rate used in the torch::optim_adam() optimizer.

Positive integer (default is 64). The number of samples to include in each batch during the training of the vaeac model. Used in torch::dataloader().

running_avg_n_values Positive integer (default is 5). The number of previous IWAE values to include when we compute the running means of the IWAE criterion.

An torch::nn_module() representing an activation function such as, e.g., torch::nn_relu() (default), torch::nn_leaky_relu(), torch::nn_selu(), or torch::nn_sigmoid().

Logical (default is TRUE). If TRUE, we apply identity skip connections in each layer, see skip_connection(). That is, we add the input X to the outcome of each hidden layer, so the output becomes X + activation(WX + b).

Logical (default is TRUE). If TRUE, we apply concatenate skip connections between the layers in the masked encoder and decoder. The first layer of the masked encoder will be linked to the last layer of the decoder. The second layer of the masked encoder will be linked to the second to last layer of the decoder, and so on.

Logical (default is FALSE). If TRUE, we apply batch normalization after the activation function. Note that if skip_conn_layer = TRUE, then the normalization is applied after the inclusion of the skip connection. That is, we batch normalize the whole quantity X + activation(WX + b).

Logical (default is TRUE). If TRUE, we apply paired sampling to the training batches. That is, the training observations in each batch will be duplicated, where the first instance will be masked by S while the second instance will be masked by \bar{S}. This ensures that the training of the vaeac model becomes more stable as the model has access to the full version of each training observation. However, this will increase the training time due to more complex implementation and doubling the size of each batch. See paired_sampler() for more information.

Numeric (default is 0.5). Probability of masking a feature in the mcar_mask_generator() (MCAR = Missing Completely At Random). The MCAR masking scheme ensures that vaeac model can do arbitrary conditioning as all coalitions will be trained. masking_ratio will be overruled if mask_gen_coalitions is specified.

Matrix (default is NULL). Matrix containing the coalitions that the vaeac model will be trained on, see specified_masks_mask_generator(). This parameter is used internally in shapr when we only consider a subset of coalitions, i.e., when n_coalitions < 2^{n_{\text{features}}}, and for group Shapley, i.e., when group is specified in explain().

Numeric array (default is NULL). Array of length equal to the height of mask_gen_coalitions containing the probabilities of sampling the corresponding coalitions in mask_gen_coalitions.

Numeric (default is 1e4). One of two hyperparameter values in the normal-gamma prior used in the masked encoder, see Section 3.3.1 in Olsen et al. (2022).

Numeric (default is 1e-4). One of two hyperparameter values in the normal-gamma prior used in the masked encoder, see Section 3.3.1 in Olsen et al. (2022).

Logical (default is FALSE). If TRUE, then the data is stored together with the model. Useful if one are to continue to train the model later using vaeac_train_model_continue().

Logical (default is FALSE). If we are to \log transform all continuous features before sending the data to vaeac(). The vaeac model creates unbounded Monte Carlo sample values. Thus, if the continuous features are strictly positive (as for, e.g., the Burr distribution and Abalone data set), it can be advantageous to \log transform the data to unbounded form before using vaeac. If TRUE, then vaeac_postprocess_data() will take the \exp of the results to get back to strictly positive values when using the vaeac model to impute missing values/generate the Monte Carlo samples.

String (default is best). The name of the vaeac model (snapshots from different epochs) to use when generating the Monte Carlo samples. The standard choices are: "best" (epoch with lowest IWAE), "best_running" (epoch with lowest running IWAE, see vaeac.running_avg_n_values), and last (the last epoch). Note that additional choices are available if vaeac.save_every_nth_epoch is provided. For example, if vaeac.save_every_nth_epoch = 5, then vaeac.which_vaeac_model can also take the values "epoch_5", "epoch_10", "epoch_15", and so on.

String vector or NULL. Specifies the verbosity (printout detail level) through one or more of strings "basic", "progress", "convergence", "shapley" and "vS_details". "basic" (default) displays basic information about the computation which is being performed, in addition to some messages about parameters being sets or checks being unavailable due to specific input. ⁠"progress⁠ displays information about where in the calculation process the function currently is. #' "convergence" displays information on how close to convergence the Shapley value estimates are (only when iterative = TRUE) . "shapley" displays intermediate Shapley value estimates and standard deviations (only when iterative = TRUE) and the final estimates. "vS_details" displays information about the v_S estimates. This is most relevant for ⁠approach %in% c("regression_separate", "regression_surrogate", "vaeac"⁠). NULL means no printout. Note that any combination of four strings can be used. E.g. verbose = c("basic", "vS_details") will display basic information + details about the v(S)-estimation process.

Positive integer (default is 1). Seed for reproducibility. Specifies the seed before any randomness based code is being run.

List of extra parameters, currently not used.

List containing named entries. I.e., list(a = 1, b = 2).

List containing named entries. I.e., list(a = 0.2, b = 10^3).

List containing named entries. I.e., list(a = 0.2, b = 0.9).

String (default is base::tempdir()). String specifying a path to a folder where the function is to save the fitted vaeac model. Note that the path will be removed from the returned explain() object if vaeac.save_model = FALSE.

String (default is make.names(Sys.time())). String containing, e.g., the name of the data distribution or additional parameter information. Used in the save name of the fitted model. If not provided, then a name will be generated based on base::Sys.time() to ensure a unique name. We use base::make.names() to ensure a valid file name for all operating systems.

Logical (default is FALSE). If TRUE, then the data is stored together with the model. Useful if one are to continue to train the model later using vaeac_train_model_continue().

Positive integer (default is 100). The number of epochs to train the final vaeac model. This includes epochs_initiation_phase, where the default is 2.

Positive integer (default is NULL). If provided, then the vaeac model after every save_every_nth_epochth epoch will be saved.

The object size of the x_train object.

String vector or NULL. Specifies the verbosity (printout detail level) through one or more of strings "basic", "progress", "convergence", "shapley" and "vS_details". "basic" (default) displays basic information about the computation which is being performed, in addition to some messages about parameters being sets or checks being unavailable due to specific input. ⁠"progress⁠ displays information about where in the calculation process the function currently is. #' "convergence" displays information on how close to convergence the Shapley value estimates are (only when iterative = TRUE) . "shapley" displays intermediate Shapley value estimates and standard deviations (only when iterative = TRUE) and the final estimates. "vS_details" displays information about the v_S estimates. This is most relevant for ⁠approach %in% c("regression_separate", "regression_surrogate", "vaeac"⁠). NULL means no printout. Note that any combination of four strings can be used. E.g. verbose = c("basic", "vS_details") will display basic information + details about the v(S)-estimation process.

String (default is best). The name of the vaeac model (snapshots from different epochs) to use when generating the Monte Carlo samples. The standard choices are: "best" (epoch with lowest IWAE), "best_running" (epoch with lowest running IWAE, see vaeac.running_avg_n_values), and last (the last epoch). Note that additional choices are available if vaeac.save_every_nth_epoch is provided. For example, if vaeac.save_every_nth_epoch = 5, then vaeac.which_vaeac_model can also take the values "epoch_5", "epoch_10", "epoch_15", and so on.

Positive integer (default is 100). The number of epochs to train the final vaeac model. This includes epochs_initiation_phase, where the default is 2.

Positive integer (default is NULL). If provided, then the vaeac model after every save_every_nth_epochth epoch will be saved.

Array of strings containing the feature names of the vaeac model.

Array of strings containing the feature names to compare with.

A torch_tensor of dimension n_observation x n_features containing the data.

A torch tensor of dimension n_features containing the one hot sizes of the n_features features. That is, if the ith feature is a categorical feature with 5 levels, then one_hot_max_sizes[i] = 5. While the size for continuous features can either be 0 or 1.

A torch_tensor contain the data of shape N x p, where N and p are the number of observations and features, respectively.

A torch tensor of dimension n_features containing the one hot sizes of the n_features features. That is, if the ith feature is a categorical feature with 5 levels, then one_hot_max_sizes[i] = 5. While the size for continuous features can either be 0 or 1.

The batch we want to check if has the right size, and if not extend it until it has the right size.

A torch::dataloader() object from which we can create an iterator object and load data to extend the batch.

Integer. The number of samples to include in each batch.

The base::environment() where the objects are stored.

A data.table containing the training data. Categorical data must have class names 1,2,\dots,K.

Logical (default is FALSE). If we are to \log transform all continuous features before sending the data to vaeac(). The vaeac model creates unbounded Monte Carlo sample values. Thus, if the continuous features are strictly positive (as for, e.g., the Burr distribution and Abalone data set), it can be advantageous to \log transform the data to unbounded form before using vaeac. If TRUE, then vaeac_postprocess_data() will take the \exp of the results to get back to strictly positive values when using the vaeac model to impute missing values/generate the Monte Carlo samples.

Numeric (default is 0.25). Scalar between 0 and 1 indicating the ratio of instances from the input data which will be used as validation data. That is, val_ratio = 0.25 means that ⁠75%⁠ of the provided data is used as training data, while the remaining ⁠25%⁠ is used as validation data.

Positive integer (default is 64). The number of samples to include in each batch during the training of the vaeac model. Used in torch::dataloader().

Logical (default is TRUE). If TRUE, we apply paired sampling to the training batches. That is, the training observations in each batch will be duplicated, where the first instance will be masked by S while the second instance will be masked by \bar{S}. This ensures that the training of the vaeac model becomes more stable as the model has access to the full version of each training observation. However, this will increase the training time due to more complex implementation and doubling the size of each batch. See paired_sampler() for more information.

String (default is make.names(Sys.time())). String containing, e.g., the name of the data distribution or additional parameter information. Used in the save name of the fitted model. If not provided, then a name will be generated based on base::Sys.time() to ensure a unique name. We use base::make.names() to ensure a valid file name for all operating systems.

Positive integer (default is 3). The number of hidden layers in the neural networks of the masked encoder, full encoder, and decoder.

Positive integer (default is 32). The number of neurons in each hidden layer in the neural networks of the masked encoder, full encoder, and decoder.

Positive integer (default is 8). The number of dimensions in the latent space.

Positive numeric (default is 0.001). The learning rate used in the torch::optim_adam() optimizer.

Positive integer (default is 100). The number of epochs to train the final vaeac model. This includes epochs_initiation_phase, where the default is 2.

Positive integer (default is NULL). If provided, then the vaeac model after every save_every_nth_epochth epoch will be saved.

String (default is base::tempdir()). String specifying a path to a folder where the function is to save the fitted vaeac model. Note that the path will be removed from the returned explain() object if vaeac.save_model = FALSE.

Numeric array (optional) containing the indices of the training observations. There are conducted no checks to validate the indices.

Numeric array (optional) containing the indices of the validation observations. #' There are conducted no checks to validate the indices.

A list of explain() objects applied to the same data, model, and vaeac must be the used approach. If the entries in the list is named, then the function use these names. Otherwise, it defaults to the approach names (with integer suffix for duplicates) for the explanation objects in explanation_list.

String (default is make.names(Sys.time())). String containing, e.g., the name of the data distribution or additional parameter information. Used in the save name of the fitted model. If not provided, then a name will be generated based on base::Sys.time() to ensure a unique name. We use base::make.names() to ensure a valid file name for all operating systems.

String (default is base::tempdir()). String specifying a path to a folder where the function is to save the fitted vaeac model. Note that the path will be removed from the returned explain() object if vaeac.save_model = FALSE. Furthermore, the model cannot be moved from its original folder if we are to use the vaeac_train_model_continue() function to continue training the model.

List or String (default is NULL). 1) Either a list of class vaeac, i.e., the list stored in explanation$internal$parameters$vaeac where explanation is the returned list from an earlier call to the explain() function. 2) A string containing the path to where the vaeac model is stored on disk, for example, explanation$internal$parameters$vaeac$models$best.

Logical (default is FALSE). If TRUE, then the vaeac model will be trained using cuda/GPU. If torch::cuda_is_available() is FALSE, the we fall back to use CPU. If FALSE, we use the CPU. Using a GPU for smaller tabular dataset often do not improve the efficiency. See vignette("installation", package = "torch") fo help to enable running on the GPU (only Linux and Windows).

Positive integer (default is 2). The number of epochs to run each of the vaeac.n_vaeacs_initialize vaeac models before continuing to train only the best performing model.

Positive integer (default is NULL). The training stops if there has been no improvement in the validation IWAE for vaeac.epochs_early_stopping epochs. If the user wants the training process to be solely based on this training criterion, then vaeac.epochs in explain() should be set to a large number. If NULL, then shapr will internally set vaeac.epochs_early_stopping = vaeac.epochs such that early stopping does not occur.

Positive integer (default is NULL). If provided, then the vaeac model after every vaeac.save_every_nth_epochth epoch will be saved.

Numeric (default is 0.25). Scalar between 0 and 1 indicating the ratio of instances from the input data which will be used as validation data. That is, vaeac.val_ratio = 0.25 means that ⁠75%⁠ of the provided data is used as training data, while the remaining ⁠25%⁠ is used as validation data.