feat: add help method to tuner (#331)

NEWS.md

@@ -1,6 +1,7 @@
 # mlr3tuning 0.12.1
 
 * feat: Added a `as.data.table.DictionaryTuner` method.
+* feat: `$help()` method which opens manual page of a `Tuner`.
 
 # mlr3tuning 0.12.0
 

R/Tuner.R

@@ -88,13 +88,18 @@ Tuner = R6Class("Tuner",
     #' @param packages (`character()`)\cr
     #' Set of required packages. Note that these packages will be loaded via
     #' [requireNamespace()], and are not attached.
-    initialize = function(param_set, param_classes, properties, packages = character()) {
+    #'
+    #' @param man (`character(1)`)\cr
+    #'   String in the format `[pkg]::[topic]` pointing to a manual page for this object.
+    #'   The referenced help package can be opened via method `$help()`.
+    initialize = function(param_set, param_classes, properties, packages = character(), man = NA_character_) {
       private$.param_set = assert_param_set(param_set)
       private$.param_classes = assert_subset(param_classes,
         c("ParamLgl", "ParamInt", "ParamDbl", "ParamFct", "ParamUty"))
       # has to have at least multi-crit or single-crit property
       private$.properties = assert_subset(properties, bbotk_reflections$optimizer_properties, empty.ok = FALSE)
       private$.packages = union("mlr3tuning", assert_character(packages, any.missing = FALSE, min.chars = 1L))
+      private$.man = assert_string(man, na.ok = TRUE)
 
       check_packages_installed(self$packages,
         msg = sprintf("Package '%%s' required but not installed for Tuner '%s'", format(self)))
@@ -117,6 +122,12 @@ Tuner = R6Class("Tuner",
       catf(str_indent("* Packages:", self$packages))
     },
 
+    #' @description
+    #' Opens the corresponding help page referenced by field `$man`.
+    help = function() {
+      open_help(self$man)
+    },
+
     #' @description
     #' Performs the tuning on a [TuningInstanceSingleCrit] or
     #' [TuningInstanceMultiCrit] until termination.
@@ -167,6 +178,14 @@ Tuner = R6Class("Tuner",
         stop("$packages is read-only.")
       }
       private$.packages
+    },
+
+    #' @field man (`character()`).
+    man = function(rhs) {
+      if (!missing(rhs) && !identical(rhs, private$.man)) {
+        stop("$man is read-only.")
+      }
+      private$.man
     }
   ),
 
@@ -181,6 +200,7 @@ Tuner = R6Class("Tuner",
     .param_set = NULL,
     .param_classes = NULL,
     .properties = NULL,
-    .packages = NULL
+    .packages = NULL,
+    .man = NULL
   )
 )

R/TunerCmaes.R

@@ -13,36 +13,36 @@
 #' \describe{
 #' \item{`sigma`}{`numeric(1)`}
 #' \item{`start_values`}{`character(1)`\cr
-#' Create `random` start values or based on `center` of search space? In the 
+#' Create `random` start values or based on `center` of search space? In the
 #' latter case, it is the center of the parameters before a trafo is applied.}
 #' }
 #'
 #' For the meaning of the control parameters, see [adagio::pureCMAES()]. Note
 #' that we have removed all control parameters which refer to the termination of
 #' the algorithm and where our terminators allow to obtain the same behavior.
-#' 
+#'
 #' @template section_progress_bars
 #' @template section_logging
-#' 
-#' @source 
+#'
+#' @source
 #' `r format_bib("hansen_2016")`
 #'
 #' @family Tuner
 #' @seealso Package \CRANpkg{mlr3hyperband} for hyperband tuning.
 #' @export
 #' @examples
 #' library(data.table)
-#' 
+#'
 #' # retrieve task
 #' task = tsk("pima")
-#' 
+#'
 #' # load learner and set search space
-#' learner = lrn("classif.rpart", 
-#'   cp = to_tune(1e-04, 1e-1, logscale = TRUE), 
+#' learner = lrn("classif.rpart",
+#'   cp = to_tune(1e-04, 1e-1, logscale = TRUE),
 #'   minsplit = to_tune(p_dbl(2, 128, trafo = as.integer)),
 #'   minbucket = to_tune(p_dbl(1, 64, trafo = as.integer))
 #' )
-#' 
+#'
 #' # hyperparameter tuning on the pima indians diabetes data set
 #' instance = tune(
 #'   method = "cmaes",
@@ -51,13 +51,13 @@
 #'   resampling = rsmp("holdout"),
 #'   measure = msr("classif.ce"),
 #'   term_evals = 10)
-#' 
+#'
 #' # best performing hyperparameter configuration
 #' instance$result
-#' 
+#'
 #' # all evaluated hyperparameter configuration
 #' as.data.table(instance$archive)
-#' 
+#'
 #' # fit final model on complete data set
 #' learner$param_set$values = instance$result_learner_param_vals
 #' learner$train(task)
@@ -71,6 +71,7 @@ TunerCmaes = R6Class("TunerCmaes",
      super$initialize(
        optimizer = OptimizerCmaes$new()
      )
+     private$.man = "mlr3tuning::mlr_tuners_cmaes"
    }
   )
 )

