Title: | Define and Work with Parameter Spaces for Complex Algorithms |
---|---|
Description: | Define parameter spaces, constraints and dependencies for arbitrary algorithms, to program on such spaces. Also includes statistical designs and random samplers. Objects are implemented as 'R6' classes. |
Authors: | Michel Lang [aut] , Bernd Bischl [aut] , Jakob Richter [aut] , Xudong Sun [aut] , Martin Binder [aut, cre], Marc Becker [ctb] |
Maintainer: | Martin Binder <[email protected]> |
License: | LGPL-3 |
Version: | 1.0.1 |
Built: | 2024-11-14 03:44:04 UTC |
Source: | https://github.com/mlr-org/paradox |
Define parameter spaces, constraints and dependencies for arbitrary algorithms, to program on such spaces. Also includes statistical designs and random samplers. Objects are implemented as 'R6' classes.
Maintainer: Martin Binder [email protected]
Authors:
Michel Lang [email protected] (ORCID)
Bernd Bischl [email protected] (ORCID)
Jakob Richter [email protected] (ORCID)
Xudong Sun [email protected] (ORCID)
Other contributors:
Marc Becker [email protected] (ORCID) [contributor]
Useful links:
Report bugs at https://github.com/mlr-org/paradox/issues
Assertions for Params and ParamSets
assert_param_set( param_set, cl = NULL, no_untyped = FALSE, must_bounded = FALSE, no_deps = FALSE )
assert_param_set( param_set, cl = NULL, no_untyped = FALSE, must_bounded = FALSE, no_deps = FALSE )
param_set |
( |
cl |
( |
no_untyped |
( |
must_bounded |
( |
no_deps |
( |
The checked object, invisibly.
Condition object, to specify the condition in a dependency.
condition_test(cond, x) condition_as_string(cond, lhs_chr = "x") Condition(rhs, condition_format_string)
condition_test(cond, x) condition_as_string(cond, lhs_chr = "x") Condition(rhs, condition_format_string)
cond |
( |
x |
( |
lhs_chr |
( |
rhs |
( |
condition_format_string |
( |
condition_test()
: Used internally. Tests whether a value satisfies a given condition.
Vectorizes when x
is atomic.
condition_as_string()
: Used internally. Returns a string that represents the condition for pretty
printing, in the form "<lhs> <relation> <rhs>"
, e.g. "x == 3"
or
"param %in% {1, 2, 10}"
.
CondEqual(rhs)
Value must be equal to rhs
.
CondAnyOf(rhs)
Value must be any value of rhs
.
Extract parameter default values.
default_values(x, ...) ## S3 method for class 'ParamSet' default_values(x, ...)
default_values(x, ...) ## S3 method for class 'ParamSet' default_values(x, ...)
x |
( |
... |
(any) |
list()
.
A lightweight wrapper around a ParamSet and a data.table::data.table()
, where the
latter is a design of configurations produced from the former - e.g.,
by calling a generate_design_grid()
or by sampling.
param_set
(ParamSet).
data
(data.table::data.table()
)
Stored data
.
new()
Creates a new instance of this R6 class.
Design$new(param_set, data, remove_dupl)
param_set
(ParamSet).
data
(data.table::data.table()
)
Stored data
.
remove_dupl
(logical(1)
)
Remove duplicates?
format()
Helper for print outputs.
Design$format(...)
...
(ignored).
print()
Printer.
Design$print(...)
...
(ignored).
transpose()
Converts data
into a list of lists of row-configurations,
possibly removes NA
entries of inactive parameter values due to unsatisfied dependencies,
and possibly calls the trafo
function of the ParamSet.
Design$transpose(filter_na = TRUE, trafo = TRUE)
filter_na
(logical(1)
)
Should NA
entries of inactive parameter values due to unsatisfied
dependencies be removed?
trafo
(logical(1)
)
Should the trafo
function of the ParamSet be called?
clone()
The objects of this class are cloneable with this method.
Design$clone(deep = FALSE)
deep
Whether to make a deep clone.
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, through the ParamSet
constructor itself,
or through the ParamSet
$search_space()
mechanism (see
to_tune()
).
For each of the basic parameter 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 fitting construction arguments that control their
bounds and behavior.
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, once constructed.
The Domain
object's internals are subject to change and should not be relied upon.
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, init, aggr = NULL, in_tune_fn = NULL, disable_in_tune = NULL ) p_fct( levels, special_vals = list(), default = NO_DEF, tags = character(), depends = NULL, trafo = NULL, init, aggr = NULL, in_tune_fn = NULL, disable_in_tune = NULL ) p_int( lower = -Inf, upper = Inf, special_vals = list(), default = NO_DEF, tags = character(), tolerance = sqrt(.Machine$double.eps), depends = NULL, trafo = NULL, logscale = FALSE, init, aggr = NULL, in_tune_fn = NULL, disable_in_tune = NULL ) p_lgl( special_vals = list(), default = NO_DEF, tags = character(), depends = NULL, trafo = NULL, init, aggr = NULL, in_tune_fn = NULL, disable_in_tune = NULL ) p_uty( custom_check = NULL, special_vals = list(), default = NO_DEF, tags = character(), depends = NULL, trafo = NULL, repr = substitute(default), init, aggr = NULL, in_tune_fn = NULL, disable_in_tune = NULL )
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, init, aggr = NULL, in_tune_fn = NULL, disable_in_tune = NULL ) p_fct( levels, special_vals = list(), default = NO_DEF, tags = character(), depends = NULL, trafo = NULL, init, aggr = NULL, in_tune_fn = NULL, disable_in_tune = NULL ) p_int( lower = -Inf, upper = Inf, special_vals = list(), default = NO_DEF, tags = character(), tolerance = sqrt(.Machine$double.eps), depends = NULL, trafo = NULL, logscale = FALSE, init, aggr = NULL, in_tune_fn = NULL, disable_in_tune = NULL ) p_lgl( special_vals = list(), default = NO_DEF, tags = character(), depends = NULL, trafo = NULL, init, aggr = NULL, in_tune_fn = NULL, disable_in_tune = NULL ) p_uty( custom_check = NULL, special_vals = list(), default = NO_DEF, tags = character(), depends = NULL, trafo = NULL, repr = substitute(default), init, aggr = NULL, in_tune_fn = NULL, disable_in_tune = NULL )
lower |
( |
upper |
( |
special_vals |
( |
default |
( |
tags |
(
|
tolerance |
( |
depends |
( |
trafo |
( |
logscale |
( |
init |
( |
aggr |
( |
in_tune_fn |
( |
disable_in_tune |
(named |
levels |
( |
custom_check |
( |
repr |
( |
Although the levels
values of a constructed p_fct()
will always be character
-valued, the p_fct
function admits
a levels
argument that goes beyond this:
Besides 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.
A Domain
object.
Other ParamSet construction helpers:
ps()
,
to_tune()
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 `p_dbl()`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()) # internal tuning param_set = ps( iters = p_int(0, Inf, tags = "internal_tuning", aggr = function(x) round(mean(unlist(x))), in_tune_fn = function(domain, param_vals) { stopifnot(domain$lower <= 1) stopifnot(param_vals$early_stopping == TRUE) domain$upper }, disable_in_tune = list(early_stopping = FALSE)), early_stopping = p_lgl() ) param_set$set_values( iters = to_tune(upper = 100, internal = TRUE), early_stopping = TRUE ) param_set$convert_internal_search_space(param_set$search_space()) param_set$aggr_internal_tuned_values( list(iters = list(1, 2, 3)) ) param_set$disable_internal_tuning("iters") param_set$values$early_stopping
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 `p_dbl()`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()) # internal tuning param_set = ps( iters = p_int(0, Inf, tags = "internal_tuning", aggr = function(x) round(mean(unlist(x))), in_tune_fn = function(domain, param_vals) { stopifnot(domain$lower <= 1) stopifnot(param_vals$early_stopping == TRUE) domain$upper }, disable_in_tune = list(early_stopping = FALSE)), early_stopping = p_lgl() ) param_set$set_values( iters = to_tune(upper = 100, internal = TRUE), early_stopping = TRUE ) param_set$convert_internal_search_space(param_set$search_space()) param_set$aggr_internal_tuned_values( list(iters = list(1, 2, 3)) ) param_set$disable_internal_tuning("iters") param_set$values$early_stopping
Generate a grid with a specified resolution in the parameter space. The resolution for categorical parameters is ignored, these parameters always produce a grid over all their valid levels. For number params the endpoints of the params are always included in the grid.
generate_design_grid(param_set, resolution = NULL, param_resolutions = NULL)
generate_design_grid(param_set, resolution = NULL, param_resolutions = NULL)
param_set |
( |
resolution |
( |
param_resolutions |
(named |
Other generate_design:
generate_design_lhs()
,
generate_design_random()
,
generate_design_sobol()
pset = ps( ratio = p_dbl(lower = 0, upper = 1), letters = p_fct(levels = letters[1:3]) ) generate_design_grid(pset, 10)
pset = ps( ratio = p_dbl(lower = 0, upper = 1), letters = p_fct(levels = letters[1:3]) ) generate_design_grid(pset, 10)
Generate a space-filling design using Latin hypercube sampling. Dependent
parameters whose constraints are unsatisfied generate NA
entries in
their respective columns.
generate_design_lhs(param_set, n, lhs_fun = NULL)
generate_design_lhs(param_set, n, lhs_fun = NULL)
param_set |
( |
n |
( |
lhs_fun |
( |
Other generate_design:
generate_design_grid()
,
generate_design_random()
,
generate_design_sobol()
pset = ps( ratio = p_dbl(lower = 0, upper = 1), letters = p_fct(levels = letters[1:3]) ) if (requireNamespace("lhs", quietly = TRUE)) { generate_design_lhs(pset, 10) }
pset = ps( ratio = p_dbl(lower = 0, upper = 1), letters = p_fct(levels = letters[1:3]) ) if (requireNamespace("lhs", quietly = TRUE)) { generate_design_lhs(pset, 10) }
Generates a design with randomly drawn points.
Internally uses SamplerUnif
, hence, also works for ParamSets with dependencies.
If dependencies do not hold, values are set to NA
in the resulting data.table.
generate_design_random(param_set, n)
generate_design_random(param_set, n)
param_set |
( |
n |
( |
Other generate_design:
generate_design_grid()
,
generate_design_lhs()
,
generate_design_sobol()
pset = ps( ratio = p_dbl(lower = 0, upper = 1), letters = p_fct(levels = letters[1:3]) ) generate_design_random(pset, 10)
pset = ps( ratio = p_dbl(lower = 0, upper = 1), letters = p_fct(levels = letters[1:3]) ) generate_design_random(pset, 10)
Generate a space-filling design using a Sobol sequence. Dependent
parameters whose constraints are unsatisfied generate NA
entries in
their respective columns.
Uses spacefillr::generate_sobol_set.
Note that non determinism is achieved by sampling the seed argument via
sample(.Machine$integer.max, size = 1L)
.
generate_design_sobol(param_set, n)
generate_design_sobol(param_set, n)
param_set |
( |
n |
( |
Other generate_design:
generate_design_grid()
,
generate_design_lhs()
,
generate_design_random()
pset = ps( ratio = p_dbl(lower = 0, upper = 1), letters = p_fct(levels = letters[1:3]) ) if (requireNamespace("spacefillr", quietly = TRUE)) { generate_design_sobol(pset, 10) }
pset = ps( ratio = p_dbl(lower = 0, upper = 1), letters = p_fct(levels = letters[1:3]) ) if (requireNamespace("spacefillr", quietly = TRUE)) { generate_design_sobol(pset, 10) }
Special new data type for no-default. Not often needed by the end-user, mainly internal.
NO_DEF
: Singleton object for type, used in Domain
when no default is given.
is_nodefault()
: Is an object the 'no default' object?
An object representing the space of possible parametrizations of a function or another object.
ParamSet
s are used on the side of objects being parameterized, where they function as a configuration space determining the set of possible configurations accepted by these objects.
They can also be used to specify search spaces for optimization, indicating the set of legal configurations to try out.
It is often convenient to generate search spaces from configuration spaces, which can be done using the $search_space()
method in combination with to_tune()
/ TuneToken
objects.
Individual dimensions of a ParamSet
are specified by Domain
objects, created as p_dbl()
, p_lgl()
etc.
The field $values
can be used to store an active configuration or to partially fix
some parameters to constant values – the precise effect can be determined by the object being parameterized.
Constructing a ParamSet
can be done using ParamSet$new()
in combination with a named list of Domain
objects.
This route is recommended when the set of dimensions (i.e. the members of this named list) is dynamically created, such as when the number of parameters is variable.
ParamSet
s can also be created using the ps()
shorthand, which is the recommended way when the set of parameters is fixed.
In practice, the majority of cases where a ParamSet
is created, the ps()
should be used.
as.data.table()
ParamSet
-> data.table::data.table()
Compact representation as datatable. Col types are:
id: character
class: character
lower, upper: numeric
levels: list col, with NULL elements
nlevels: integer valued numeric
is_bounded: logical
special_vals: list col of list
default: list col
storage_type: character
tags: list col of character vectors
assert_values
(logical(1)
)
Should values be checked for validity during assigment to active binding $values
?
Default is TRUE
, only switch this off if you know what you are doing.
data
(data.table
) data.table
representation of the ParamSet
.
values
(named list()
)
Currently set / fixed parameter values.
Settable, and feasibility of values will be checked when you set them.
You do not have to set values for all parameters, but only for a subset.
When you set values, all previously set values will be unset / removed.
tags
(named list()
of character()
)
Can be used to group and subset parameters.
Named with parameter IDs.
params
(named list()
)data.table
representing the combined Domain
objects used to construct the ParamSet
.
Used for internal purpuses.
Its use by external code is deprecated.
domains
(named list
of Domain
)
List of Domain
objects that could be used to initialize this ParamSet
.
extra_trafo
(function(x, param_set)
)
Transformation function. Settable.
User has to pass a function(x)
, of the form
(named list()
, ParamSet) -> named list()
.
The function is responsible to transform a feasible configuration into another encoding,
before potentially evaluating the configuration with the target algorithm.
For the output, not many things have to hold.
It needs to have unique names, and the target algorithm has to accept the configuration.
For convenience, the self-paramset is also passed in, if you need some info from it (e.g. tags).
Is NULL by default, and you can set it to NULL to switch the transformation off.
constraint
(function(x)
)
Constraint function. Settable.
This function must evaluate a named list()
of values and determine whether it satisfies
constraints, returning a scalar logical(1)
value.
deps
(data.table::data.table()
)
Table has cols id
(character(1)
) and on
(character(1)
) and cond
(Condition).
Lists all (direct) dependency parents of a param, through parameter IDs.
Internally created by a call to add_dep
.
Settable, if you want to remove dependencies or perform other changes.
length
(integer(1)
)
Number of contained parameters.
is_empty
(logical(1)
)
Is the ParamSet
empty? Named with parameter IDs.
has_trafo
(logical(1)
)
Whether a trafo
function is present, in parameters or in extra_trafo
.
has_extra_trafo
(logical(1)
)
Whether extra_trafo
is set.
has_deps
(logical(1)
)
Whether the parameter dependencies are present
has_constraint
(logical(1)
)
Whether parameter constraint is set.
all_numeric
(logical(1)
)
Is TRUE
if all parameters are p_dbl()
or p_int()
.
all_categorical
(logical(1)
)
Is TRUE
if all parameters are p_fct()
and p_lgl()
.
all_bounded
(logical(1)
)
Is TRUE
if all parameters are bounded.
class
(named character()
)
Classes of contained parameters. Named with parameter IDs.
lower
(named double()
)
Lower bounds of numeric parameters (NA
for non-numerics). Named with parameter IDs.
upper
(named double()
)
Upper bounds of numeric parameters (NA
for non-numerics). Named with parameter IDs.
levels
(named list()
of character
)
Allowed levels of categorical parameters (NULL
for non-categoricals).
Named with parameter IDs.
storage_type
(character()
)
Data types of parameters when stored in tables. Named with parameter IDs.
special_vals
(named list()
of list()
)
Special values for all parameters. Named with parameter IDs.
default
(named list()
)
Default values of all parameters. If no default exists, element is not present.
Named with parameter IDs.
has_trafo_param
(logical()
)
Whether trafo
is set for any parameter.
is_logscale
(logical()
)
Whether trafo
was set to logscale
during construction.
Note that this only refers to the logscale
flag set during construction, e.g. p_dbl(logscale = TRUE)
.
If the parameter was set to logscale manually, e.g. through p_dbl(trafo = exp)
,
this is_logscale
will be FALSE
.
nlevels
(named integer()
)
Number of distinct levels of parameters. Inf
for double parameters or unbounded integer parameters.
Named with param IDs.
is_number
(named logical()
)
Whether parameter is p_dbl()
or p_int()
. Named with parameter IDs.
is_categ
(named logical()
)
Whether parameter is p_fct()
or p_lgl()
. Named with parameter IDs.
is_bounded
(named logical()
)
Whether parameters have finite bounds. Named with parameter IDs.
new()
Creates a new instance of this R6 class.
ParamSet$new(params = named_list(), allow_dangling_dependencies = FALSE)
params
(named list()
)
List of Domain
, named with their respective ID.
allow_dangling_dependencies
(character(1)
)
Whether dependencies depending on parameters that are not present should be allowed. A parameter x
having
depends = y == 0
if y
is not present would usually throw an error, but if dangling
dependencies are allowed, the dependency is added regardless. This is mainly for internal
use.
ids()
Retrieves IDs of contained parameters based on some filter criteria
selections, NULL
means no restriction.
Only returns IDs of parameters that satisfy all conditions.
ParamSet$ids(class = NULL, tags = NULL, any_tags = NULL)
class
(character()
)
Typically a subset of "ParamDbl"
, "ParamInt"
, "ParamFct"
, "ParamLgl"
, "ParamUty"
.
Other classes are possible if implemented by 3rd party packages.
Return only IDs of dimensions with the given class.
tags
(character()
).
Return only IDs of dimensions that have all tags given in this argument.
any_tags
(character()
).
Return only IDs of dimensions that have at least one of the tags given in this argument.
character()
.
get_values()
Retrieves parameter values based on some selections, NULL
means no
restriction and is equivalent to $values
.
Only returns values of parameters that satisfy all conditions.
ParamSet$get_values( class = NULL, tags = NULL, any_tags = NULL, type = "with_token", check_required = TRUE, remove_dependencies = TRUE )
class
(character()
). See $ids()
.
tags
(character()
). See $ids()
.
any_tags
(character()
). See $ids()
.
type
(character(1)
)
Return values "with_token"
(i.e. all values),
check_required
(logical(1)
)
Check if all required parameters are set?
remove_dependencies
(logical(1)
)
If TRUE
, set values with dependencies that are not fulfilled to NULL
.
Named list()
.
set_values()
Allows to to modify (and overwrite) or replace the parameter values. Per default already set values are being kept unless new values are being provided.
ParamSet$set_values(..., .values = list(), .insert = TRUE)
...
(any)
Named parameter values.
.values
(named list()
)
Named list with parameter values. Names must not already appear in ...
.
.insert
(logical(1)
)
Whether to insert the values (old values are being kept, if not overwritten), or to
replace all values. Default is TRUE.
trafo()
Perform transformation specified by the trafo
of Domain
objects, as well as the $extra_trafo
field.
ParamSet$trafo(x, param_set = self)
x
(named list()
| data.frame
)
The value(s) to be transformed.
param_set
(ParamSet
)
Passed to extra_trafo()
. Note that the extra_trafo
of self
is used, not the extra_trafo
of the
ParamSet
given in the param_set
argument.
In almost all cases, the default param_set = self
should be used.
aggr_internal_tuned_values()
Aggregate parameter values according to their aggregation rules.
ParamSet$aggr_internal_tuned_values(x)
x
(named list()
of list()
s)
The value(s) to be aggregated. Names are parameter values.
The aggregation function is selected based on the parameter.
(named list()
)
disable_internal_tuning()
Set the parameter values so that internal tuning for the selected parameters is disabled.
ParamSet$disable_internal_tuning(ids)
ids
(character()
)
The ids of the parameters for which to disable internal tuning.
Self
convert_internal_search_space()
Convert all parameters from the search space to parameter values using the transformation given by
in_tune_fn
.
ParamSet$convert_internal_search_space(search_space)
search_space
(ParamSet
)
The internal search space.
(named list()
)
test_constraint()
checkmate-like test-function. Takes a named list.
Return FALSE
if the given $constraint
is not satisfied, TRUE
otherwise.
Note this is different from satisfying the bounds or types given by the ParamSet
itself:
If x
does not satisfy these, an error will be thrown, given that assert_value
is TRUE
.
ParamSet$test_constraint(x, assert_value = TRUE)
x
(named list()
)
The value to test.
assert_value
(logical(1)
)
Whether to verify that x
satisfies the bounds and types given by this ParamSet
.
Should be TRUE
unless this was already checked before.
logical(1)
: Whether x
satisfies the $constraint
.
test_constraint_dt()
checkmate-like test-function. Takes a data.table
.
For each row, return FALSE
if the given $constraint
is not satisfied, TRUE
otherwise.
Note this is different from satisfying the bounds or types given by the ParamSet
itself:
If x
does not satisfy these, an error will be thrown, given that assert_value
is TRUE
.
ParamSet$test_constraint_dt(x, assert_value = TRUE)
x
(data.table
)
The values to test.
assert_value
(logical(1)
)
Whether to verify that x
satisfies the bounds and types given by this ParamSet
.
Should be TRUE
unless this was already checked before.
logical
: For each row in x
, whether it satisfies the $constraint
.
check()
checkmate-like check-function. Takes a named list.
A point x is feasible, if it configures a subset of params,
all individual param constraints are satisfied and all dependencies are satisfied.
Params for which dependencies are not satisfied should not be part of x
.
Constraints and dependencies are not checked when check_strict
is FALSE
.
ParamSet$check(xs, check_strict = TRUE, sanitize = FALSE)
xs
(named list()
).
check_strict
(logical(1)
)
Whether to check that constraints and dependencies are satisfied.
sanitize
(logical(1)
)
Whether to move values that are slightly outside bounds to valid values.
These values are accepted independent of sanitize
(depending on the
tolerance
arguments of p_dbl()
and p_int()
) . If sanitize
is TRUE
, the additional effect is that, should checks pass, the
sanitized values of xs
are added to the result as attribute "sanitized"
.
If successful TRUE
, if not a string with an error message.
check_dependencies()
checkmate-like check-function. Takes a named list. Checks that all individual param dependencies are satisfied.
ParamSet$check_dependencies(xs)
xs
(named list()
).
If successful TRUE
, if not a string with an error message.
test()
checkmate-like test-function. Takes a named list.
A point x is feasible, if it configures a subset of params,
all individual param constraints are satisfied and all dependencies are satisfied.
Params for which dependencies are not satisfied should not be part of x
.
Constraints and dependencies are not checked when check_strict
is FALSE
.
ParamSet$test(xs, check_strict = TRUE)
xs
(named list()
).
check_strict
(logical(1)
)
Whether to check that constraints and dependencies are satisfied.
If successful TRUE
, if not FALSE
.
assert()
checkmate-like assert-function. Takes a named list.
A point x is feasible, if it configures a subset of params,
all individual param constraints are satisfied and all dependencies are satisfied.
Params for which dependencies are not satisfied should not be part of x
.
Constraints and dependencies are not checked when check_strict
is FALSE
.
ParamSet$assert( xs, check_strict = TRUE, .var.name = vname(xs), sanitize = FALSE )
xs
(named list()
).
check_strict
(logical(1)
)
Whether to check that constraints and dependencies are satisfied.
.var.name
(character(1)
)
Name of the checked object to print in error messages.
Defaults to the heuristic implemented in vname.
sanitize
(logical(1)
)
Whether to move values that are slightly outside bounds to valid values.
These values are accepted independent of sanitize
(depending on the
tolerance
arguments of p_dbl()
and p_int()
) . If sanitize
is TRUE
, the additional effect is that xs
is converted to within bounds.
If successful xs
invisibly, if not an error message.
check_dt()
checkmate-like check-function. Takes a data.table::data.table
where rows are points and columns are parameters.
A point x is feasible, if it configures a subset of params,
all individual param constraints are satisfied and all dependencies are satisfied.
Params for which dependencies are not satisfied should not be part of x
.
Constraints and dependencies are not checked when check_strict
is FALSE
.
ParamSet$check_dt(xdt, check_strict = TRUE)
xdt
(data.table::data.table | data.frame()
).
check_strict
(logical(1)
)
Whether to check that constraints and dependencies are satisfied.
If successful TRUE
, if not a string with the error message.
test_dt()
checkmate-like test-function (s. $check_dt()
).
ParamSet$test_dt(xdt, check_strict = TRUE)
xdt
check_strict
(logical(1)
)
Whether to check that constraints and dependencies are satisfied.
If successful TRUE
, if not FALSE
.
assert_dt()
checkmate-like assert-function (s. $check_dt()
).
ParamSet$assert_dt(xdt, check_strict = TRUE, .var.name = vname(xdt))
xdt
check_strict
(logical(1)
)
Whether to check that constraints and dependencies are satisfied.
.var.name
(character(1)
)
Name of the checked object to print in error messages.
Defaults to the heuristic implemented in vname.
If successful xs
invisibly, if not, an error is generated.
qunif()
Map a matrix
or data.frame
of values between 0 and 1 to proportional values inside the feasible intervals of individual parameters.
ParamSet$qunif(x)
x
(matrix
| data.frame
)
Values to map. Column names must be a subset of the names of parameters.
data.table
.
get_domain()
get the Domain
object that could be used to create a given parameter.
ParamSet$get_domain(id)
id
(character(1)
).
subset()
Create a new ParamSet
restricted to the passed IDs.
ParamSet$subset( ids, allow_dangling_dependencies = FALSE, keep_constraint = TRUE )
ids
(character()
).
allow_dangling_dependencies
(logical(1)
)
Whether to allow subsets that cut across parameter dependencies.
Dependencies that point to dropped parameters are kept (but will be "dangling", i.e. their "on"
will not be present).
keep_constraint
(logical(1)
)
Whether to keep the $constraint
function.
ParamSet
.
subspaces()
Create new one-dimensional ParamSet
s for each dimension.
ParamSet$subspaces(ids = private$.params$id)
ids
(character()
)
IDs for which to create ParamSet
s. Defaults to all IDs.
named list()
of ParamSet
.
flatten()
Create a ParamSet
from this object, even if this object itself is not
a ParamSet
but e.g. a ParamSetCollection
.
ParamSet$flatten()
search_space()
Construct a ParamSet
to tune over. Constructed from TuneToken
in $values
, see to_tune()
.
ParamSet$search_space(values = self$values)
values
(named list
): optional named list of TuneToken
objects to convert, in place of $values
.
add_dep()
Adds a dependency to this set, so that param id
now depends on param on
.
ParamSet$add_dep(id, on, cond, allow_dangling_dependencies = FALSE)
id
(character(1)
).
on
(character(1)
).
cond
(Condition).
allow_dangling_dependencies
(logical(1)
): Whether to allow dependencies on parameters that are not present.
format()
Helper for print outputs.
ParamSet$format()
...
(ignored).
print()
Printer.
ParamSet$print( ..., hide_cols = c("levels", "is_bounded", "special_vals", "tags", "storage_type") )
...
(ignored).
hide_cols
(character()
)
Which fields should not be printed? Default is "levels"
,
"is_bounded"
, "special_vals"
, "tags"
, and "storage_type"
.
clone()
The objects of this class are cloneable with this method.
ParamSet$clone(deep = FALSE)
deep
Whether to make a deep clone.
pset = ParamSet$new( params = list( d = p_dbl(lower = -5, upper = 5, default = 0, trafo = function(x) 2^x), f = p_fct(levels = letters[1:3]) ) ) # alternative, recommended way of construction in this case since the # parameter list is not dynamic: pset = ps( d = p_dbl(lower = -5, upper = 5, default = 0, trafo = function(x) 2^x), f = p_fct(levels = letters[1:3]) ) pset$check(list(d = 2.1, f = "a")) pset$check(list(d = 2.1, f = "d"))
pset = ParamSet$new( params = list( d = p_dbl(lower = -5, upper = 5, default = 0, trafo = function(x) 2^x), f = p_fct(levels = letters[1:3]) ) ) # alternative, recommended way of construction in this case since the # parameter list is not dynamic: pset = ps( d = p_dbl(lower = -5, upper = 5, default = 0, trafo = function(x) 2^x), f = p_fct(levels = letters[1:3]) ) pset$check(list(d = 2.1, f = "a")) pset$check(list(d = 2.1, f = "d"))
A collection of multiple ParamSet
objects.
The collection is basically a light-weight wrapper / container around references to multiple sets.
In order to ensure unique param names, every param in the collection is referred to with
"<set_id>.<param_id>", where <set_id>
is the name of the entry a given ParamSet
in the named list given during construction.
Parameters from ParamSet
with empty (i.e. ""
) set_id
are referenced
directly. Multiple ParamSet
s with set_id
""
can be combined, but their parameter names
may not overlap to avoid name clashes.
When you either ask for 'values' or set them, the operation is delegated to the individual,
contained ParamSet
references. The collection itself does not maintain a values
state.
This also implies that if you directly change values
in one of the referenced sets,
this change is reflected in the collection.
Dependencies: It is possible to currently handle dependencies
regarding parameters inside of the same set - in this case simply add the dependency to the set, best before adding the set to the collection
across sets, where a param from one set depends on the state
of a param from another set - in this case add call add_dep
on the collection.
If you call deps
on the collection, you are returned a complete table of dependencies, from sets and across sets.
paradox::ParamSet
-> ParamSetCollection
deps
(data.table::data.table()
)
Table has cols id
(character(1)
) and on
(character(1)
) and cond
(Condition).
Lists all (direct) dependency parents of a param, through parameter IDs.
Internally created by a call to add_dep
.
Settable, if you want to remove dependencies or perform other changes.
extra_trafo
(function(x, param_set)
)
Transformation function. Settable.
User has to pass a function(x)
, of the form
(named list()
, ParamSet) -> named list()
.
The function is responsible to transform a feasible configuration into another encoding,
before potentially evaluating the configuration with the target algorithm.
For the output, not many things have to hold.
It needs to have unique names, and the target algorithm has to accept the configuration.
For convenience, the self-paramset is also passed in, if you need some info from it (e.g. tags).
Is NULL by default, and you can set it to NULL to switch the transformation off.
constraint
(function(x)
)
Constraint function. Settable.
This function must evaluate a named list()
of values and determine whether it satisfies
constraints, returning a scalar logical(1)
value.
sets
(named list()
)
Read-only list
of of ParamSet
s contained in this ParamSetCollection
.
This field provides direct references to the ParamSet
objects.
paradox::ParamSet$add_dep()
paradox::ParamSet$aggr_internal_tuned_values()
paradox::ParamSet$assert()
paradox::ParamSet$assert_dt()
paradox::ParamSet$check()
paradox::ParamSet$check_dependencies()
paradox::ParamSet$check_dt()
paradox::ParamSet$format()
paradox::ParamSet$get_domain()
paradox::ParamSet$get_values()
paradox::ParamSet$ids()
paradox::ParamSet$print()
paradox::ParamSet$qunif()
paradox::ParamSet$search_space()
paradox::ParamSet$set_values()
paradox::ParamSet$subset()
paradox::ParamSet$subspaces()
paradox::ParamSet$test()
paradox::ParamSet$test_constraint()
paradox::ParamSet$test_constraint_dt()
paradox::ParamSet$test_dt()
paradox::ParamSet$trafo()
new()
Creates a new instance of this R6 class.
ParamSetCollection$new(sets, tag_sets = FALSE, tag_params = FALSE)
sets
(named list()
of ParamSet)
ParamSet objects are not cloned.
Names are used as "set_id" for the naming scheme of delegated parameters.
tag_sets
(logical(1)
)
Whether to add tags of the form "set_<set_id>"
to each parameter originating from a given ParamSet
given with name <set_id>
.
tag_params
(logical(1)
)
Whether to add tags of the form "param_<param_id>"
to each parameter with original ID <param_id>
.
add()
Adds a ParamSet
to this collection.
ParamSetCollection$add(p, n = "", tag_sets = FALSE, tag_params = FALSE)
p
(ParamSet).
n
(character(1)
)
Name to use. Default ""
.
tag_sets
(logical(1)
)
Whether to add tags of the form "set_<n>"
to the newly added parameters.
tag_params
(logical(1)
)
Whether to add tags of the form "param_<param_id>"
to each parameter with original ID <param_id>
.
disable_internal_tuning()
Set the parameter values so that internal tuning for the selected parameters is disabled.
ParamSetCollection$disable_internal_tuning(ids)
ids
(character()
)
The ids of the parameters for which to disable internal tuning.
Self
convert_internal_search_space()
Convert all parameters from the search space to parameter values using the transformation given by
in_tune_fn
.
ParamSetCollection$convert_internal_search_space(search_space)
search_space
(ParamSet
)
The internal search space.
(named list()
)
flatten()
Create a ParamSet
from this ParamSetCollection
.
ParamSetCollection$flatten()
clone()
The objects of this class are cloneable with this method.
ParamSetCollection$clone(deep = FALSE)
deep
Whether to make a deep clone.
The ps()
short form constructor uses Domain
objects (p_dbl
, p_fct
, ...) to construct ParamSet
s in a
succinct and readable way.
For more specifics also see the documentation of Domain
.
ps( ..., .extra_trafo = NULL, .constraint = NULL, .allow_dangling_dependencies = FALSE )
ps( ..., .extra_trafo = NULL, .constraint = NULL, .allow_dangling_dependencies = FALSE )
... |
( |
.extra_trafo |
( |
.constraint |
( |
.allow_dangling_dependencies |
( |
A ParamSet
object.
Other ParamSet construction helpers:
Domain()
,
to_tune()
pars = ps( a = p_int(0, 10), b = p_int(upper = 20), c = p_dbl(), e = p_fct(letters[1:3]), f = p_uty(custom_check = checkmate::check_function) ) print(pars) pars = ps( a = p_dbl(0, 1, trafo = exp), b = p_dbl(0, 1, trafo = exp), .extra_trafo = function(x, ps) { x$c <- x$a + x$b x } ) # See how the addition happens after exp()ing: pars$trafo(list(a = 0, b = 0)) pars$values = list( a = to_tune(ps(x = p_int(0, 1), .extra_trafo = function(x, param_set) list(a = x$x) )), # make 'y' depend on 'x', but they are defined in different ParamSets # Therefore we need to allow dangling dependencies here. b = to_tune(ps(y = p_int(0, 1, depends = x == 1), .extra_trafo = function(x, param_set) list(b = x$y), .allow_dangling_dependencies = TRUE )) ) pars$search_space()
pars = ps( a = p_int(0, 10), b = p_int(upper = 20), c = p_dbl(), e = p_fct(letters[1:3]), f = p_uty(custom_check = checkmate::check_function) ) print(pars) pars = ps( a = p_dbl(0, 1, trafo = exp), b = p_dbl(0, 1, trafo = exp), .extra_trafo = function(x, ps) { x$c <- x$a + x$b x } ) # See how the addition happens after exp()ing: pars$trafo(list(a = 0, b = 0)) pars$values = list( a = to_tune(ps(x = p_int(0, 1), .extra_trafo = function(x, param_set) list(a = x$x) )), # make 'y' depend on 'x', but they are defined in different ParamSets # Therefore we need to allow dangling dependencies here. b = to_tune(ps(y = p_int(0, 1, depends = x == 1), .extra_trafo = function(x, param_set) list(b = x$y), .allow_dangling_dependencies = TRUE )) ) pars$search_space()
Repeat a ParamSet
a given number of times and thus create a larger ParamSet
.
By default, the resulting parameters are prefixed with the string "repX.", where
Xcounts up from 1. It is also possible to tag parameters by their original name and by their prefix, making grouped retrieval e.g. using
$get_values()' easier.
ps_replicate( set, times = length(prefixes), prefixes = sprintf("rep%s", seq_len(times)), tag_sets = FALSE, tag_params = FALSE )
ps_replicate( set, times = length(prefixes), prefixes = sprintf("rep%s", seq_len(times)), tag_sets = FALSE, tag_params = FALSE )
set |
|
times |
( |
prefixes |
( |
tag_sets |
( |
tag_params |
( |
pset = ps( i = p_int(), z = p_lgl() ) ps_replicate(pset, 3) ps_replicate(pset, prefixes = c("first", "last")) pset$values = list(i = 1, z = FALSE) psr = ps_replicate(pset, 2, tag_sets = TRUE, tag_params = TRUE) # observe the effect of tag_sets, tag_params: psr$tags # note that values are repeated as well psr$values psr$set_values(rep1.i = 10, rep2.z = TRUE) psr$values # use `any_tags` to get subset of values. # `any_tags = ` is preferable to `tags = `, since parameters # could also have other tags. `tags = ` would require the # selected params to have the given tags exclusively. # get all values associated with the original parameter `i` psr$get_values(any_tags = "param_i") # get all values associated with the first repetition "rep1" psr$get_values(any_tags = "set_rep1")
pset = ps( i = p_int(), z = p_lgl() ) ps_replicate(pset, 3) ps_replicate(pset, prefixes = c("first", "last")) pset$values = list(i = 1, z = FALSE) psr = ps_replicate(pset, 2, tag_sets = TRUE, tag_params = TRUE) # observe the effect of tag_sets, tag_params: psr$tags # note that values are repeated as well psr$values psr$set_values(rep1.i = 10, rep2.z = TRUE) psr$values # use `any_tags` to get subset of values. # `any_tags = ` is preferable to `tags = `, since parameters # could also have other tags. `tags = ` would require the # selected params to have the given tags exclusively. # get all values associated with the original parameter `i` psr$get_values(any_tags = "param_i") # get all values associated with the first repetition "rep1" psr$get_values(any_tags = "set_rep1")
This emulates ParamSetCollection$new(sets)
, except that the result is a flat ParamSet
, not a ParamSetCollection
.
The resulting object is decoupled from the input ParamSet
objects: Unlike ParamSetCollection
, changing $values
of
the resulting object will not change the input ParamSet
$values
by reference.
This emulates ParamSetCollection$new(sets)
, which in particular means that the resulting ParamSet
has all the Domain
s
from the input sets
, but some $id
s are changed: If the ParamSet
is given in sets
with a name, then the Domain
s will
have their <id>
changed to <name in "sets">.<id>
. This is also reflected in deps.
The c()
operator, applied to ParamSet
s, is a synony for ps_union()
.
ps_union(sets, tag_sets = FALSE, tag_params = FALSE)
ps_union(sets, tag_sets = FALSE, tag_params = FALSE)
sets |
( |
tag_sets |
( |
tag_params |
( |
ps1 = ps(x = p_dbl()) ps1$values = list(x = 1) ps2 = ps(y = p_lgl()) pu = ps_union(list(ps1, ps2)) # same as: pu = c(ps1, ps2) pu pu$values pu$values$x = 2 pu$values # p1 is unchanged: ps1$values # Prefixes automatically created for named elements. # This allows repeating components. pu2 = c(one = ps1, two = ps1, ps2) pu2 pu2$values
ps1 = ps(x = p_dbl()) ps1$values = list(x = 1) ps2 = ps(y = p_lgl()) pu = ps_union(list(ps1, ps2)) # same as: pu = c(ps1, ps2) pu pu$values pu$values$x = 2 pu$values # p1 is unchanged: ps1$values # Prefixes automatically created for named elements. # This allows repeating components. pu2 = c(one = ps1, two = ps1, ps2) pu2 pu2$values
Creates a ParamSetCollection
.
psc(...)
psc(...)
... |
(any) |
This is the abstract base class for sampling objects like Sampler1D, SamplerHierarchical or SamplerJointIndep.
param_set
(ParamSet
)
Domain / support of the distribution we want to sample from.
new()
Creates a new instance of this R6 class.
Note that this object is typically constructed via derived classes, e.g., Sampler1D.
Sampler$new(param_set)
sample()
Sample n
values from the distribution.
Sampler$sample(n)
n
(integer(1)
).
format()
Helper for print outputs.
Sampler$format(...)
...
(ignored).
print()
Printer.
Sampler$print(...)
...
(ignored).
clone()
The objects of this class are cloneable with this method.
Sampler$clone(deep = FALSE)
deep
Whether to make a deep clone.
Other Sampler:
Sampler1D
,
Sampler1DCateg
,
Sampler1DNormal
,
Sampler1DRfun
,
Sampler1DUnif
,
SamplerHierarchical
,
SamplerJointIndep
,
SamplerUnif
1D sampler, abstract base class for Sampler like Sampler1DUnif, Sampler1DRfun, Sampler1DCateg and Sampler1DNormal.
paradox::Sampler
-> Sampler1D
new()
Creates a new instance of this R6 class.
Note that this object is typically constructed via derived classes,
e.g., Sampler1DUnif
.
Sampler1D$new(param)
param
(ParamSet
)
Domain / support of the distribution we want to sample from.
Must be one-dimensional.
clone()
The objects of this class are cloneable with this method.
Sampler1D$clone(deep = FALSE)
deep
Whether to make a deep clone.
Other Sampler:
Sampler
,
Sampler1DCateg
,
Sampler1DNormal
,
Sampler1DRfun
,
Sampler1DUnif
,
SamplerHierarchical
,
SamplerJointIndep
,
SamplerUnif
Sampling from a discrete distribution, for a ParamSet
containing a single p_fct()
or p_lgl()
.
paradox::Sampler
-> paradox::Sampler1D
-> Sampler1DCateg
prob
(numeric()
| NULL)
Numeric vector of param$nlevels
probabilities.
new()
Creates a new instance of this R6 class.
Sampler1DCateg$new(param, prob = NULL)
param
(ParamSet
)
Domain / support of the distribution we want to sample from.
Must be one-dimensional.
prob
(numeric()
| NULL)
Numeric vector of param$nlevels
probabilities, which is uniform by default.
clone()
The objects of this class are cloneable with this method.
Sampler1DCateg$clone(deep = FALSE)
deep
Whether to make a deep clone.
Other Sampler:
Sampler
,
Sampler1D
,
Sampler1DNormal
,
Sampler1DRfun
,
Sampler1DUnif
,
SamplerHierarchical
,
SamplerJointIndep
,
SamplerUnif
Normal sampling (potentially truncated) for p_dbl()
.
paradox::Sampler
-> paradox::Sampler1D
-> paradox::Sampler1DRfun
-> Sampler1DNormal
mean
(numeric(1)
)
Mean parameter of the normal distribution.
sd
(numeric(1)
)
SD parameter of the normal distribution.
new()
Creates a new instance of this R6 class.
Sampler1DNormal$new(param, mean = NULL, sd = NULL)
param
(ParamSet
)
Domain / support of the distribution we want to sample from.
Must be one-dimensional.
mean
(numeric(1)
)
Mean parameter of the normal distribution.
Default is mean(c(param$lower, param$upper)
.
sd
(numeric(1)
)
SD parameter of the normal distribution.
Default is (param$upper - param$lower)/4
.
clone()
The objects of this class are cloneable with this method.
Sampler1DNormal$clone(deep = FALSE)
deep
Whether to make a deep clone.
Other Sampler:
Sampler
,
Sampler1D
,
Sampler1DCateg
,
Sampler1DRfun
,
Sampler1DUnif
,
SamplerHierarchical
,
SamplerJointIndep
,
SamplerUnif
Arbitrary sampling from 1D RNG functions from R.
paradox::Sampler
-> paradox::Sampler1D
-> Sampler1DRfun
rfun
(function()
)
Random number generator function.
trunc
(logical(1)
)TRUE
enables naive rejection sampling, so we stay inside of [lower, upper].
new()
Creates a new instance of this R6 class.
Sampler1DRfun$new(param, rfun, trunc = TRUE)
param
(ParamSet
)
Domain / support of the distribution we want to sample from.
Must be one-dimensional.
rfun
(function()
)
Random number generator function, e.g. rexp
to sample from exponential distribution.
trunc
(logical(1)
)TRUE
enables naive rejection sampling, so we stay inside of [lower, upper].
clone()
The objects of this class are cloneable with this method.
Sampler1DRfun$clone(deep = FALSE)
deep
Whether to make a deep clone.
Other Sampler:
Sampler
,
Sampler1D
,
Sampler1DCateg
,
Sampler1DNormal
,
Sampler1DUnif
,
SamplerHierarchical
,
SamplerJointIndep
,
SamplerUnif
Uniform random sampler for arbitrary (bounded) parameters.
paradox::Sampler
-> paradox::Sampler1D
-> Sampler1DUnif
new()
Creates a new instance of this R6 class.
Sampler1DUnif$new(param)
param
(ParamSet
)
Domain / support of the distribution we want to sample from.
Must be one-dimensional.
clone()
The objects of this class are cloneable with this method.
Sampler1DUnif$clone(deep = FALSE)
deep
Whether to make a deep clone.
Other Sampler:
Sampler
,
Sampler1D
,
Sampler1DCateg
,
Sampler1DNormal
,
Sampler1DRfun
,
SamplerHierarchical
,
SamplerJointIndep
,
SamplerUnif
Hierarchical sampling for arbitrary param sets with dependencies, where the user specifies 1D samplers per param.
Dependencies are topologically sorted, parameters are then sampled in topological order,
and if dependencies do not hold, values are set to NA
in the resulting data.table
.
paradox::Sampler
-> SamplerHierarchical
samplers
(list()
)
List of Sampler1D
objects that gives a Sampler for each dimension in the param_set
.
new()
Creates a new instance of this R6 class.
SamplerHierarchical$new(param_set, samplers)
clone()
The objects of this class are cloneable with this method.
SamplerHierarchical$clone(deep = FALSE)
deep
Whether to make a deep clone.
Other Sampler:
Sampler
,
Sampler1D
,
Sampler1DCateg
,
Sampler1DNormal
,
Sampler1DRfun
,
Sampler1DUnif
,
SamplerJointIndep
,
SamplerUnif
Create joint, independent sampler out of multiple other samplers.
paradox::Sampler
-> SamplerJointIndep
samplers
(list()
)
List of Sampler
objects.
new()
Creates a new instance of this R6 class.
SamplerJointIndep$new(samplers)
samplers
(list()
)
List of Sampler
objects.
clone()
The objects of this class are cloneable with this method.
SamplerJointIndep$clone(deep = FALSE)
deep
Whether to make a deep clone.
Other Sampler:
Sampler
,
Sampler1D
,
Sampler1DCateg
,
Sampler1DNormal
,
Sampler1DRfun
,
Sampler1DUnif
,
SamplerHierarchical
,
SamplerUnif
Uniform random sampling for an arbitrary (bounded) ParamSet. Constructs 1 uniform sampler per parameter, then passes them to SamplerHierarchical. Hence, also works for ParamSets sets with dependencies.
paradox::Sampler
-> paradox::SamplerHierarchical
-> SamplerUnif
new()
Creates a new instance of this R6 class.
SamplerUnif$new(param_set)
clone()
The objects of this class are cloneable with this method.
SamplerUnif$clone(deep = FALSE)
deep
Whether to make a deep clone.
Other Sampler:
Sampler
,
Sampler1D
,
Sampler1DCateg
,
Sampler1DNormal
,
Sampler1DRfun
,
Sampler1DUnif
,
SamplerHierarchical
,
SamplerJointIndep
to_tune()
creates a TuneToken
object which can be assigned to the $values
slot of a ParamSet
as an
alternative to a concrete value. This indicates that the value is not given directly but should be tuned using
bbotk or mlr3tuning. If the thus parameterized object
is invoked directly, without being wrapped by or given to a tuner, it will give an error.
The tuning range ParamSet
that is constructed from the TuneToken
values in a ParamSet
's $values
slot
can be accessed through the ParamSet$search_space()
method. This is done automatically by tuners if no tuning range
is given, but it is also possible to access the $search_space()
method, modify it further, and give the modified
ParamSet
to a tuning function (or do anything else with it, nobody is judging you).
A TuneToken
represents the range over which the parameter whose $values
slot it occupies should be tuned over. It
can be constructed via the to_tune()
function in one of several ways:
to_tune()
: Indicates a parameter should be tuned over its entire range. Only applies to finite parameters
(i.e. discrete or bounded numeric parameters)
to_tune(lower, upper, logscale)
: Indicates a numeric parameter should be tuned in the inclusive interval spanning
lower
to upper
, possibly on a log scale if logscale
is se to TRUE
. All parameters are optional, and the
parameter's own lower / upper bounds are used without log scale, by default. Depending on the parameter,
integer (if it is a p_int()
) or real values (if it is a p_dbl()
) are used.lower
, upper
, and logscale
can be given by position, except when only one of them is given, in which case
it must be named to disambiguate from the following cases.
When logscale
is TRUE
, then a trafo
is generated automatically that transforms to the given bounds. The
bounds are log()'d pre-trafo (see examples). See the logscale
argument of Domain
functions for more info.
Note that "logscale" is not inherited from the Domain
that the TuneToken
belongs to! Defining a parameter
with p_dbl(... logscale = TRUE)
will not automatically give the to_tune()
assigned to it log-scale.
to_tune(levels)
: Indicates a parameter should be tuned through the given discrete values. levels
can be any
named or unnamed atomic vector or list (although in the unnamed case it must be possible to construct a
corresponding character
vector with distinct values using as.character
).
to_tune(<Domain>)
: The given Domain
object (constructed e.g. with p_int()
or p_fct()
) indicates
the range which should be tuned over. The supplied trafo
function is used for parameter transformation.
to_tune(<ParamSet>)
: The given ParamSet
is used to tune over a single dimension. This is useful for cases
where a single evaluation-time parameter value (e.g. p_uty()
) is constructed from multiple tuner-visible
parameters (which may not be p_uty()
). If not one-dimensional, the supplied ParamSet
should always contain a $extra_trafo
function,
which must then always return a list
with a single entry.
The TuneToken
object's internals are subject to change and should not be relied upon. TuneToken
objects should
only be constructed via to_tune()
, and should only be used by giving them to $values
of a ParamSet
.
to_tune(..., internal = !is.null(aggr), aggr = NULL)
to_tune(..., internal = !is.null(aggr), aggr = NULL)
... |
if given, restricts the range to be tuning over, as described above. |
internal |
( |
aggr |
( |
A TuneToken
object.
Other ParamSet construction helpers:
Domain()
,
ps()
params = ps( int = p_int(0, 10), int_unbounded = p_int(), dbl = p_dbl(0, 10), dbl_unbounded = p_dbl(), dbl_bounded_below = p_dbl(lower = 1), fct = p_fct(c("a", "b", "c")), uty1 = p_uty(), uty2 = p_uty(), uty3 = p_uty(), uty4 = p_uty(), uty5 = p_uty() ) params$values = list( # tune over entire range of `int`, 0..10: int = to_tune(), # tune over 2..7: int_unbounded = to_tune(2, 7), # tune on a log scale in range 1..10; # recognize upper bound of 10 automatically, but restrict lower bound to 1: dbl = to_tune(lower = 1, logscale = TRUE), ## This is equivalent to the following: # dbl = to_tune(p_dbl(log(1), log(10), trafo = exp)), # nothing keeps us from tuning a dbl over integer values dbl_unbounded = to_tune(p_int(1, 10)), # tune over values "a" and "b" only fct = to_tune(c("a", "b")), # tune over integers 2..8. # ParamUty needs type information in form of p_xxx() in to_tune. uty1 = to_tune(p_int(2, 8)), # tune uty2 like a factor, trying 1, 10, and 100: uty2 = to_tune(c(1, 10, 100)), # tune uty3 like a factor. The factor levels are the names of the list # ("exp", "square"), but the trafo will generate the values from the list. # This way you can tune an objective that has function-valued inputs. uty3 = to_tune(list(exp = exp, square = function(x) x^2)), # tune through multiple parameters. When doing this, the ParamSet in tune() # must have the trafo that generates a list with one element and the right # name: uty4 = to_tune(ps( base = p_dbl(0, 1), exp = p_int(0, 3), .extra_trafo = function(x, param_set) { list(uty4 = x$base ^ x$exp) } )), # not all values need to be tuned! uty5 = 100 ) print(params$values) print(params$search_space()) # Change `$values` directly and generate new `$search_space()` to play around params$values$uty3 = 8 params$values$uty2 = to_tune(c(2, 4, 8)) print(params$search_space()) # Notice how `logscale` applies `log()` to lower and upper bound pre-trafo: params = ps(x = p_dbl()) params$values$x = to_tune(1, 100, logscale = TRUE) print(params$search_space()) grid = generate_design_grid(params$search_space(), 3) # The grid is equidistant within log-bounds pre-trafo: print(grid) # But the values are on a log scale scale with desired bounds after trafo: print(grid$transpose())
params = ps( int = p_int(0, 10), int_unbounded = p_int(), dbl = p_dbl(0, 10), dbl_unbounded = p_dbl(), dbl_bounded_below = p_dbl(lower = 1), fct = p_fct(c("a", "b", "c")), uty1 = p_uty(), uty2 = p_uty(), uty3 = p_uty(), uty4 = p_uty(), uty5 = p_uty() ) params$values = list( # tune over entire range of `int`, 0..10: int = to_tune(), # tune over 2..7: int_unbounded = to_tune(2, 7), # tune on a log scale in range 1..10; # recognize upper bound of 10 automatically, but restrict lower bound to 1: dbl = to_tune(lower = 1, logscale = TRUE), ## This is equivalent to the following: # dbl = to_tune(p_dbl(log(1), log(10), trafo = exp)), # nothing keeps us from tuning a dbl over integer values dbl_unbounded = to_tune(p_int(1, 10)), # tune over values "a" and "b" only fct = to_tune(c("a", "b")), # tune over integers 2..8. # ParamUty needs type information in form of p_xxx() in to_tune. uty1 = to_tune(p_int(2, 8)), # tune uty2 like a factor, trying 1, 10, and 100: uty2 = to_tune(c(1, 10, 100)), # tune uty3 like a factor. The factor levels are the names of the list # ("exp", "square"), but the trafo will generate the values from the list. # This way you can tune an objective that has function-valued inputs. uty3 = to_tune(list(exp = exp, square = function(x) x^2)), # tune through multiple parameters. When doing this, the ParamSet in tune() # must have the trafo that generates a list with one element and the right # name: uty4 = to_tune(ps( base = p_dbl(0, 1), exp = p_int(0, 3), .extra_trafo = function(x, param_set) { list(uty4 = x$base ^ x$exp) } )), # not all values need to be tuned! uty5 = 100 ) print(params$values) print(params$search_space()) # Change `$values` directly and generate new `$search_space()` to play around params$values$uty3 = 8 params$values$uty2 = to_tune(c(2, 4, 8)) print(params$search_space()) # Notice how `logscale` applies `log()` to lower and upper bound pre-trafo: params = ps(x = p_dbl()) params$values$x = to_tune(1, 100, logscale = TRUE) print(params$search_space()) grid = generate_design_grid(params$search_space(), 3) # The grid is equidistant within log-bounds pre-trafo: print(grid) # But the values are on a log scale scale with desired bounds after trafo: print(grid$transpose())