### Install mlr3tuning Development Version

Source: https://github.com/mlr-org/mlr3tuning/blob/main/README.md

Installs the development version of the mlr3tuning package directly from GitHub using the 'pak' package manager. This is useful for accessing the latest features or bug fixes.

```r
# install.packages("pak")
pak::pak("mlr-org/mlr3tuning")
```

--------------------------------

### Optimize Tuning Instance

Source: https://github.com/mlr-org/mlr3tuning/blob/main/README.md

Starts the hyperparameter optimization process by passing the tuning instance to the selected tuner. The result includes the best hyperparameter configuration and performance.

```r
tuner$optimize(instance)
```

--------------------------------

### Install mlr3tuning from CRAN

Source: https://github.com/mlr-org/mlr3tuning/blob/main/README.md

Installs the latest stable release of the mlr3tuning package from the Comprehensive R Archive Network (CRAN).

```r
install.packages("mlr3tuning")
```

--------------------------------

### Use Predefined Tuning Callbacks

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Leverage built-in callbacks for common tuning tasks. Examples include backing up benchmark results to disk after each batch, scoring additional performance measures during tuning, and applying the One Standard Error Rule to select a parsimonious model.

```r
library("mlr3tuning")

# Backup benchmark result to disk after each batch
instance = tune(
  tuner      = tnr("random_search", batch_size = 2),
  task       = tsk("pima"),
  learner    = lrn("classif.rpart", cp = to_tune(1e-04, 1e-1, logscale = TRUE)),
  resampling = rsmp("cv", folds = 3),
  measures   = msr("classif.ce"),
  term_evals = 4,
  callbacks  = clbk("mlr3tuning.backup", path = tempfile(fileext = ".rds"))
)
```

```r
# Score additional measures during tuning (memory-constrained scenario)
instance2 = tune(
  tuner      = tnr("random_search", batch_size = 2),
  task       = tsk("pima"),
  learner    = lrn("classif.rpart", cp = to_tune(1e-04, 1e-1, logscale = TRUE)),
  resampling = rsmp("cv", folds = 3),
  measures   = msr("classif.ce"),
  term_evals = 4,
  callbacks  = clbk("mlr3tuning.measures", measures = msr("classif.acc"))
)
as.data.table(instance2$archive)[, .(cp, classif.ce, classif.acc)]
```

```r
# One Standard Error Rule: prefer parsimonious models
instance3 = tune(
  tuner      = tnr("random_search", batch_size = 15),
  task       = tsk("pima"),
  learner    = lrn("classif.rpart", cp = to_tune(1e-04, 1e-1, logscale = TRUE)),
  resampling = rsmp("cv", folds = 3),
  measures   = msr("classif.ce"),
  term_evals = 30,
  callbacks  = clbk("mlr3tuning.one_se_rule")
)
instance3$result  # smallest feature set within 1 SE of best
```

--------------------------------

### Create Custom Tuning Callback

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Implement custom logic within the tuning loop by defining a callback function. This example demonstrates a callback that prints progress messages after each evaluation batch, showing the current evaluation count and the best performance achieved so far.

```r
library("mlr3tuning")

# Custom callback: print a message after each batch
my_callback = callback_batch_tuning(
  "my.progress",
  on_optimizer_after_eval = function(callback, context) {
    n = context$instance$archive$n_evals
    best = min(as.data.table(context$instance$archive)[[context$instance$archive$cols_y]])
    message(sprintf("Eval %d: best so far = %.4f", n, best))
  }
)

instance = tune(
  tuner      = tnr("random_search", batch_size = 3),
  task       = tsk("pima"),
  learner    = lrn("classif.rpart", cp = to_tune(1e-04, 1e-1, logscale = TRUE)),
  resampling = rsmp("cv", folds = 3),
  measures   = msr("classif.ce"),
  term_evals = 9,
  callbacks  = my_callback
)
```

--------------------------------

### Breaking Change Footer Example

Source: https://github.com/mlr-org/mlr3tuning/blob/main/extra-rules/commit-messages.md

Use the `BREAKING CHANGE:` footer to indicate significant changes that may break compatibility.

```git
BREAKING CHANGE: parameter 'x' has been removed
```

--------------------------------

