`tune`

attempts to evaluate the candidate models in the shortest amount of time. This vignette is a summary of those approaches.

## Sub-model speed-ups

For some types of models, such as boosted models or regularized models, the number of models that are actually *fit* can be far less than the number of models evaluated. For example, suppose a boosted tree is fit with 1000 trees. Many boosting implementations let the user make predictions for any number of trees less than what was originally fit (1000 in this example). This “sub-model trick” can greatly speed up the training time for many models (e.g. see this example in the `caret`

documentation).

In order to know what models allow this, the `parsnip`

package contains a `multi_predict()`

function that enables this feature. Printing the S3 methods for it lists the possible models:

```
library(tidymodels)
methods("multi_predict")
```

```
## [1] multi_predict._C5.0* multi_predict._earth*
## [3] multi_predict._elnet* multi_predict._lognet*
## [5] multi_predict._multnet* multi_predict._torch_mlp*
## [7] multi_predict._train.kknn* multi_predict._xgb.Booster*
## [9] multi_predict.default*
## see '?methods' for accessing help and source code
```

```
# There are arguments for the parameter(s) that can create multiple predictions.
# For xgboost, `trees` are cheap to evaluate:
parsnip:::multi_predict._xgb.Booster %>%
formals() %>%
names()
```

`## [1] "object" "new_data" "type" "trees" "..."`

The same feature does not exist for recipes though.

## Expensive pre-processing

When tuning a recipe and a model, it makes sense to avoid *recreating* the recipe for each model.

For example, suppose that Isomap multi-dimensional scaling is used to pre-process the data prior to tuning a K-nearest neighbor regression:

```
data(Chicago)
iso_rec <-
recipe(ridership ~ ., data = Chicago) %>%
step_dummy(all_nominal()) %>%
step_isomap(all_predictors(), num_terms = tune())
knn_mod <-
nearest_neighbor(neighbors = tune(), weight_func = tune()) %>%
set_engine("kknn") %>%
set_mode("regression")
```

With the following grid:

```
grid <-
parameters(num_terms(c(1, 9)), neighbors(), weight_func()) %>%
grid_regular(levels = c(5, 10, 7)) %>%
arrange(num_terms, neighbors, weight_func)
grid
```

```
## # A tibble: 350 × 3
## num_terms neighbors weight_func
## <int> <int> <chr>
## 1 1 1 biweight
## 2 1 1 cos
## 3 1 1 epanechnikov
## 4 1 1 inv
## 5 1 1 rectangular
## 6 1 1 triangular
## 7 1 1 triweight
## 8 1 2 biweight
## 9 1 2 cos
## 10 1 2 epanechnikov
## # … with 340 more rows
```

To evaluate these 350 candidate models, we would have to compute the same recipe 70 times *per resample*. Since Isomap is expensive, this is really inefficient.

`tune_grid()`

determines when this occurs and fits all 70 candidate models for each unique configuration of the recipe. In essence, it nests the model parameters inside the unique parameters of the recipe:

```
## # A tibble: 5 × 2
## num_terms data
## <int> <list>
## 1 1 <tibble [70 × 2]>
## 2 3 <tibble [70 × 2]>
## 3 5 <tibble [70 × 2]>
## 4 7 <tibble [70 × 2]>
## 5 9 <tibble [70 × 2]>
```

Only 5 recipes are prepared and, within each, all of the appropriate models are fit from the same recipe. In this example, once the recipe with `num_terms = 1`

is created, the model parameters are iteratively tuned:

```
## # A tibble: 70 × 2
## neighbors weight_func
## <int> <chr>
## 1 1 biweight
## 2 1 cos
## 3 1 epanechnikov
## 4 1 inv
## 5 1 rectangular
## 6 1 triangular
## 7 1 triweight
## 8 2 biweight
## 9 2 cos
## 10 2 epanechnikov
## # … with 60 more rows
```

The same will be true for post-processing parameters being tuned. For each unique set of recipe and model parameters, the post-processing parameters will be evaluated without unnecessary re-fitting.

Also, when using a model formula, the model matrix is only created once per resample.

## Parallel Processing

`tune`

allows users, when possible, to use multiple cores or separate machines fit models. Currently, the package parallelizes the *resampling* loop of grid search^{1}.

The `foreach`

package is used to facilitate parallel computations. `foreach`

can use a variety of technologies to share the computations and the choice of technology is determined by which *parallel backend* package is chosen (aka the `do{technology}`

packages). For example, the `doMC`

package uses the forking mechanism on *unix systems to split the computations across multiple cores. As of this writing, the backend packages are `doFuture`

, `doMC`

, `doMPI`

, `doParallel`

, `doRedis`

, `doRNG`

, `doSNOW`

, and `doAzureParallel`

(GitHub only). Of these, `doFuture`

and `doParallel`

are probably the most comprehensive and best supported.

Registering a parallel backend is also somewhat dependent of the package. For `doParallel`

, one could use:

```
all_cores <- parallel::detectCores(logical = FALSE)
library(doParallel)
cl <- makePSOCKcluster(all_cores)
registerDoParallel(cl)
```

Other options exist in `doParallel`

.

`doFuture`

uses a function called `plan`

to declare the method:

```
all_cores <- parallel::detectCores(logical = FALSE)
library(doFuture)
registerDoFuture()
cl <- makeCluster(all_cores)
plan(cluster, workers = cl)
```

One downside to parallel processing is that the different technologies handle inputs and outputs differently. For example, multicore forking *tends* to carry the loaded packages and objects into the worker processes. Others do not. To make sure that the correct packages are loaded (but not attached) in the workers is to use the `pkg`

option in `control_grid()`

.

Some helpful advice to avoid errors in parallel processing is to not use variables in the global environment. These may not be found when the code is run inside of a worker process. For example:

```
num_pcs <- 3
recipe(mpg ~ ., data = mtcars) %>%
# Bad since num_pcs might not be found by a worker process
step_pca(all_predictors(), num_comp = num_pcs)
recipe(mpg ~ ., data = mtcars) %>%
# Good since the value is injected into the object
step_pca(all_predictors(), num_comp = !!num_pcs)
```

This issue is likely to occur if `dplyr::one_of()`

is used as a sector.

Also note that almost all of the logging provided by `tune_grid()`

will not be seen when running in parallel. Again, this is dependent on the backend package and technology being used.