plot.EBM: Interpret plots for fitted EBM objects

Description

Provides an interactive visualization for a given explanation(s).

Usage

# S3 method for EBM
plot(
  x,
  term = NULL,
  local = FALSE,
  X = NULL,
  y = NULL,
  init_score = NULL,
  interactive = FALSE,
  n_terms = NULL,
  geom = c("point", "col", "bar"),
  mapping = NULL,
  aesthetics = list(),
  horizontal = FALSE,
  uncertainty = TRUE,
  width = 0.5,
  alpha = 0.5,
  fill = "grey",
  display = c("viewer", "markdown", "url"),
  viewer = c("browser", "rstudio"),
  full_dashboard = FALSE,
  ...
)

Value

When interactive = FALSE (the default), the output is either a ggplot object when visualizing term importance scores or main effects, or a trellis object when visualizing pairwise interaction effects. When interactive = TRUE, the return value depends on display argument. When display = "url", a character string is returned giving the URL for displaying the HTML-based visualization. Otherwise, the results are viewed as requested (i.e., in a browser, built-in viewer, or displayed in rendered HTML output).

Arguments

x

A fitted ebm() object.

term

Character string specifying which term to plot. For interaction effect, you can supply a pair (e.g., term = c("x1", "x2")). Default is NULL which will just display the overall importance of each term.

local

Logocial indicating whether to display local explanations (TRUE) or global explanations (FALSE). Default is FALSE.

X

Data frame or matrix of samples. Unless display = "url" or full_dashboard = TRUE, then X can only contain a single row.

y

Optional vector of response values corresponding to X.

init_score

Optional. Either a model that can generate scores or per-sample initialization score. If samples scores it should be the same length as X.

interactive

Logical indicating whether to produce an interactive plot based on HTML. Default is FALSE. Currently, only interactive graphics (i.e., interactive = TRUE) are available for multiclass outcomes.

n_terms

Integer specifying the maximum number of variable importance scores to plot. Default is NULL which corresponds to all terms in the fitted model.

geom

Character string specifying which type of plot to construct for terms associated with categorical features. Current options are:

geom = "bar" (or "col") uses geom_col to construct a bar chart of the scores.
geom = "point" uses geom_point to construct a Cleveland dot plot of the term scores.

Default is "point".

mapping

Set of aesthetic mappings created by aes-related functions and/or tidy eval helpers. See example usage below.

aesthetics

List specifying additional arguments passed on to layer. These are often aesthetics, used to set an aesthetic to a fixed value, likecolour = "red" or size = 3. See example usage below.

horizontal

Logical indicating whether or not term plots for categorical features should be flipped horzintally. Default is FALSE.

uncertainty

Logical indicating whether or not to also display uncertainty via error bars on the main effect plots. Default is TRUE. Not very useful unless outer_bags > 1 when calling ebm().

width

Numeric specifying the width of the error bars displayed in bar/ dot plots for categorical features. Default is 0.5.

alpha

Numeric between 0 and 1 specifying the level of transparency to use when displaying uncertainty in plots for continuous features. Default is 0.5.

fill

Character string specifying the fill color to use when displaying uncertainty in plots for continuous features. Default is "grey".

display

Character string specifying how the results should be displayed whenever interactive = TRUE. Available options are "viewer" (e.g., RStudio viewer browser), "markdown" (e.g., for vingettes, Quarto, or Rmarkdown documents), or "url" (e.g., to print a URL which can be pasted into a browser). When display = "url", a URL for viewing the entire interpret dashboard is provided (i.e., the term and full_dashboard arguments are ignored).

viewer

Character string specifying how the results should be viewed. Current choices are "broswer", which calls utils::browseURL() to display the results in an HTML browser, or "rstudio" for displaying the results within the Viewer pane in an active RStudio session. Also works in VS Code. Default is "browser".

full_dashboard

Logical indicating whether or not to display the full interpret dashboard. Default is FALSE. Only works when display = "viewer" or display = "url" (e.g., paste the resulting URL in your browser).

...

Additional optional arguments. Currently only passed onto levelplot() for heatmaps of interaction effects.