### Implementing Active Bindings for Mutable Fields

Source: https://github.com/mlr-org/mlr3tuning/blob/main/extra-rules/mlr3.md

Example of an active binding for a mutable field 'id'. It handles both getting the current value and validating/setting a new value.

```r
id = function(rhs) {
  if (missing(rhs)) {
    return(private$.id)
  }
  private$.id = assert_id(rhs)
}
```

--------------------------------

### Implementing Active Bindings for Read-Only Fields

Source: https://github.com/mlr-org/mlr3tuning/blob/main/extra-rules/mlr3.md

Example of an active binding for a read-only field 'task_type'. It prevents any assignment attempts.

```r
task_type = function(rhs) {
  assert_ro_binding(rhs)
  private$.data$task_type
}
```

--------------------------------

### Registering a New Learner in mlr3

Source: https://github.com/mlr-org/mlr3tuning/blob/main/extra-rules/mlr3.md

Demonstrates how to register a new learner object with the mlr3 dictionary system. Ensure the base dictionary file is included.

```r
#' @include mlr_learners.R
mlr_learners$add("classif.rpart", function() LearnerClassifRpart$new())
```

--------------------------------

### tune()

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

A convenience wrapper that constructs a `TuningInstance` internally, runs `tuner$optimize()`, and returns the instance. It supports shortcuts for terminators.

```APIDOC
## tune() — One-Line Tuning

Convenience wrapper that constructs a `TuningInstance` internally, runs `tuner$optimize()`, and returns the instance. Supports shortcuts `term_evals` and `term_time` instead of constructing a `Terminator` explicitly.

```r
library("mlr3learners")
library("mlr3tuning")

instance = tune(
  tuner      = tnr("random_search", batch_size = 2),
  task       = tsk("pima"),
  learner    = lrn("classif.rpart", cp = to_tune(1e-04, 1e-1, logscale = TRUE)),
  resampling = rsmp("holdout"),
  measures   = msr("classif.ce"),
  term_evals = 10          # shortcut for trm("evals", n_evals = 10)
)

# Best hyperparameter configuration
instance$result
#>            cp learner_param_vals  x_domain classif.ce
#> 1: -4.605170          <list[2]> <list[1]>  0.2395833

# All 10 evaluated configurations
as.data.table(instance$archive)[, .(cp, classif.ce, batch_nr)]
```
```

--------------------------------

### Defining Hyperparameters with Paradox

Source: https://github.com/mlr-org/mlr3tuning/blob/main/extra-rules/mlr3.md

Shows how to define hyperparameters for a learner using paradox::ps(). Parameters must be tagged as 'train' or 'predict'.

```r
ps = ps(
  cp = p_dbl(0, 1, default = 0.01, tags = "train"),
  keep_model = p_lgl(default = FALSE, tags = "train")
)
```

--------------------------------

### Construct a Tuning Instance with ti()

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Creates a `TuningInstanceBatchSingleCrit` (single measure) or `TuningInstanceBatchMultiCrit` (multiple measures). The instance encapsulates all information about the tuning problem and is passed to the tuner.

```R
library("mlr3")
library("mlr3tuning")

learner = lrn("classif.rpart",
  cp = to_tune(1e-04, 1e-1, logscale = TRUE)
)

# Single criterion instance
instance = ti(
  task        = tsk("penguins"),
  learner     = learner,
  resampling  = rsmp("cv", folds = 3),
  measures    = msr("classif.ce"),
  terminator  = trm("evals", n_evals = 20)
)

# Multi-criteria instance (Pareto front optimization)
instance_mc = ti(
  task       = tsk("penguins"),
  learner    = learner,
  resampling = rsmp("holdout"),
  measures   = msrs(c("classif.ce", "time_train")),
  terminator = trm("evals", n_evals = 20)
)

instance
#> ── <TuningInstanceBatchSingleCrit> ──
#> • State: Not optimized
#> • Search Space:
#>    id    class     lower     upper nlevels
#> 1: cp ParamDbl -9.210340 -2.302585     Inf
#> • Terminator: <TerminatorEvals> [20/20]
```

--------------------------------

