paradox: Domain – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

Domain

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 ParamSets, 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 relid 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.

Value

A Domain object.

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 pre-trafo
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())

paradox

Define and Work with Parameter Spaces for Complex Algorithms

v0.7.1

LGPL-3

Authors

Michel Lang [cre, aut] (<https://orcid.org/0000-0001-9754-0393>), Bernd Bischl [aut] (<https://orcid.org/0000-0001-6002-6980>), Jakob Richter [aut] (<https://orcid.org/0000-0003-4481-5554>), Xudong Sun [aut] (<https://orcid.org/0000-0003-3269-2307>), Martin Binder [aut], Marc Becker [ctb] (<https://orcid.org/0000-0002-8115-0400>)

Initial release