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:`"required"`

implies that the parameters has to be given when setting`values`

in ParamSet.

- 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`

. Log-scale`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 log-scale.`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.

## 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)
#> <ParamSet>
#> id class lower upper nlevels default
#> 1: unbounded_integer ParamInt -Inf Inf Inf <NoDefault[3]>
#> 2: bounded_double ParamDbl 0 10 Inf <NoDefault[3]>
#> 3: half_bounded_integer ParamDbl 1 Inf Inf <NoDefault[3]>
#> 4: half_bounded_double ParamDbl -Inf 1 Inf <NoDefault[3]>
#> 5: double_with_trafo ParamDbl -1 1 Inf <NoDefault[3]>
#> 6: extra_double ParamDbl 0 1 Inf <NoDefault[3]>
#> 7: factor_param ParamFct NA NA 3 <NoDefault[3]>
#> 8: factor_param_with_implicit_trafo ParamFct NA NA 3 <NoDefault[3]>
#> value
#> 1:
#> 2:
#> 3:
#> 4:
#> 5:
#> 6:
#> 7:
#> 8:
#> Trafo is set.
params$trafo(list(
bounded_double = 1,
double_with_trafo = 1,
factor_param = "c",
factor_param_with_implicit_trafo = "c"
))
#> $bounded_double
#> [1] 1
#>
#> $double_with_trafo
#> [1] 2.718282
#>
#> $factor_param
#> [1] "c"
#>
#> $factor_param_with_implicit_trafo
#> list()
#>
# logscale:
params = ps(x = p_dbl(1, 100, logscale = TRUE))
# The ParamSet has bounds log(1) .. log(100):
print(params)
#> <ParamSet>
#> id class lower upper nlevels default value
#> 1: x ParamDbl 0 4.60517 Inf <NoDefault[3]>
#> Trafo is set.
# When generating a equidistant grid, it is equidistant within log values
grid = generate_design_grid(params, 3)
print(grid)
#> <Design> with 3 rows:
#> x
#> 1: 0.000000
#> 2: 2.302585
#> 3: 4.605170
# But the values are on a log scale with desired bounds after trafo
print(grid$transpose())
#> [[1]]
#> [[1]]$x
#> [1] 1
#>
#>
#> [[2]]
#> [[2]]$x
#> [1] 10
#>
#>
#> [[3]]
#> [[3]]$x
#> [1] 100
#>
#>
# Integer parameters with logscale are `ParamDbl`s pre-trafo
params = ps(x = p_int(0, 10, logscale = TRUE))
print(params)
#> <ParamSet>
#> id class lower upper nlevels default value
#> 1: x ParamDbl -0.6931472 2.397895 Inf <NoDefault[3]>
#> Trafo is set.
grid = generate_design_grid(params, 4)
print(grid)
#> <Design> with 4 rows:
#> x
#> 1: -0.6931472
#> 2: 0.3372003
#> 3: 1.3675478
#> 4: 2.3978953
# ... but get transformed to integers.
print(grid$transpose())
#> [[1]]
#> [[1]]$x
#> [1] 0
#>
#>
#> [[2]]
#> [[2]]$x
#> [1] 1
#>
#>
#> [[3]]
#> [[3]]$x
#> [1] 3
#>
#>
#> [[4]]
#> [[4]]$x
#> [1] 10
#>
#>
```