### Run Hyperparameter Optimization with tuner$optimize()

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Executes the tuning loop by proposing configurations, evaluating them, and writing results to the instance archive. Returns the best configuration(s). The best configuration can then be applied to train a final model.

```r
library("mlr3learners")
library("mlr3tuning")

learner = lrn("classif.svm",
  cost   = to_tune(1e-3, 1e3, logscale = TRUE),
  kernel = "radial",
  type   = "C-classification"
)

instance = ti(
  task       = tsk("sonar"),
  learner    = learner,
  resampling = rsmp("cv", folds = 3),
  measures   = msr("classif.ce"),
  terminator = trm("evals", n_evals = 10)
)

tuner = tnr("random_search", batch_size = 5)
tuner$optimize(instance)
#>        cost learner_param_vals  x_domain classif.ce
#> 1: 2.718282          <list[4]> <list[2]>   0.134615

# Best configuration
instance$result
instance$result_learner_param_vals  # ready to pass to learner$param_set$values

# Apply best config and train final model
learner$param_set$values = instance$result_learner_param_vals
learner$train(tsk("sonar"))
```

--------------------------------

### Construct Tuning Instance

Source: https://github.com/mlr-org/mlr3tuning/blob/main/README.md

Creates a tuning instance specifying the task, learner, resampling strategy, performance measures, and terminator. The 'tsk("sonar")' task and 'rsmp("cv", folds = 3)' resampling are used.

```r
instance = ti(
  task = tsk("sonar"),
  learner = learner,
  resampling = rsmp("cv", folds = 3),
  measures = msr("classif.ce"),
  terminator = trm("none")
)
instance
```

--------------------------------

### One-Line Tuning with tune()

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

A convenience wrapper that constructs a `TuningInstance` internally, runs `tuner$optimize()`, and returns the instance. Supports shortcuts for terminators like `term_evals`.

```r
library("mlr3learners")
library("mlr3tuning")

instance = tune(
  tuner      = tnr("random_search", batch_size = 2),
  task       = tsk("pima"),
  learner    = lrn("classif.rpart", cp = to_tune(1e-04, 1e-1, logscale = TRUE)),
  resampling = rsmp("holdout"),
  measures   = msr("classif.ce"),
  term_evals = 10          # shortcut for trm("evals", n_evals = 10)
)

# Best hyperparameter configuration
instance$result
#>            cp learner_param_vals  x_domain classif.ce
#> 1: -4.605170          <list[2]> <list[1]>  0.2395833

# All 10 evaluated configurations
as.data.table(instance$archive)[, .(cp, classif.ce, batch_nr)]
```

--------------------------------

### Select Tuner

Source: https://github.com/mlr-org/mlr3tuning/blob/main/README.md

Initializes a grid search tuner with a specified resolution. The tuner is configured to use batch optimization and supports various parameter classes.

```r
tuner = tnr("grid_search", resolution = 5)
tuner
```

--------------------------------

### Access Full Tuning Results Archive

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Retrieve the complete tuning archive as a data.table. This allows for detailed inspection of all evaluated configurations, their performance metrics, and associated data like batch number and runtime. It also shows how to score additional measures post-hoc or access specific resampling experiments and learner models.

```r
extract_inner_tuning_results(rr, tuning_instance = TRUE)
```

```r
library("mlr3tuning")

instance = tune(
  tuner      = tnr("grid_search", resolution = 5),
  task       = tsk("sonar"),
  learner    = lrn("classif.svm",
    cost   = to_tune(1e-2, 1e2, logscale = TRUE),
    kernel = "radial",
    type   = "C-classification"
  ),
  resampling = rsmp("holdout"),
  measures   = msr("classif.ce"),
  terminator = trm("none")
)

# Full archive as data.table
dt = as.data.table(instance$archive)
dt[, .(cost, classif.ce, batch_nr, runtime_learners)]

# Score on an additional measure post-hoc
as.data.table(instance$archive, measures = msr("classif.acc"))

# Access the 3rd resampling experiment
instance$archive$resample_result(i = 3)

# Access learner with model from 3rd eval
instance$archive$learners(i = 3)[[1]]$model
```

--------------------------------

### Run Tuning with Design Points

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Executes the hyperparameter tuning process using the specified design. It requires a tuner, task, learner, resampling strategy, and performance measures.

