plot_shap_waterfall-methods: Create SHAP waterfall plot

In familiar: End-to-End Automated Machine Learning and Model Evaluation

Create SHAP waterfall plot

Description

This method creates plots that show a waterfall of SHAP values obtained from the data stored in a familiarCollection object.

Usage

plot_shap_waterfall(
  object,
  draw = FALSE,
  dir_path = NULL,
  split_by = NULL,
  x_axis_by = NULL,
  y_axis_by = NULL,
  facet_by = NULL,
  facet_wrap_cols = NULL,
  ggtheme = NULL,
  gradient_palette = NULL,
  x_label = waiver(),
  y_label = waiver(),
  legend_label = waiver(),
  plot_title = waiver(),
  plot_sub_title = waiver(),
  caption = NULL,
  limit_n_features = waiver(),
  x_range = NULL,
  x_n_breaks = 5L,
  x_breaks = NULL,
  width = waiver(),
  height = waiver(),
  units = waiver(),
  export_collection = FALSE,
  ...
)

## S4 method for signature 'ANY'
plot_shap_waterfall(
  object,
  draw = FALSE,
  dir_path = NULL,
  split_by = NULL,
  x_axis_by = NULL,
  y_axis_by = NULL,
  facet_by = NULL,
  facet_wrap_cols = NULL,
  ggtheme = NULL,
  gradient_palette = NULL,
  x_label = waiver(),
  y_label = waiver(),
  legend_label = waiver(),
  plot_title = waiver(),
  plot_sub_title = waiver(),
  caption = NULL,
  limit_n_features = waiver(),
  x_range = NULL,
  x_n_breaks = 5L,
  x_breaks = NULL,
  width = waiver(),
  height = waiver(),
  units = waiver(),
  export_collection = FALSE,
  ...
)

## S4 method for signature 'familiarCollection'
plot_shap_waterfall(
  object,
  draw = FALSE,
  dir_path = NULL,
  split_by = NULL,
  x_axis_by = NULL,
  y_axis_by = NULL,
  facet_by = NULL,
  facet_wrap_cols = NULL,
  ggtheme = NULL,
  gradient_palette = NULL,
  x_label = waiver(),
  y_label = waiver(),
  legend_label = waiver(),
  plot_title = waiver(),
  plot_sub_title = waiver(),
  caption = NULL,
  limit_n_features = waiver(),
  x_range = NULL,
  x_n_breaks = 5L,
  x_breaks = NULL,
  width = waiver(),
  height = waiver(),
  units = waiver(),
  export_collection = FALSE,
  ...
)

Arguments

