Domain: Parameter Range without an Id
Description
A Domain
object is a representation of a single dimension of a ParamSet
. Domain
objects are used to construct
ParamSet
s, either through the ps()
short form, or through the ParamSet
$search_space()
mechanism (see
to_tune()
). Domain
corresponds to a Param
object, except it does not have an $id
, and it does have a
trafo
and dependencies (depends
) associated with it. For each of the basic Param
classes (ParamInt
,
ParamDbl
, ParamLgl
, ParamFct
, and ParamUty
) there is a function constructing a Domain
object
(p_int()
, p_dbl()
, p_lgl()
, p_fct()
, p_uty()
). They each have the same arguments as the corresponding
Param
$new()
function, except without the id
argument, and with the the additional parameters trafo
, and
depends
.
Domain
objects are representations of parameter ranges and are intermediate objects to be used in short form
constructions in to_tune()
and ps()
. Because of their nature, they should not be modified by the user.
The Domain
object's internals are subject to change and should not be relied upon.
Usage
p_int(
lower = Inf,
upper = Inf,
special_vals = list(),
default = NO_DEF,
tags = character(),
depends = NULL,
trafo = NULL,
logscale = FALSE
)
p_dbl(
lower = Inf,
upper = Inf,
special_vals = list(),
default = NO_DEF,
tags = character(),
tolerance = sqrt(.Machine$double.eps),
depends = NULL,
trafo = NULL,
logscale = FALSE
)
p_uty(
default = NO_DEF,
tags = character(),
custom_check = NULL,
depends = NULL,
trafo = NULL
)
p_lgl(
special_vals = list(),
default = NO_DEF,
tags = character(),
depends = NULL,
trafo = NULL
)
p_fct(
levels,
special_vals = list(),
default = NO_DEF,
tags = character(),
depends = NULL,
trafo = NULL
)
Arguments
lower 
(numeric(1) )
Lower bound, can be Inf .

upper 
(numeric(1) )
Upper bound can be +Inf .

special_vals 
(list() )
Arbitrary special values this parameter is allowed to take, to make it
feasible. This allows extending the domain of the parameter. Note that
these values are only used in feasibility checks, neither in generating
designs nor sampling.

default 
(any )
Default value. Can be from the domain of the parameter or an element of
special_vals . Has value NO_DEF if no default exists. NULL can be a
valid default.
The value has no effect on ParamSet$values or the behavior of
ParamSet$check() , $test() or $assert() .
The default is intended to be used for documentation purposes.
'

tags 
(character() )
Arbitrary tags to group and subset parameters. Some tags serve a special
purpose:

depends 
(call  expression )
An expression indicating a requirement for the parameter that will be constructed from this. Can be given as an
expression (using quote() ), or the expression can be entered directly and will be parsed using NSE (see
examples). The expression may be of the form <Param> == <value> or <Param> %in% <values> , which will result in
dependencies according to ParamSet$add_dep(on = "<Param>", cond = CondEqual$new(<value>)) or
ParamSet$add_dep(on = "<Param>", cond = CondAnyOf$new(<values>)) , respectively (see CondEqual ,
CondAnyOf ). The expression may also contain multiple conditions separated by && .

trafo 
(function )
Single argument function performing the transformation of a parameter. When the Domain is used to construct a
ParamSet , this transformation will be applied to the corresponding parameter as part of the $trafo function.
Note that the trafo is not inherited by TuneToken s! Defining a parameter
with e.g. p_dbl(..., trafo = ...) will not automatically give the to_tune() assigned to it a transformation.
trafo only makes sense for ParamSet s that get used as search spaces for optimization or tuning, it is not useful when
defining domains or hyperparameter ranges of learning algorithms, because these do not use trafos.

logscale 
(logical(1) )
Put numeric domains on a log scale. Default FALSE . Logscale Domain s represent parameter ranges where lower and upper bounds
are logarithmized, and where a trafo is added that exponentiates sampled values to the original scale. This is
not the same as setting trafo = exp , because logscale = TRUE will handle parameter bounds internally:
a p_dbl(1, 10, logscale = TRUE) results in a ParamDbl that has lower bound 0 , upper bound log(10) ,
and uses exp transformation on these. Therefore, the given bounds represent the bounds after the transformation.
(see examples).
p_int() with logscale = TRUE results in a ParamDbl , not a ParamInt , but with bounds log(max(lower, 0.5)) ...
log(upper + 1) and a trafo similar to "as.integer(exp(x)) " (with additional bounds correction). The lower bound
is lifted to 0.5 if lower 0 to handle the lower == 0 case. The upper bound is increased to log(upper + 1)
because the trafo would otherwise almost never generate a value of upper .
When logscale is TRUE , then upper bounds may be infinite, but lower bounds should be greater than 0 for p_dbl()
or greater or equal 0 for p_int() .
Note that "logscale" is not inherited by TuneToken s! Defining a parameter
with p_dbl(... logscale = TRUE) will not automatically give the to_tune() assigned to it logscale. logscale
only makes sense for ParamSet s that get used as search spaces for optimization or tuning, it is not useful when
defining domains or hyperparameter ranges of learning algorithms, because these do not use trafos.
logscale happens on a natural (e == 2.718282... ) basis. Be aware that using a different base (log10() /10^ ,
log2() /2^ ) is completely equivalent and does not change the values being sampled after transformation.

tolerance 
(numeric(1) )
Initializes the $tolerance field that determines the

custom_check 
(function() )
Custom function to check the feasibility.
Function which checks the input.
Must return 'TRUE' if the input is valid and a character(1) with the error message otherwise.
This function should not throw an error.
Defaults to NULL , which means that no check is performed.

levels 
(character  atomic  list )
Allowed categorical values of the parameter. If this is not a character , then a trafo is generated that
converts the names (if not given: as.character() of the values) of the levels argument to the values.
This trafo is then performed before the function given as the trafo argument.

Details
The p_fct
function admits a levels
argument that goes beyond the levels
accepted by ParamFct
$new()
.
Instead of a character
vector, any atomic vector or list (optionally named) may be given. (If the value is a list
that is not named, the names are inferred using as.character()
on the values.) The resulting Domain
will
correspond to a range of values given by the names of the levels
argument with a trafo
that maps the character
names to the arbitrary values of the levels
argument.
Value
A Domain
object.
See Also
Other ParamSet construction helpers:
ps()
,
to_tune()
Examples
params = ps(
unbounded_integer = p_int(),
bounded_double = p_dbl(0, 10),
half_bounded_integer = p_dbl(1),
half_bounded_double = p_dbl(upper = 1),
double_with_trafo = p_dbl(1, 1, trafo = exp),
extra_double = p_dbl(0, 1, special_vals = list("xxx"), tags = "tagged"),
factor_param = p_fct(c("a", "b", "c")),
factor_param_with_implicit_trafo = p_fct(list(a = 1, b = 2, c = list()))
)
print(params)
params$trafo(list(
bounded_double = 1,
double_with_trafo = 1,
factor_param = "c",
factor_param_with_implicit_trafo = "c"
))
# logscale:
params = ps(x = p_dbl(1, 100, logscale = TRUE))
# The ParamSet has bounds log(1) .. log(100):
print(params)
# When generating a equidistant grid, it is equidistant within log values
grid = generate_design_grid(params, 3)
print(grid)
# But the values are on a log scale with desired bounds after trafo
print(grid$transpose())
# Integer parameters with logscale are `ParamDbl`s pretrafo
params = ps(x = p_int(0, 10, logscale = TRUE))
print(params)
grid = generate_design_grid(params, 4)
print(grid)
# ... but get transformed to integers.
print(grid$transpose())