```R
instance = tune(
  tuner      = tnr("design_points", design = design),
  task       = tsk("penguins"),
  learner    = learner,
  resampling = rsmp("holdout"),
  measures   = msr("classif.ce")
)
```

--------------------------------

### View Tuning Archive

Source: https://github.com/mlr-org/mlr3tuning/blob/main/README.md

Retrieves and displays the tuning archive as a data table, showing evaluated hyperparameter configurations, their performance metrics, batch numbers, and resampling results.

```r
as.data.table(instance$archive)[, .(cost, gamma, classif.ce, batch_nr, resample_result)]
```

--------------------------------

### Automatic Tuning Pipeline with auto_tuner()

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Wraps a learner with automatic hyperparameter tuning, creating an `AutoTuner`. During `$train()`, it internally tunes hyperparameters and then fits the final model with the best configuration on the full training data.

```r
library("mlr3learners")
library("mlr3tuning")

learner = lrn("classif.rpart",
  cp = to_tune(1e-04, 1e-1, logscale = TRUE)
)

at = auto_tuner(
  tuner      = tnr("random_search"),
  learner    = learner,
  resampling = rsmp("holdout"),
  measure    = msr("classif.ce"),
  term_evals = 10
)

# Split data
task  = tsk("penguins")
split = partition(task, ratio = 0.8)

# Train: tunes internally, then fits final model on train set
at$train(task, row_ids = split$train)

# Predict on held-out test set
preds = at$predict(task, row_ids = split$test)
preds$score(msr("classif.ce"))

# Inspect tuning result
at$tuning_result
#>            cp learner_param_vals  x_domain classif.ce
#> 1: -3.912023          <list[2]> <list[1]>  0.0869565

# Access trained final learner
at$learner$model
```

--------------------------------

### Define Search Space with Tune Tokens

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Attach tune tokens directly to learner parameter values to implicitly declare the search space. Supports numeric ranges (with optional log-scale), discrete sets, and internal tuning. The search space is automatically extracted by TuningInstance at construction time.

```R
library("mlr3")
library("mlr3learners")
library("mlr3tuning")

# Numeric range on log scale
learner = lrn("classif.svm",
  cost   = to_tune(1e-5, 1e5, logscale = TRUE),
  gamma  = to_tune(1e-5, 1e5, logscale = TRUE),
  kernel = "radial",
  type   = "C-classification"
)

# Discrete values
learner2 = lrn("classif.rpart",
  cp        = to_tune(1e-04, 1e-1, logscale = TRUE),
  minsplit  = to_tune(2L, 128L),
  minbucket = to_tune(p_int(1, 64))
)

# View the constructed search space
learner2$param_set$search_space()
#> <ParamSet>
#>          id    class lower upper nlevels
#> 1:       cp ParamDbl  ...  ...      Inf
#> 2: minsplit ParamInt    2  128      127
#> 3:minbucket ParamInt    1   64       64
```

--------------------------------

### Visualize Tuning Results

Source: https://github.com/mlr-org/mlr3tuning/blob/main/README.md

Generates a surface plot of the tuning results using the 'mlr3viz' package to visualize the relationship between hyperparameters and performance.

```r
library(mlr3viz)

autoplot(instance, type = "surface")
```

--------------------------------

### Using mlr3misc Error Handling Functions

Source: https://github.com/mlr-org/mlr3tuning/blob/main/extra-rules/mlr3.md

Demonstrates the use of structured error functions from mlr3misc for reporting configuration errors. These functions support sprintf-style formatting.

```r
error_config("Invalid configuration for %s.", "learner")
```

--------------------------------

### tuner$optimize()

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Executes the tuning loop for hyperparameter optimization. It proposes configurations, evaluates them, and returns the best configuration(s).

```APIDOC
## tuner$optimize() — Run Hyperparameter Optimization

Executes the tuning loop. The tuner proposes hyperparameter configurations, evaluates them via resampling, and writes all results to `instance$archive`. Returns the best configuration(s).

```r
library("mlr3learners")
library("mlr3tuning")

learner = lrn("classif.svm",
  cost   = to_tune(1e-3, 1e3, logscale = TRUE),
  kernel = "radial",
  type   = "C-classification"
)

