In tidymodels/tune: Tidy Tuning Tools

if (rlang::is_installed(c("tidymodels", "kknn", "modeldata", "splines2"))) {
  run <- TRUE
} else {
  cv_splits <- NULL
  run <- FALSE
}

knitr::opts_chunk$set(
  eval = run,
  digits = 3,
  collapse = TRUE,
  comment = "#>"
)
options(digits = 3)
library(tidymodels)
library(kknn)
theme_set(theme_bw())
doParallel::registerDoParallel()

Introduction

The tune package helps optimize the modeling process. Users can tag arguments in recipes and model objects for optimization. The search routines in tune can discover these arguments and evaluate candidate values until a combination with good performance is found.

As an example, let's model the Ames housing data:

library(tidymodels)

data(ames)

set.seed(4595)
data_split <- ames %>%
  mutate(Sale_Price = log10(Sale_Price)) %>%
  initial_split(strata = Sale_Price)
ames_train <- training(data_split)
ames_test  <- testing(data_split)

For simplicity, the sale price of a house will be modeled as a function of its geo-location. These predictors appear to have nonlinear relationships with the outcome:

ames_train %>% 
  dplyr::select(Sale_Price, Longitude, Latitude) %>% 
  tidyr::pivot_longer(cols = c(Longitude, Latitude), 
                      names_to = "predictor", values_to = "value") %>% 
  ggplot(aes(x = value, Sale_Price)) + 
  geom_point(alpha = .2) + 
  geom_smooth(se = FALSE) + 
  facet_wrap(~ predictor, scales = "free_x")

These two predictors could be modeled using natural splines in conjunction with a linear model. The amount of "wiggliness" in these splines is determined by the degrees of freedom. An appropriate value of this parameter cannot be analytically determined from the data, so it is a tuning parameter (a.k.a. a hyper-parameter). A common approach is to use resampling to estimate model performance over different values of these parameters and use these results to set reasonable values.

We can tag these parameters for optimization using the tune() function:

ames_rec <- 
  recipe(Sale_Price ~ Gr_Liv_Area + Longitude + Latitude, data = ames_train) %>% 
  step_log(Gr_Liv_Area, base = 10) %>% 
  step_spline_natural(Longitude, Latitude, deg_free = tune())

The package can detect these parameters and optimize them.

However, based on the plot above, the potential amount of non-linearity between the sale price and the predictors might be different. For example, longitude might require more flexibility than latitude. The recipe above would constrain the nonlinearity of the predictors to be the same. We can probably do better than that.

To accomplish this, individual step_spline_natural() terms can be added to the recipe for each predictor. However, we want these to be identifiable; using the same syntax as above, we can't tell the difference between the two deg_free parameters.

tune() has an option to provide a text annotation so that each tuning parameter has a unique identifier:

ames_rec <- 
  recipe(Sale_Price ~ Gr_Liv_Area + Longitude + Latitude, data = ames_train) %>% 
  step_log(Gr_Liv_Area, base = 10) %>% 
  step_spline_natural(Longitude, deg_free = tune("long df")) %>% 
  step_spline_natural(Latitude,  deg_free = tune("lat df"))

The function extract_parameter_set_dials() can detect and collect the parameters that have been flagged for tuning.

extract_parameter_set_dials(ames_rec)

The dials package has default ranges for many parameters. The generic parameter function for deg_free() has a fairly small range:

deg_free()

However, there is a function in dials that is more appropriate for splines:

spline_degree()

The parameter objects can be easily changed using the update() function:

ames_param <- 
  ames_rec %>% 
  extract_parameter_set_dials() %>% 
  update(
    `long df` = spline_degree(), 
    `lat df` = spline_degree()
  )
ames_param

Grid Search

Grid search uses a pre-defined set of candidate parameters and evaluates these using resampling. The basic ingredients are:

• A grid of candidate values to evaluate.

• One or more performance metrics for quantifying how well the model works.

• A resampling scheme that can be used to appropriately measure performance (which could be a simple validation set).

To make the grid, a data frame is needed with column names matching the "identifier" column above. There are several functions in dials to created grids (named grid_*()). For example, a space-filling design can be created by:

spline_grid <- grid_max_entropy(ames_param, size = 10)
spline_grid

Alternately, expand.grid() also works to create a regular grid:

df_vals <- seq(2, 18, by = 2)
# A regular grid:
spline_grid <- expand.grid(`long df` = df_vals, `lat df` = df_vals)

Note that a 2-degree-of-freedom model is a simple quadratic fit.

There are two other ingredients that are required before tuning.

First is a model specification. Using functions in parsnip, a basic linear model can be used:

lm_mod <- linear_reg() %>% set_engine("lm")

No tuning parameters here.

As mentioned above, a resampling specification is also needed. The Ames data set is large enough to use simple 10-fold cross-validation:

set.seed(2453)
cv_splits <- vfold_cv(ames_train, v = 10, strata = Sale_Price)

The root mean squared error will be used to measure performance (and this is the default for regression problems).