R/TunerDesignPoints.R

@@ -13,7 +13,7 @@
 #'
 #' @inheritSection bbotk::OptimizerDesignPoints Parameters
 #' @inheritSection bbotk::OptimizerDesignPoints Progress Bars
-#' 
+#'
 #' @template section_parallelization
 #' @template section_logging
 #'
@@ -22,13 +22,13 @@
 #' @export
 #' @examples
 #' library(data.table)
-#' 
+#'
 #' # retrieve task
 #' task = tsk("pima")
-#' 
+#'
 #' # load learner and set search space
 #' learner = lrn("classif.rpart", cp = to_tune(1e-04, 1e-1, logscale = TRUE))
-#' 
+#'
 #' # hyperparameter tuning on the pima indians diabetes data set
 #' instance = tune(
 #'   method = "design_points",
@@ -41,10 +41,10 @@
 #'
 #' # best performing hyperparameter configuration
 #' instance$result
-#' 
+#'
 #' # all evaluated hyperparameter configuration
 #' as.data.table(instance$archive)
-#' 
+#'
 #' # fit final model on complete data set
 #' learner$param_set$values = instance$result_learner_param_vals
 #' learner$train(task)
@@ -58,6 +58,7 @@ TunerDesignPoints = R6Class("TunerDesignPoints",
       super$initialize(
         optimizer = OptimizerDesignPoints$new()
       )
+      private$.man = "mlr3tuning::mlr_tuners_design_points"
     }
   )
 )

R/TunerGenSA.R

@@ -11,7 +11,7 @@
 #'
 #' @inheritSection bbotk::OptimizerGenSA Parameters
 #' @inheritSection bbotk::OptimizerGenSA Progress Bars
-#' 
+#'
 #' @template section_parallelization
 #' @template section_logging
 #'
@@ -32,6 +32,7 @@ TunerGenSA = R6Class("TunerGenSA",
       super$initialize(
         optimizer = OptimizerGenSA$new()
       )
+      private$.man = "mlr3tuning::mlr_tuners_gensa"
     }
   )
 )

R/TunerGridSearch.R

@@ -49,7 +49,8 @@ TunerGridSearch = R6Class("TunerGridSearch",
       super$initialize(
         param_set = param_set,
         param_classes = c("ParamLgl", "ParamInt", "ParamDbl", "ParamFct"),
-        properties = c("dependencies", "single-crit", "multi-crit")
+        properties = c("dependencies", "single-crit", "multi-crit"),
+        man = "mlr3tuning::mlr_tuners_grid_search"
       )
     }
   ),

R/TunerIrace.R

@@ -6,16 +6,16 @@
 #' @description
 #' `TunerIrace` class that implements iterated racing. Calls [irace::irace()]
 #' from package \CRANpkg{irace}.
-#' 
+#'
 #' @templateVar id irace
 #' @template section_dictionary_tuners
-#' 
+#'
 #' @section Parameters:
 #' \describe{
 #' \item{`n_instances`}{`integer(1)`\cr
 #' Number of resampling instances.}
 #' }
-#' 
+#'
 #' For the meaning of all other parameters, see [irace::defaultScenario()]. Note
 #' that we have removed all control parameters which refer to the termination of
 #' the algorithm. Use [TerminatorEvals] instead. Other terminators do not work