instance = ti(
  task       = tsk("sonar"),
  learner    = learner,
  resampling = rsmp("cv", folds = 3),
  measures   = msr("classif.ce"),
  terminator = trm("evals", n_evals = 10)
)

tuner = tnr("random_search", batch_size = 5)
tuner$optimize(instance)
#>        cost learner_param_vals  x_domain classif.ce
#> 1: 2.718282          <list[4]> <list[2]>   0.134615

# Best configuration
instance$result
instance$result_learner_param_vals  # ready to pass to learner$param_set$values

# Apply best config and train final model
learner$param_set$values = instance$result_learner_param_vals
learner$train(tsk("sonar"))
```
```

--------------------------------

### Print Tuner Object

Source: https://github.com/mlr-org/mlr3tuning/blob/main/tests/testthat/_snaps/Tuner.md

Displays detailed information about a Tuner object, including its configuration and properties. This is useful for inspecting the state of a tuner before or after tuning.

```r
tuner
```

--------------------------------

### Access and Display Tuning Results

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Retrieves and displays the results of the hyperparameter tuning instance. It shows the selected hyperparameters and their corresponding performance.

```R
instance$result
```

```R
as.data.table(instance$archive)[, .(cp, minsplit, minbucket, classif.ce)]
```

--------------------------------

### auto_tuner()

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Wraps a learner with automatic hyperparameter tuning, creating an `AutoTuner`. During `$train()`, it tunes hyperparameters and then fits the final model.

```APIDOC
## auto_tuner() — Automatic Tuning Pipeline

Wraps a learner with automatic hyperparameter tuning, creating an `AutoTuner` that behaves as a regular mlr3 `Learner`. During `$train()`, it internally tunes hyperparameters and then fits the final model with the best configuration on the full training data.

```r
library("mlr3learners")
library("mlr3tuning")

learner = lrn("classif.rpart",
  cp = to_tune(1e-04, 1e-1, logscale = TRUE)
)

at = auto_tuner(
  tuner      = tnr("random_search"),
  learner    = learner,
  resampling = rsmp("holdout"),
  measure    = msr("classif.ce"),
  term_evals = 10
)

# Split data
task  = tsk("penguins")
split = partition(task, ratio = 0.8)

# Train: tunes internally, then fits final model on train set
at$train(task, row_ids = split$train)

# Predict on held-out test set
preds = at$predict(task, row_ids = split$test)
preds$score(msr("classif.ce"))

# Inspect tuning result
at$tuning_result
#>            cp learner_param_vals  x_domain classif.ce
#> 1: -3.912023          <list[2]> <list[1]>  0.0869565

# Access trained final learner
at$learner$model
```
```

--------------------------------

### Design-Points Tuner for Manual Configuration Evaluation

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Utilize the Design-Points Tuner to evaluate a user-defined grid of hyperparameter configurations in a specified order. This is useful for validating specific settings or incorporating domain knowledge into the tuning process.

```r
library("mlr3tuning")
library("mlr3misc")

learner = lrn("classif.rpart",
  cp        = to_tune(1e-04, 1e-1),
  minsplit  = to_tune(2, 128),
  minbucket = to_tune(1, 64)
)
```

--------------------------------

### Run R Package Commands with devtools

Source: https://github.com/mlr-org/mlr3tuning/blob/main/AGENTS.md

Execute various development tasks for an R package using Rscript and devtools. Ensure the package is loaded before running commands.

```bash
# To run code
Rscript -e "devtools::load_all(); code"
```

```bash
# To run all tests
Rscript -e "devtools::test()"
```

```bash
# To run all tests for files starting with {name}
Rscript -e "devtools::test(filter = '^ {name}')"
```

```bash
# To run all tests for R/{name}.R
Rscript -e "devtools::test_active_file('R/{name}.R')"
```

```bash
# To run a single test "blah" for R/{name}.R
Rscript -e "devtools::test_active_file('R/{name}.R', desc = 'blah')"
```

```bash
# To redocument the package
Rscript -e "devtools::document()"
```

```bash
# To check pkgdown documentation
Rscript -e "pkgdown::check_pkgdown()"
```

