|
| 1 | +#' @title Evaluates expressions within a learner or parameter set. |
| 2 | +#' |
| 3 | +#' @description |
| 4 | +#' A \code{\link{Learner}} can contain unevaluated \code{\link[base]{expression}s} |
| 5 | +#' as value for a hyperparameter. E.g., these expressions are used if the default |
| 6 | +#' value depends on the task size or an upper limit for a parameter is given by |
| 7 | +#' the number of features in a task. \code{evaluateParamExpressions} allows to |
| 8 | +#' evaluate these expressions using a given dictionary, which holds the following |
| 9 | +#' information: |
| 10 | +#' \itemize{ |
| 11 | +#' \item{\code{task}:} the task itself, allowing to access any of its elements. |
| 12 | +#' \item{\code{p}:} the number of features in the task |
| 13 | +#' \item{\code{n}:} the number of observations in the task |
| 14 | +#' \item{\code{type}:} the task type, i.e. "classif", "regr", "surv", "cluster", "costcens" or "multilabel" |
| 15 | +#' \item{\code{k}:} the number of classes of the target variable (only available for classification tasks) |
| 16 | +#' } |
| 17 | +#' Usually the evaluation of the expression is performed automatically, e.g. in |
| 18 | +#' \code{\link{train}} or \code{\link{tuneParams}}. Therefore calling |
| 19 | +#' \code{evaluateParamExpressions} manually should not be necessary. |
| 20 | +#' It is also possible to directly evaluate the expressions of a |
| 21 | +#' \code{\link[ParamHelpers]{ParamSet}}, \code{\link[base]{list}} of |
| 22 | +#' \code{\link[ParamHelpers]{Param}s} or single \code{\link[ParamHelpers]{Param}s}. |
| 23 | +#' For further information on these, please refer to the documentation of the |
| 24 | +#' \code{ParamHelpers} package. |
| 25 | +#' |
| 26 | +#' @param obj [\code{\link{Learner}}]\cr |
| 27 | +#' The learner. If you pass a string the learner will be created via |
| 28 | +#' \code{\link{makeLearner}}. Expressions within \code{length}, \code{lower} |
| 29 | +#' or \code{upper} boundaries, \code{default} or \code{value} will be |
| 30 | +#' evaluated using the provided dictionary (\code{dict}). |
| 31 | +#' @param dict [\code{environment} | \code{list} | \code{NULL}]\cr |
| 32 | +#' Environment or list which will be used for evaluating the variables |
| 33 | +#' of expressions within a parameter, parameter set or list of parameters. |
| 34 | +#' The default is \code{NULL}. |
| 35 | +#' @return [\code{\link{Learner}}]. |
| 36 | +#' @export |
| 37 | +#' @examples |
| 38 | +#' ## (1) evaluation of a learner's hyperparameters |
| 39 | +#' task = makeClassifTask(data = iris, target = "Species") |
| 40 | +#' dict = getTaskDictionary(task = task) |
| 41 | +#' lrn1 = makeLearner("classif.rpart", minsplit = expression(k * p), |
| 42 | +#' minbucket = expression(3L + 4L * task$task.desc$has.blocking)) |
| 43 | +#' lrn2 = evaluateParamExpressions(obj = lrn1, dict = dict) |
| 44 | +#' |
| 45 | +#' getHyperPars(lrn1) |
| 46 | +#' getHyperPars(lrn2) |
| 47 | +#' |
| 48 | +#' ## (2) evaluation of a learner's entire parameter set |
| 49 | +#' task = makeClassifTask(data = iris, target = "Species") |
| 50 | +#' dict = getTaskDictionary(task = task) |
| 51 | +#' lrn1 = makeLearner("classif.randomForest") |
| 52 | +#' lrn2 = evaluateParamExpressions(obj = lrn1, dict = dict) |
| 53 | +#' |
| 54 | +#' ## Note the values for parameters 'mtry', 'classwt' and 'cutoff' |
| 55 | +#' lrn1$par.set |
| 56 | +#' lrn2$par.set |
| 57 | +#' |
| 58 | +#' ## (3) evaluation of a parameter set |
| 59 | +#' task = makeClassifTask(data = iris, target = "Species") |
| 60 | +#' dict = getTaskDictionary(task = task) |
| 61 | +#' ps1 = makeParamSet( |
| 62 | +#' makeNumericParam("C", lower = expression(k), upper = expression(n), trafo = function(x) 2^x), |
| 63 | +#' makeDiscreteParam("sigma", values = expression(list(k, p))) |
| 64 | +#' ) |
| 65 | +#' ps2 = evaluateParamExpressions(obj = ps1, dict = dict) |
| 66 | +#' |
| 67 | +#' ps1 |
| 68 | +#' ps2 |
| 69 | +evaluateParamExpressions.Learner = function(obj, dict = NULL) { |
| 70 | + obj = checkLearner(obj) |
| 71 | + if (hasExpression(obj)) { |
| 72 | + assertList(dict, null.ok = TRUE) |
| 73 | + obj$par.set = evaluateParamExpressions(obj = obj$par.set, dict = dict) |
| 74 | + obj$par.vals = evaluateParamExpressions(obj = obj$par.vals, dict = dict) |
| 75 | + } |
| 76 | + return(obj) |
| 77 | +} |
0 commit comments