ale_ixn {ale}

Create and return ALE interaction data, statistics, and plots

Description

This is the central function that manages the creation of ALE data and plots for two-way ALE interactions. For simple one-way ALE, see ale(). See documentation there for functionality shared between both functions.

For details, see the introductory vignette for this package or the details and examples below.

For the plots, n_y_quant is the number of quantiles into which to divide the predicted variable (y). The middle quantiles are grouped specially:

• The middle quantile is the first confidence interval of median_band_pct (median_band_pct[1]) around the median. This middle quantile is special because it generally represents no meaningful interaction.

• The quantiles above and below the middle are extended from the borders of the middle quantile to the regular borders of the other quantiles.

There will always be an odd number of quantiles: the special middle quantile plus an equal number of quantiles on each side of it. If n_y_quant is even, then a middle quantile will be added to it. If n_y_quant is odd, then the number specified will be used, including the middle quantile.

Usage

ale_ixn(
  data,
  model,
  x1_cols = NULL,
  x2_cols = NULL,
  y_col = NULL,
  ...,
  parallel = parallel::detectCores(logical = FALSE) - 1,
  model_packages = as.character(NA),
  output = c("plots", "data"),
  pred_fun = function(object, newdata, type = pred_type) {
     stats::predict(object =
    object, newdata = newdata, type = type)
 },
  pred_type = "response",
  x_intervals = 100,
  relative_y = "median",
  y_type = NULL,
  median_band_pct = c(0.05, 0.5),
  rug_sample_size = 500,
  min_rug_per_interval = 1,
  ale_xs = NULL,
  n_x1_int = 20,
  n_x2_int = 20,
  n_y_quant = 10,
  compact_plots = FALSE,
  silent = FALSE
)

Arguments

data

See documentation for ale()

model

See documentation for ale()

x1_cols, x2_cols

character. Vectors of column names from data for which two-way interaction ALE data is to be calculated. ALE data will be calculated for each x1 column interacting with each x2 column. x1_cols can be of any standard datatype (logical, factor, or numeric) but x2_cols can only be numeric. If ixn is TRUE, then both values must be provided.

y_col

See documentation for ale()

...

not used. Inserted to require explicit naming of subsequent arguments.

parallel

See documentation for ale()

model_packages

See documentation for ale()

output

See documentation for ale()

pred_fun, pred_type

See documentation for ale()

x_intervals

See documentation for ale()

relative_y

See documentation for ale()

y_type

See documentation for ale()

median_band_pct

See documentation for ale()

rug_sample_size, min_rug_per_interval

See documentation for ale()

ale_xs

See documentation for ale()

n_x1_int, n_x2_int

positive scalar integer. Number of intervals for the x1 or x2 axes respectively for interaction plot. These values are ignored if x1 or x2 are not numeric (i.e, if they are logical or factors).

n_y_quant

positive scalar integer. Number of intervals over which the range of y values is divided for the colour bands of the interaction plot. See details.

compact_plots

See documentation for ale()

silent

See documentation for ale()

Value

list of ALE interaction data tibbles and plots. The list has two levels of depth:

• The first level is named by the x1 variables.

• Within each x1 variable list, the second level is named by the x2 variables.

• Within each x1-x2 list element, the data or plot is returned as requested in the output argument.

Examples

set.seed(0)
diamonds_sample <- ggplot2::diamonds[sample(nrow(ggplot2::diamonds), 1000), ]

# Create a GAM model with flexible curves to predict diamond price
# Smooth all numeric variables and include all other variables
gam_diamonds <- mgcv::gam(
  price ~ s(carat) + s(depth) + s(table) + s(x) + s(y) + s(z) +
    cut + color + clarity,
  data = diamonds_sample
)
summary(gam_diamonds)


# ALE two-way interactions
ale_ixn_gam_diamonds <- ale_ixn(
  diamonds_sample, gam_diamonds,
  parallel = 2  # CRAN limit (delete this line on your own computer)
)

# Print interaction plots
ale_ixn_gam_diamonds$plots |>
  # extract list of x1 ALE outputs
  purrr::walk(\(.x1) {
    # plot all x2 plots in each .x1 element
    patchwork::wrap_plots(.x1) |>
      print()
  })