Using these objects, tune_grid() can be used^[A simple R model formula could have been used here, such as Sale_Price ~ log10(Gr_Liv_Area) + Longitude + Latitude. A recipe is not required.]:

ames_res <- tune_grid(lm_mod, ames_rec, resamples = cv_splits, grid = spline_grid)

The object is similar to the rsample object but with one or more extra columns:

ames_res

The .metrics column has all of the holdout performance estimates^[the tune package has default measures of performance that it uses if none are specified. Here the RMSE and R² are estimated. This can be changed using the metrics option.] for each parameter combination:

ames_res$.metrics[[1]]

To get the average metric value for each parameter combination, collect_metrics() can be put to use:

estimates <- collect_metrics(ames_res)
estimates

The values in the mean column are the averages of the r nrow(cv_splits) resamples. The best RMSE values corresponded to:

rmse_vals <- 
  estimates %>% 
  dplyr::filter(.metric == "rmse") %>% 
  arrange(mean)
rmse_vals

Smaller degrees of freedom values correspond to more linear functions, but the grid search indicates that more nonlinearity is better. What was the relationship between these two parameters and RMSE?

autoplot(ames_res, metric = "rmse")

Interestingly, latitude does not do well with degrees of freedom less than 8. How nonlinear are the optimal degrees of freedom?

Let's plot these spline functions over the data for both good and bad values of deg_free:

ames_train %>% 
  dplyr::select(Sale_Price, Longitude, Latitude) %>% 
  tidyr::pivot_longer(cols = c(Longitude, Latitude), 
                      names_to = "predictor", values_to = "value") %>% 
  ggplot(aes(x = value, Sale_Price)) + 
  geom_point(alpha = .2) + 
  geom_smooth(se = FALSE, method = lm, formula = y ~ splines::ns(x, df = 3),  col = "red")  + 
  geom_smooth(se = FALSE, method = lm, formula = y ~ splines::ns(x, df = 16)) +
  scale_y_log10() +
  facet_wrap(~ predictor, scales = "free_x")

Looking at these plots, the smaller degrees of freedom (red) are clearly under-fitting. Visually, the more complex splines (blue) might indicate that there is overfitting but this would result in poor RMSE values when computed on the hold-out data.

Based on these results, a new recipe would be created with the optimized values (using the entire training set) and this would be combined with a linear model created form the entire training set.

Model Optimization

Instead of a linear regression, a nonlinear model might provide good performance. A K-nearest-neighbor fit will also be optimized. For this example, the number of neighbors and the distance weighting function will be optimized:

# requires the kknn package
knn_mod <- 
  nearest_neighbor(neighbors = tune(), weight_func = tune()) %>% 
  set_engine("kknn") %>% 
  set_mode("regression")

The easiest approach to optimize the pre-processing and model parameters is to bundle these objects into a workflow:

library(workflows)
knn_wflow <- 
  workflow() %>% 
  add_model(knn_mod) %>% 
  add_recipe(ames_rec)

From this, the parameter set can be used to modify the range and values of parameters being optimized^[One of the tuning parameters (weight_func) is categorical and, by default, has r length(dials::values_weight_func) unique values. The model used to predict new test parameters is a Gaussian process model, and this can become slow to fit when the number of tuning parameters is large or when a categorical parameter generates many dummy variables. We've reduced the number of categories for this parameter to speed things up a bit.]:

knn_param <- 
  knn_wflow %>% 
  extract_parameter_set_dials() %>% 
    update(
    `long df` = spline_degree(c(2, 18)), 
    `lat df` = spline_degree(c(2, 18)),
    neighbors = neighbors(c(3, 50)),
    weight_func = weight_func(values = c("rectangular", "inv", "gaussian", "triangular"))
  )

This parameter collection can be used with the grid functions or with tune_grid() via the param_info argument.

Instead of using grid search, an iterative method called Bayesian optimization can be used. This takes an initial set of results and tries to predict the next tuning parameters to evaluate.

Although no grid is required, the process requires a few additional pieces of information:

• A description of the search space. At a minimum, the would consist of ranges for numeric values and a list of values for categorical tuning parameters.

• An acquisition function that helps score potential tuning parameter values.

• A model for analyzing and making predictions of the best tuning parameter values. A Gaussian Process model is typical and used here.

The code to conduct the search is:

ctrl <- control_bayes(verbose = TRUE)
set.seed(8154)
knn_search <- tune_bayes(knn_wflow, resamples = cv_splits, initial = 5, iter = 20,
                         param_info = knn_param, control = ctrl)

Visually, the performance gain was:

autoplot(knn_search, type = "performance", metric = "rmse")

The best results here were:

collect_metrics(knn_search) %>% 
  dplyr::filter(.metric == "rmse") %>% 
  arrange(mean)

With this intrinsically nonlinear model there is less reliance on the nonlinear terms created by the recipe.

tidymodels/tune documentation built on April 12, 2025, 9:40 p.m.