```bash
# To check the package with R CMD check
Rscript -e "devtools::check()"
```

--------------------------------

### Retrieving Hyperparameter Values

Source: https://github.com/mlr-org/mlr3tuning/blob/main/extra-rules/mlr3.md

Illustrates how to retrieve hyperparameter values tagged for training within the .train() or .predict() methods.

```r
self$param_set$get_values(tags = "train")
```

--------------------------------

### Retrieve Tuner Objects with tnr() / tnrs()

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Sugar functions to look up tuner objects from the `mlr_tuners` dictionary. Available keys include "random_search", "grid_search", "design_points", "cmaes", "irace", "nloptr", "gensa".

```R
# Random search with batch size 10
tuner_rs = tnr("random_search", batch_size = 10)

# Grid search with resolution 5 per dimension
tuner_gs = tnr("grid_search", resolution = 5)

# CMA-ES (requires adagio package)
tuner_cmaes = tnr("cmaes")

# Iterated Racing (requires irace package)
tuner_irace = tnr("irace")

# List multiple tuners at once
tuners = tnrs(c("random_search", "grid_search"))
```

--------------------------------

### Define Tunable Learner

Source: https://github.com/mlr-org/mlr3tuning/blob/main/README.md

Defines a support vector machine learner with 'cost' and 'gamma' hyperparameters set to be tuned. Requires 'mlr3learners' and 'mlr3tuning' libraries.

```r
library("mlr3learners")
library("mlr3tuning")

learner = lrn("classif.svm",
  cost  = to_tune(1e-5, 1e5, logscale = TRUE),
  gamma = to_tune(1e-5, 1e5, logscale = TRUE),
  kernel = "radial",
  type = "C-classification"
)
```

--------------------------------

### Fit Final Model

Source: https://github.com/mlr-org/mlr3tuning/blob/main/README.md

Fits a final model using the optimized hyperparameters obtained from the tuning instance. The learner's parameter values are updated before training on the task.

```r
learner$param_set$values = instance$result_learner_param_vals
learner$train(tsk("sonar"))
```

--------------------------------

### Access Inner Tuning Results with extract_inner_tuning_results()

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Extracts the per-fold tuning results from a `ResampleResult` or `BenchmarkResult` produced by nested resampling with an `AutoTuner`. Requires `store_tuning_instance = TRUE` when creating the `AutoTuner`.

```r
library("mlr3learners")
library("mlr3tuning")

at = auto_tuner(
  tuner      = tnr("random_search"),
  learner    = lrn("classif.rpart", cp = to_tune(1e-04, 1e-1, logscale = TRUE)),
  resampling = rsmp("holdout"),
  measure    = msr("classif.ce"),
  term_evals = 4,
  store_tuning_instance = TRUE
)

rr = resample(tsk("iris"), at, rsmp("cv", folds = 3), store_models = TRUE)

# Best config per outer fold
extract_inner_tuning_results(rr)
```

--------------------------------

### Define Hand-crafted Design for Tuning

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Defines a grid of hyperparameter values for tuning using `rowwise_table`. This approach is useful when you have specific combinations of hyperparameters you want to explore.

```R
design = rowwise_table(
  ~cp,   ~minsplit, ~minbucket,
  0.1,    2,         64,
  0.01,  64,         32,
  0.001, 128,         1
)
```

--------------------------------

### Nested Resampling with tune_nested()

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Performs nested resampling by wrapping an `AutoTuner` in an outer resampling loop. This provides an unbiased estimate of the generalization performance of the tuning procedure itself.

```r
library("mlr3learners")
library("mlr3tuning")

rr = tune_nested(
  tuner              = tnr("random_search", batch_size = 2),
  task               = tsk("penguins"),
  learner            = lrn("classif.rpart", cp = to_tune(1e-04, 1e-1, logscale = TRUE)),
  inner_resampling   = rsmp("holdout"),
  outer_resampling   = rsmp("cv", folds = 3),
  measure            = msr("classif.ce"),
  term_evals         = 5
)

# Per-fold performance on the outer resampling
rr$score()
#>    iteration classif.ce
#> 1:         1  0.0869565
#> 2:         2  0.1304348
#> 3:         3  0.0869565

# Aggregate unbiased performance estimate
rr$aggregate()
#> classif.ce
#>  0.1014493

# Inner tuning results per fold
extract_inner_tuning_results(rr)
#>    iteration         cp classif.ce task_id       learner_id resampling_id
#> 1:         1 -4.6051702 0.08695652 penguins classif.rpart.tuned     holdout
#> 2:         2 -2.3025851 0.13043478 penguins classif.rpart.tuned     holdout
#> 3:         3 -4.6051702 0.08695652 penguins classif.rpart.tuned     holdout
```