object	familiarCollection object, or one or more familiarData objects, that will be internally converted to a familiarCollection object. It is also possible to provide a familiarEnsemble or one or more familiarModel objects together with the data from which data is computed prior to export. Paths to such files can also be provided. Additionally, some familiarData objects can be created from prediction tables (familiarDataElementPredictionTable). Other familiarData objects can be created from data (dataObject, or data.table). Please check details for more information.
draw	(optional) Draws the plot if TRUE.
dir_path	(optional) Path to the directory where created plots are saved to. Output is saved in the explanation subdirectory. If NULL no figures are saved, but are returned instead.
split_by	(optional) Splitting variables. This refers to column names on which datasets are split. A separate figure is created for each split. See details for available variables.
x_axis_by	(optional) Variable plotted along the x-axis of a plot. The variable cannot overlap with variables provided to the split_by and y_axis_by arguments (if used), but may overlap with other arguments. Only one variable is allowed for this argument. See details for available variables.
y_axis_by	(optional) Variable plotted along the y-axis of a plot. The variable cannot overlap with variables provided to the split_by and x_axis_by arguments (if used), but may overlap with other arguments. Only one variable is allowed for this argument. See details for available variables.
facet_by	(optional) Variables used to determine how and if facets of each figure appear. In case the facet_wrap_cols argument is NULL, the first variable is used to define columns, and the remaing variables are used to define rows of facets. The variables cannot overlap with those provided to the split_by argument, but may overlap with other arguments. See details for available variables.
facet_wrap_cols	(optional) Number of columns to generate when facet wrapping. If NULL, a facet grid is produced instead.
ggtheme	(optional) ggplot theme to use for plotting.
gradient_palette	(optional) Divergent palette used to colour the elements of waterfall plots. familiar has a default palette. Other palettes are supported by the paletteer package, grDevices::palette.pals() (requires R >= 4.0.0), grDevices::hcl.pals() (requires R >= 3.6.0) and rainbow, heat.colors, terrain.colors, topo.colors and cm.colors, which correspond to the palettes of the same name in grDevices. You may also specify your own palette by providing a vector of colour names listed by grDevices::colors() or through hexadecimal RGB strings.
x_label	(optional) Label to provide to the x-axis. If NULL, no label is shown.
y_label	(optional) Label to provide to the y-axis. If NULL, no label is shown.
legend_label	(optional) Label to provide to the legend. If NULL, the legend will not have a name.
plot_title	(optional) Label to provide as figure title. If NULL, no title is shown.
plot_sub_title	(optional) Label to provide as figure subtitle. If NULL, no subtitle is shown.
caption	(optional) Label to provide as figure caption. If NULL, no caption is shown.
limit_n_features	(optional) The number of features that should be included in the plot. Only the most important features are shown. By default, the number of features is not limited.
x_range	(optional) Value range for the x-axis.
x_n_breaks	(optional) Number of breaks to show on the x-axis of the plot. x_n_breaks is used to determine the x_breaks argument in case it is unset.
x_breaks	(optional) Break points on the x-axis of the plot.
width	(optional) Width of the plot. A default value is derived from the number of facets.
height	(optional) Height of the plot. A default value is derived from the number of features and the number of facets.
units	(optional) Plot size unit. Either cm (default), mm or ⁠in⁠.
export_collection	(optional) Exports the collection if TRUE.
...	Arguments passed on to extract_performance, as_familiar_collection, ggplot2::ggsave data A dataObject object, data.table or data.frame that constitutes the data that are assessed. is_pre_processed Flag that indicates whether the data was already pre-processed externally, e.g. normalised and clustered. Only used if the data argument is a data.table or data.frame. cl Cluster created using the parallel package. This cluster is then used to speed up computation through parallellisation. evaluation_times One or more time points that are used for in analysis of survival problems when data has to be assessed at a set time, e.g. calibration. If not provided explicitly, this parameter is read from settings used at creation of the underlying familiarModel objects. Only used for survival outcomes. ensemble_method Method for ensembling predictions from models for the same sample. Available methods are: median (default): Use the median of the predicted values as the ensemble value for a sample. mean: Use the mean of the predicted values as the ensemble value for a sample. metric One or more metrics for assessing model performance. See the vignette on performance metrics for the available metrics. If not provided explicitly, this parameter is read from settings used at creation of the underlying familiarModel objects. verbose Flag to indicate whether feedback should be provided on the computation and extraction of various data elements. message_indent Number of indentation steps for messages shown during computation and extraction of various data elements. detail_level (optional) Sets the level at which results are computed and aggregated. ensemble: Results are computed at the ensemble level, i.e. over all models in the ensemble. This means that, for example, bias-corrected estimates of model performance are assessed by creating (at least) 20 bootstraps and computing the model performance of the ensemble model for each bootstrap. hybrid (default): Results are computed at the level of models in an ensemble. This means that, for example, bias-corrected estimates of model performance are directly computed using the models in the ensemble. If there are at least 20 trained models in the ensemble, performance is computed for each model, in contrast to ensemble where performance is computed for the ensemble of models. If there are less than 20 trained models in the ensemble, bootstraps are created so that at least 20 point estimates can be made. model: Results are computed at the model level. This means that, for example, bias-corrected estimates of model performance are assessed by creating (at least) 20 bootstraps and computing the performance of the model for each bootstrap. Note that each level of detail has a different interpretation for bootstrap confidence intervals. For ensemble and model these are the confidence intervals for the ensemble and an individual model, respectively. That is, the confidence interval describes the range where an estimate produced by a respective ensemble or model trained on a repeat of the experiment may be found with the probability of the confidence level. For hybrid, it represents the range where any single model trained on a repeat of the experiment may be found with the probability of the confidence level. By definition, confidence intervals obtained using hybrid are at least as wide as those for ensemble. hybrid offers the correct interpretation if the goal of the analysis is to assess the result of a single, unspecified, model. hybrid is generally computationally less expensive then ensemble, which in turn is somewhat less expensive than model. A non-default detail_level parameter can be specified for separate evaluation steps by providing a parameter value in a named list with data elements, e.g. list("auc_data"="ensemble", "model_performance"="hybrid"). This parameter can be set for the following data elements: auc_data, decision_curve_analyis, model_performance, permutation_vimp, ice_data, prediction_data and confusion_matrix. If results are computed from 10 samples or fewer, ensemble is automatically used. This prevents issues where evaluation steps do not have a required minimum number of samples for hybrid or model. estimation_type (optional) Sets the type of estimation that should be possible. This has the following options: point: Point estimates. bias_correction or bc: Bias-corrected estimates. A bias-corrected estimate is computed from (at least) 20 point estimates, and familiar may bootstrap the data to create them. bootstrap_confidence_interval or bci (default): Bias-corrected estimates with bootstrap confidence intervals (Efron and Hastie, 2016). The number of point estimates required depends on the confidence_level parameter, and familiar may bootstrap the data to create them. As with detail_level, a non-default estimation_type parameter can be specified for separate evaluation steps by providing a parameter value in a named list with data elements, e.g. list("auc_data"="bci", "model_performance"="point"). This parameter can be set for the following data elements: auc_data, decision_curve_analyis, model_performance, permutation_vimp, ice_data, and prediction_data. aggregate_results (optional) Flag that signifies whether results should be aggregated during evaluation. If estimation_type is bias_correction or bc, aggregation leads to a single bias-corrected estimate. If estimation_type is bootstrap_confidence_interval or bci, aggregation leads to a single bias-corrected estimate with lower and upper boundaries of the confidence interval. This has no effect if estimation_type is point. The default value is equal to TRUE except when assessing metrics to assess model performance, as the default violin plot requires underlying data. As with detail_level and estimation_type, a non-default aggregate_results parameter can be specified for separate evaluation steps by providing a parameter value in a named list with data elements, e.g. list("auc_data"=TRUE, , "model_performance"=FALSE). This parameter exists for the same elements as estimation_type. confidence_level (optional) Numeric value for the level at which confidence intervals are determined. In the case bootstraps are used to determine the confidence intervals bootstrap estimation, familiar uses the rule of thumb n = 20 / ci.level to determine the number of required bootstraps. The default value is 0.95. bootstrap_ci_method (optional) Method used to determine bootstrap confidence intervals (Efron and Hastie, 2016). The following methods are implemented: percentile (default): Confidence intervals obtained using the percentile method. bc: Bias-corrected confidence intervals. Note that the standard method is not implemented because this method is often not suitable due to non-normal distributions. The bias-corrected and accelerated (BCa) method is not implemented yet. familiar_data_names Names of the dataset(s). Only used if the object parameter is one or more familiarData objects. collection_name Name of the collection. device Device to use. Can either be a device function (e.g. png), or one of "eps", "ps", "tex" (pictex), "pdf", "jpeg", "tiff", "png", "bmp", "svg" or "wmf" (windows only). If NULL (default), the device is guessed based on the filename extension. scale Multiplicative scaling factor. dpi Plot resolution. Also accepts a string input: "retina" (320), "print" (300), or "screen" (72). Only applies when converting pixel units, as is typical for raster output types. limitsize When TRUE (the default), ggsave() will not save images larger than 50x50 inches, to prevent the common error of specifying dimensions in pixels. bg Background colour. If NULL, uses the plot.background fill value from the plot theme. create.dir Whether to create new directories if a non-existing directory is specified in the filename or path (TRUE) or return an error (FALSE, default). If FALSE and run in an interactive session, a prompt will appear asking to create a new directory when necessary.

Details

This function creates SHAP waterfall plots, which show the individual marginal contributions of feature values to the predicted value.

Available splitting variables are: vimp_method, learner, data_set, evaluation_time (survival outcome only) and positive_class (categorical outcomes), sample_id. The default for is to facet by evaluation_time or positive_class, and split by vimp_method, learner, data_set, and sample_id. color_by is not used.

Labelling methods such as set_vimp_method_names or set_learner_names can be applied to the familiarCollection object to update labels, and order the output in the figure.

Value

NULL or list of plot objects, if dir_path is NULL.

familiar documentation built on May 23, 2026, 1:07 a.m.