@@ -36,10 +36,10 @@
 #' The tuning result (`instance$result`) is the best performing elite of
 #' the final race. The reported performance is the average performance estimated
 #' on all used instances.
-#' 
+#'
 #' @template section_progress_bars
 #' @template section_logging
-#' 
+#'
 #' @source
 #' `r format_bib("lopez_2016")`
 #'
@@ -48,10 +48,10 @@
 #' @examples
 #' # retrieve task
 #' task = tsk("pima")
-#' 
+#'
 #' # load learner and set search space
 #' learner = lrn("classif.rpart", cp = to_tune(1e-04, 1e-1, logscale = TRUE))
-#' 
+#'
 #' # hyperparameter tuning on the pima indians diabetes data set
 #' instance = tune(
 #'   method = "irace",
@@ -64,10 +64,10 @@
 #'
 #' # best performing hyperparameter configuration
 #' instance$result
-#' 
+#'
 #' # all evaluated hyperparameter configuration
 #' as.data.table(instance$archive)
-#' 
+#'
 #' # fit final model on complete data set
 #' learner$param_set$values = instance$result_learner_param_vals
 #' learner$train(task)
@@ -87,6 +87,7 @@ TunerIrace = R6Class("TunerIrace",
         logFile = tempfile(fileext = ".Rdata"))
 
       super$initialize(optimizer = optimizer)
+      private$.man = "mlr3tuning::mlr_tuners_irace"
     },
 
     #' @description

R/TunerNLoptr.R

@@ -33,10 +33,10 @@
 #' \dontrun{
 #' # retrieve task
 #' task = tsk("pima")
-#' 
+#'
 #' # load learner and set search space
 #' learner = lrn("classif.rpart", cp = to_tune(1e-04, 1e-1, logscale = TRUE))
-#' 
+#'
 #' # hyperparameter tuning on the pima indians diabetes data set
 #' instance = tune(
 #'   method = "nloptr",
@@ -49,10 +49,10 @@
 #'
 #' # best performing hyperparameter configuration
 #' instance$result
-#' 
+#'
 #' # all evaluated hyperparameter configuration
 #' as.data.table(instance$archive)
-#' 
+#'
 #' # fit final model on complete data set
 #' learner$param_set$values = instance$result_learner_param_vals
 #' learner$train(task)
@@ -67,6 +67,7 @@ TunerNLoptr = R6Class("TunerNLoptr",
       super$initialize(
         optimizer = OptimizerNLoptr$new()
       )
+      private$.man = "mlr3tuning::mlr_tuners_nloptr"
     }
   )
 )

R/TunerRandomSearch.R

@@ -13,7 +13,7 @@
 #'
 #' @inheritSection bbotk::OptimizerRandomSearch Parameters
 #' @inheritSection bbotk::OptimizerRandomSearch Progress Bars
-#' 
+#'
 #' @template section_parallelization
 #' @template section_logging
 #'
@@ -34,6 +34,7 @@ TunerRandomSearch = R6Class("TunerRandomSearch",
       super$initialize(
         optimizer = OptimizerRandomSearch$new()
       )
+      private$.man = "mlr3tuning::mlr_tuners_random_search"
     }
   )
 )

R/mlr_tuners.R

@@ -38,7 +38,8 @@ as.data.table.DictionaryTuner = function(x, ...) {
       key = key,
       param_classes = list(t$param_classes),
       properties = list(t$properties),
-      packages = list(t$packages)
+      packages = list(t$packages),
+      man = t$man
     )
   }, .fill = TRUE), "key")[]
 }

inst/testthat/helper_tuner.R

@@ -18,6 +18,7 @@ test_tuner = function(key, ..., n_dim = 1L, term_evals = 2L, real_evals = term_e
   inst = TuningInstanceSingleCrit$new(tsk("iris"), lrn("classif.rpart"), rsmp("holdout"), msr("classif.ce"), term, search_space)
   tuner = tnr(key, ...)
   expect_tuner(tuner)
+  expect_man_exists(tuner$man)
   tuner$optimize(inst)
   archive = inst$archive