--------------------------------

### tune_nested()

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Performs nested resampling by wrapping an `AutoTuner` in an outer resampling loop, providing an unbiased estimate of the tuning procedure's generalization performance.

```APIDOC
## tune_nested() — Nested Resampling

Performs nested resampling by wrapping an `AutoTuner` in an outer resampling loop. This provides an unbiased estimate of the generalization performance of the tuning procedure itself.

```r
library("mlr3learners")
library("mlr3tuning")

rr = tune_nested(
  tuner              = tnr("random_search", batch_size = 2),
  task               = tsk("penguins"),
  learner            = lrn("classif.rpart", cp = to_tune(1e-04, 1e-1, logscale = TRUE)),
  inner_resampling   = rsmp("holdout"),
  outer_resampling   = rsmp("cv", folds = 3),
  measure            = msr("classif.ce"),
  term_evals         = 5
)

# Per-fold performance on the outer resampling
rr$score()
#>    iteration classif.ce
#> 1:         1  0.0869565
#> 2:         2  0.1304348
#> 3:         3  0.0869565

# Aggregate unbiased performance estimate
rr$aggregate()
#> classif.ce
#>  0.1014493

# Inner tuning results per fold
extract_inner_tuning_results(rr)
#>    iteration         cp classif.ce task_id       learner_id resampling_id
#> 1:         1 -4.6051702 0.08695652 penguins classif.rpart.tuned     holdout
#> 2:         2 -2.3025851 0.13043478 penguins classif.rpart.tuned     holdout
#> 3:         3 -4.6051702 0.08695652 penguins classif.rpart.tuned     holdout
```
```

--------------------------------

### Conventional Commit Message Format

Source: https://github.com/mlr-org/mlr3tuning/blob/main/extra-rules/commit-messages.md

Follows the Conventional Commits specification for structured commit messages. Includes type, optional scope, description, and optional body/footers.

```git
<type>(<optional scope>): <description>

[optional body]

[optional footer(s)]
```

--------------------------------

### Retrieve Terminator Objects with trm() / trms()

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Sugar functions to construct termination criteria from the `mlr_terminators` dictionary. Terminators control when the optimization stops.

```R
# Stop after 50 evaluations
trm("evals", n_evals = 50)

# Stop after 30 seconds
trm("run_time", secs = 30)

# Stop after 50 evals OR 60 seconds (whichever comes first)
trm("combo", list(trm("evals", n_evals = 50), trm("run_time", secs = 60)))

# Never stop (useful when tuner self-terminates, e.g. grid search)
trm("none")

# Stop when performance plateau is reached
trm("stagnation", iters = 5, threshold = 1e-5)
```

--------------------------------

### extract_inner_tuning_results()

Source: https://context7.com/mlr-org/mlr3tuning/llms.txt

Extracts the per-fold tuning results from a `ResampleResult` or `BenchmarkResult` produced by nested resampling with an `AutoTuner`.

```APIDOC
## extract_inner_tuning_results() — Access Inner Tuning Results

Extracts the per-fold tuning results from a `ResampleResult` or `BenchmarkResult` produced by nested resampling with an `AutoTuner`.

```r
library("mlr3learners")
library("mlr3tuning")

at = auto_tuner(
  tuner      = tnr("random_search"),
  learner    = lrn("classif.rpart", cp = to_tune(1e-04, 1e-1, logscale = TRUE)),
  resampling = rsmp("holdout"),
  measure    = msr("classif.ce"),
  term_evals = 4,
  store_tuning_instance = TRUE
)

rr = resample(tsk("iris"), at, rsmp("cv", folds = 3), store_models = TRUE)

# Best config per outer fold
extract_inner_tuning_results(rr)


```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.