Package 'ParamHelpers'

Description

Changes the argument in-place. Note that when adding parameters that have associated transformations, it is probably best to add the untransformed values to the path. Otherwise you have to switch off the feasibility check, as constraints might now not hold anymore.

Dependent parameters whose requirements are not satisfied must be represented by a scalar NA in the input.

Usage

addOptPathEl(
  op,
  x,
  y,
  dob = getOptPathLength(op) + 1L,
  eol = as.integer(NA),
  error.message = NA_character_,
  exec.time = NA_real_,
  extra = NULL,
  check.feasible = !op$add.transformed.x
)

Arguments

Value

Nothing.

See Also

Other optpath: OptPath, getOptPathBestIndex(), getOptPathCols(), getOptPathCol(), getOptPathDOB(), getOptPathEOL(), getOptPathEl(), getOptPathErrorMessages(), getOptPathExecTimes(), getOptPathLength(), getOptPathParetoFront(), getOptPathX(), getOptPathY(), setOptPathElDOB(), setOptPathElEOL()

Examples

ps = makeParamSet(
  makeNumericParam("p1"),
  makeDiscreteParam("p2", values = c("a", "b"))
)
op = makeOptPathDF(par.set = ps, y.names = "y", minimize = TRUE)
addOptPathEl(op, x = list(p1 = 7, p2 = "b"), y = 1)
addOptPathEl(op, x = list(p1 = -1, p2 = "a"), y = 2)
as.data.frame(op)

Description

The following types of columns are created:

If you want to convert these, look at BBmisc::convertDataFrameCols(). Dependent parameters whose constraints are unsatisfied generate NA entries in their respective columns. Factor columns of discrete parameters always have their complete level set from the param.set.

Usage

## S3 method for class 'OptPathDF'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  include.x = TRUE,
  include.y = TRUE,
  include.rest = TRUE,
  dob = x$env$dob,
  eol = x$env$eol,
  ...
)

Arguments

Value

data.frame.

Description

Checks whether the default values of the numerical parameters are located within the corresponding boundaries. In case of discrete parameters it checks whether the values are a subset of the parameter's possible values.

Usage

checkParamSet(par.set, dict = NULL)

Arguments

Value

TRUE on success. An exception is raised otherwise.

Examples

ps = makeParamSet(
  makeNumericParam("u", lower = expression(p)),
  makeIntegerParam("v", lower = 1, upper = expression(3 * p)),
  makeDiscreteParam("w", default = expression(z), values = c("a", "b")),
  makeDiscreteParam("x", default = "a", values = c("a", "b")),
  keys = c("p", "z")
)
checkParamSet(ps, dict = list(p = 3, z = "b"))

Description

Converts to a textual description used in irace and then potentially calls readParameters.

Usage

convertParamSetToIrace(par.set, as.chars = FALSE)

Arguments

Value

[list()].

Description

Please note that (naturally) the columns of df have to be of the correct type w.r.t. the corresponding parameter. The only exception are integer parameters where the corresponding columns in df are allowed to be numerics. And also see the argument enforce.col.types as a way around this restriction.

Dependent parameters whose requirements are not satisfied are represented by a scalar NA in the output.

Usage

dfRowsToList(df, par.set, enforce.col.types = FALSE, ...)

dfRowToList(df, par.set, i, enforce.col.types = FALSE, ...)

Arguments

Value

list. Named by parameter ids.

Description

For a discrete parameter or discrete vector. If the name is NA, indicating a missing parameter value due to unsatisfied requirements, NA is returned.

Usage

discreteNameToValue(par, name)

Arguments

Value

any. Parameter value for a discrete parameter or a list of values for a discrete vector.

Examples

p = makeDiscreteParam("u", values = c(x1 = "a", x2 = "b", x3 = "b"))
discreteNameToValue(p, "x3")

Description

For a discrete parameter or discrete vector. If the value x is NA, indicating a missing parameter value due to unsatisfied requirements, NA is returned.

Usage

discreteValueToName(par, x)

Arguments

Value

character. Single name for a discrete parameter or a character vector of names for a discrete vector.

Examples

p = makeDiscreteParam("u", values = c(x1 = "a", x2 = "b", x3 = "c"))
discreteValueToName(p, "b")

Description

Drop Params from ParamSet by ids.

Usage

dropParams(par.set, drop)

Arguments

Value

[ParamSet()].

Description

Evaluates the expressions of a parameter, parameter set or list of parameters for a given dictionary.

Usage

evaluateParamExpressions(obj, dict = NULL)

Arguments

Value

[Param() | ParamHelpers::ParamSet() | list].

Examples

ps = makeParamSet(
  makeNumericParam("x", lower = expression(p), upper = expression(ceiling(3 * p))),
  makeIntegerParam("y", lower = 1, upper = 2)
)
evaluateParamExpressions(ps, dict = list(p = 3))

ps = makeParamSet(
  makeNumericParam("x", default = expression(sum(data$Species == "setosa"))),
  makeIntegerParam("y", lower = 1, upper = 2),
  keys = c("data", "Species")
)
evaluateParamExpressions(ps, dict = list(data = iris))

par.vals = list(
  x = expression(k),
  y = 5
)
evaluateParamExpressions(par.vals, dict = list(k = 3))

Description

Parameter order is not changed. It is possible to filter via multiple arguments, e.g., first filter based on id, then the type and lastly tunable. The order in which the filters are executed is always fixed (id > type > tunable).

Usage

filterParams(
  par.set,
  ids = NULL,
  type = NULL,
  tunable = c(TRUE, FALSE),
  check.requires = FALSE
)

filterParamsNumeric(
  par.set,
  ids = NULL,
  tunable = c(TRUE, FALSE),
  include.int = TRUE
)

filterParamsDiscrete(
  par.set,
  ids = NULL,
  tunable = c(TRUE, FALSE),
  include.logical = TRUE
)

Arguments

Value

ParamSet().

Examples

ps = makeParamSet(
  makeNumericParam("u", lower = 1),
  makeIntegerParam("v", lower = 1, upper = 2),
  makeDiscreteParam("w", values = 1:2),
  makeLogicalParam("x"),
  makeCharacterParam("s"),
  makeNumericParam("y", tunable = FALSE)
)

# filter for numeric and integer parameters
filterParams(ps, type = c("integer", "numeric"))

# filter for tunable, numeric parameters
filterParams(ps, type = "numeric", tunable = TRUE)

# filter for all numeric parameters among "u", "v" and "x"
filterParams(ps, type = "numeric", ids = c("u", "v", "x"))

Description

The following types of columns are created:

If you want to convert these, look at BBmisc::convertDataFrameCols(). Dependent parameters whose constraints are unsatisfied generate NA entries in their respective columns. For discrete vectors the levels and their order will be preserved, even if not all levels are present.

Currently only lhs designs are supported.

The algorithm currently iterates the following steps:

1. We create a space filling design for all parameters, disregarding requires, a trafo or the forbidden region.

2. Forbidden points are removed.

3. Parameters are trafoed (potentially, depending on the setting of argument trafo); dependent parameters whose constraints are unsatisfied are set to NA entries.

4. Duplicated design points are removed. Duplicated points are not generated in a reasonable space-filling design, but the way discrete parameters and also parameter dependencies are handled make this possible.

5. If we removed some points, we now try to augment the design in a space-filling way and iterate.

Note that augmenting currently is somewhat experimental as we simply generate missing points via new calls to lhs::randomLHS(), but do not add points so they are maximally far away from the already present ones. The reason is that the latter is quite hard to achieve with complicated dependencies and forbidden regions, if one wants to ensure that points actually get added... But we are working on it.

Note that if you have trafos attached to your params, the complete creation of the design (except for the detection of invalid parameters w.r.t to their requires setting) takes place on the UNTRANSFORMED scale. So this function creates, e.g., a maximin LHS design on the UNTRANSFORMED scale, but not necessarily the transformed scale.

generateDesign will NOT work if there are dependencies over multiple levels of parameters and the dependency is only given with respect to the “previous” parameter. A current workaround is to state all dependencies on all parameters involved. (We are working on it.)

Usage

generateDesign(
  n = 10L,
  par.set,
  fun,
  fun.args = list(),
  trafo = FALSE,
  augment = 20L
)

Arguments

Value

data.frame. Columns are named by the ids of the parameters. If the par.set argument contains a vector parameter, its corresponding column names in the design are the parameter id concatenated with 1 to dimension of the vector. The result will have an logical(1) attribute “trafo”, which is set to the value of argument trafo.

Examples

ps = makeParamSet(
  makeNumericParam("x1", lower = -2, upper = 1),
  makeIntegerParam("x2", lower = 10, upper = 20)
)
# random latin hypercube design with 5 samples:
generateDesign(5, ps)

# with trafo
ps = makeParamSet(
  makeNumericParam("x", lower = -2, upper = 1),
  makeNumericVectorParam("y", len = 2, lower = 0, upper = 1, trafo = function(x) x / sum(x))
)
generateDesign(10, ps, trafo = TRUE)

Description

The following types of columns are created:

This will create a design containing only one point at the default values of the supplied param set. In most cases you will combine the resulting data.frame with a different generation function e.g. generateDesign(), generateRandomDesign() or generateGridDesign(). This is useful to force an evaluation at the default location of the parameters while still generating a design. Parameters default values, whose conditions (requires) are not fulfilled will be set to NA in the result.

Usage

generateDesignOfDefaults(par.set, trafo = FALSE)

Arguments

Value

data.frame. Columns are named by the ids of the parameters. If the par.set argument contains a vector parameter, its corresponding column names in the design are the parameter id concatenated with 1 to dimension of the vector. The result will have an logical(1) attribute “trafo”, which is set to the value of argument trafo.

Description

The following types of columns are created:

If you want to convert these, look at BBmisc::convertDataFrameCols(). Dependent parameters whose constraints are unsatisfied generate NA entries in their respective columns. For discrete vectors the levels and their order will be preserved.

The algorithm currently performs these steps:

1. We create a grid. For numerics and integers we use the specified resolution. For discretes all values will be taken.

2. Forbidden points are removed.

3. Parameters are trafoed (potentially, depending on the setting of argument trafo); dependent parameters whose constraints are unsatisfied are set to NA entries.

4. Duplicated points are removed. Duplicated points are not generated in a grid design, but the way parameter dependencies are handled make this possible.

Note that if you have trafos attached to your params, the complete creation of the design (except for the detection of invalid parameters w.r.t to their requires setting) takes place on the UNTRANSFORMED scale. So this function creates a regular grid over the param space on the UNTRANSFORMED scale, but not necessarily the transformed scale.

generateDesign will NOT work if there are dependencies over multiple levels of parameters and the dependency is only given with respect to the “previous” parameter. A current workaround is to state all dependencies on all parameters involved. (We are working on it.)

Usage

generateGridDesign(par.set, resolution, trafo = FALSE)

Arguments

Value

data.frame. Columns are named by the ids of the parameters. If the par.set argument contains a vector parameter, its corresponding column names in the design are the parameter id concatenated with 1 to dimension of the vector. The result will have an logical(1) attribute “trafo”, which is set to the value of argument trafo.

Examples

ps = makeParamSet(
  makeNumericParam("x1", lower = -2, upper = 1),
  makeNumericParam("x2", lower = -2, upper = 2, trafo = function(x) x^2)
)
generateGridDesign(ps, resolution = c(x1 = 4, x2 = 5), trafo = TRUE)

Description

The following types of columns are created:

If you want to convert these, look at BBmisc::convertDataFrameCols(). For discrete vectors the levels and their order will be preserved, even if not all levels are present.

The algorithm simply calls sampleValues() and arranges the result in a data.frame.

Parameters are trafoed (potentially, depending on the setting of argument trafo); dependent parameters whose constraints are unsatisfied are set to NA entries.

generateRandomDesign will NOT work if there are dependencies over multiple levels of parameters and the dependency is only given with respect to the “previous” parameter. A current workaround is to state all dependencies on all parameters involved. (We are working on it.)

Note that if you have trafos attached to your params, the complete creation of the design (except for the detection of invalid parameters w.r.t to their requires setting) takes place on the UNTRANSFORMED scale. So this function samples from a uniform density over the param space on the UNTRANSFORMED scale, but not necessarily the transformed scale.

Usage

generateRandomDesign(n = 10L, par.set, trafo = FALSE)

Arguments

Value

data.frame. Columns are named by the ids of the parameters. If the par.set argument contains a vector parameter, its corresponding column names in the design are the parameter id concatenated with 1 to dimension of the vector. The result will have an logical(1) attribute “trafo”, which is set to the value of argument trafo.

Description

Return defaults of single parameters or parameters in a parameter set or a list of parameters.

Usage

getDefaults(obj, include.null = FALSE, dict = NULL)

Arguments

Value

named list. Named (and in case of a ParamSet(), in the same order). Parameters without defaults are not present in the list.

Examples

ps1 = makeParamSet(
  makeDiscreteParam("x", values = c("a", "b"), default = "a"),
  makeNumericVectorParam("y", len = 2),
  makeIntegerParam("z", default = 99)
)
getDefaults(ps1, include.null = TRUE)

ps2 = makeParamSet(
  makeNumericVectorParam("a", len = expression(k), default = expression(p)),
  makeIntegerParam("b", default = 99),
  makeLogicalParam("c")
)
getDefaults(ps2, dict = list(k = 3, p = 5.4))

Description

getLower and getUpper return a numerical vector of lower and upper bounds, getValues returns a list of possible value sets for discrete parameters.

Parameters for which such bound make no sense - due to their type - are not present in the result.

Usage

getLower(obj, with.nr = FALSE, dict = NULL)

getUpper(obj, with.nr = FALSE, dict = NULL)

getValues(obj, dict = NULL)

Arguments

Value

vector | list. Named by parameter ids.

Examples

ps = makeParamSet(
  makeNumericParam("u"),
  makeDiscreteParam("v", values = c("a", "b")),
  makeIntegerParam("w", lower = expression(ceiling(p / 3)), upper = 2),
  makeDiscreteParam("x", values = 1:2),
  makeNumericVectorParam("y", len = 2, lower = c(0, 10), upper = c(1, 11)),
  keys = "p"
)
getLower(ps, dict = list(p = 7))
getUpper(ps)

ps = makeParamSet(
  makeNumericParam("u"),
  makeDiscreteParam("w", values = list(a = list(), b = NULL))
)
getValues(ps)

par.vals = list(
  u = makeNumericParam("u"),
  v = makeIntegerParam("v", lower = 1, upper = 2),
  w = makeDiscreteParam("w", values = 1:2),
  x = makeNumericVectorParam("x", len = 2, lower = c(3, 1), upper = expression(n))
)
getLower(par.vals)
getUpper(par.vals, dict = list(n = 12))

Description

Get index of the best element from optimization path.

Usage

getOptPathBestIndex(
  op,
  y.name = op$y.names[1],
  dob = op$env$dob,
  eol = op$env$eol,
  ties = "last"
)

Arguments

Value

integer Index or indices into path. See ties.

See Also

Other optpath: OptPath, addOptPathEl(), getOptPathCols(), getOptPathCol(), getOptPathDOB(), getOptPathEOL(), getOptPathEl(), getOptPathErrorMessages(), getOptPathExecTimes(), getOptPathLength(), getOptPathParetoFront(), getOptPathX(), getOptPathY(), setOptPathElDOB(), setOptPathElEOL()

Examples

ps = makeParamSet(makeNumericParam("x"))
op = makeOptPathDF(par.set = ps, y.names = "y", minimize = TRUE)
addOptPathEl(op, x = list(x = 1), y = 5)
addOptPathEl(op, x = list(x = 2), y = 3)
addOptPathEl(op, x = list(x = 3), y = 9)
addOptPathEl(op, x = list(x = 4), y = 3)
as.data.frame(op)
getOptPathBestIndex(op)
getOptPathBestIndex(op, ties = "first")

Description

Get column from the optimization path.

Usage

getOptPathCol(op, name, dob, eol)

Arguments

Value

Single column as a vector.

See Also

Other optpath: OptPath, addOptPathEl(), getOptPathBestIndex(), getOptPathCols(), getOptPathDOB(), getOptPathEOL(), getOptPathEl(), getOptPathErrorMessages(), getOptPathExecTimes(), getOptPathLength(), getOptPathParetoFront(), getOptPathX(), getOptPathY(), setOptPathElDOB(), setOptPathElEOL()

Description

Get columns from the optimization path.

Usage

getOptPathCols(op, names, dob, eol, row.names = NULL)

Arguments

Value

data.frame.

See Also

Other optpath: OptPath, addOptPathEl(), getOptPathBestIndex(), getOptPathCol(), getOptPathDOB(), getOptPathEOL(), getOptPathEl(), getOptPathErrorMessages(), getOptPathExecTimes(), getOptPathLength(), getOptPathParetoFront(), getOptPathX(), getOptPathY(), setOptPathElDOB(), setOptPathElEOL()

Description

Get date-of-birth vector from the optimization path.

Usage

getOptPathDOB(op, dob, eol)

Arguments

Value

integer.

See Also

Other optpath: OptPath, addOptPathEl(), getOptPathBestIndex(), getOptPathCols(), getOptPathCol(), getOptPathEOL(), getOptPathEl(), getOptPathErrorMessages(), getOptPathExecTimes(), getOptPathLength(), getOptPathParetoFront(), getOptPathX(), getOptPathY(), setOptPathElDOB(), setOptPathElEOL()

Description

Dependent parameters whose requirements are not satisfied are represented by a scalar NA in the elements of x of the return value.

Usage

getOptPathEl(op, index)

Arguments

Value

List with elements x (named list), y (named numeric), dob integer(1), eol integer(1). The elements error.message (character(1)), exec.time (numeric(1)) and extra (named list) are there if the respective options in OptPath() are enabled.

See Also

Other optpath: OptPath, addOptPathEl(), getOptPathBestIndex(), getOptPathCols(), getOptPathCol(), getOptPathDOB(), getOptPathEOL(), getOptPathErrorMessages(), getOptPathExecTimes(), getOptPathLength(), getOptPathParetoFront(), getOptPathX(), getOptPathY(), setOptPathElDOB(), setOptPathElEOL()

Description

Get end-of-life vector from the optimization path.

Usage

getOptPathEOL(op, dob, eol)

Arguments

Value

integer.

See Also

Other optpath: OptPath, addOptPathEl(), getOptPathBestIndex(), getOptPathCols(), getOptPathCol(), getOptPathDOB(), getOptPathEl(), getOptPathErrorMessages(), getOptPathExecTimes(), getOptPathLength(), getOptPathParetoFront(), getOptPathX(), getOptPathY(), setOptPathElDOB(), setOptPathElEOL()

Description

Get error-message vector from the optimization path.

Usage

getOptPathErrorMessages(op, dob, eol)

Arguments

Value

character.

See Also

Other optpath: OptPath, addOptPathEl(), getOptPathBestIndex(), getOptPathCols(), getOptPathCol(), getOptPathDOB(), getOptPathEOL(), getOptPathEl(), getOptPathExecTimes(), getOptPathLength(), getOptPathParetoFront(), getOptPathX(), getOptPathY(), setOptPathElDOB(), setOptPathElEOL()

Description

Get exec-time vector from the optimization path.

Usage

getOptPathExecTimes(op, dob, eol)

Arguments

Value

numeric.

See Also

Other optpath: OptPath, addOptPathEl(), getOptPathBestIndex(), getOptPathCols(), getOptPathCol(), getOptPathDOB(), getOptPathEOL(), getOptPathEl(), getOptPathErrorMessages(), getOptPathLength(), getOptPathParetoFront(), getOptPathX(), getOptPathY(), setOptPathElDOB(), setOptPathElEOL()

Description

Dependent parameters whose requirements are not satisfied are represented by a scalar NA in the output.

Usage

getOptPathLength(op)

Arguments

Value

integer(1)

See Also

Other optpath: OptPath, addOptPathEl(), getOptPathBestIndex(), getOptPathCols(), getOptPathCol(), getOptPathDOB(), getOptPathEOL(), getOptPathEl(), getOptPathErrorMessages(), getOptPathExecTimes(), getOptPathParetoFront(), getOptPathX(), getOptPathY(), setOptPathElDOB(), setOptPathElEOL()

Description

Get indices of pareto front of optimization path.

Usage

getOptPathParetoFront(
  op,
  y.names = op$y.names,
  dob = op$env$dob,
  eol = op$env$eol,
  index = FALSE
)

Arguments

Value

matrix | integer. Either matrix (with named columns) of points of front in objective space or indices into path for front.

See Also

Other optpath: OptPath, addOptPathEl(), getOptPathBestIndex(), getOptPathCols(), getOptPathCol(), getOptPathDOB(), getOptPathEOL(), getOptPathEl(), getOptPathErrorMessages(), getOptPathExecTimes(), getOptPathLength(), getOptPathX(), getOptPathY(), setOptPathElDOB(), setOptPathElEOL()

Examples

ps = makeParamSet(makeNumericParam("x"))
op = makeOptPathDF(par.set = ps, y.names = c("y1", "y2"), minimize = c(TRUE, TRUE))
addOptPathEl(op, x = list(x = 1), y = c(5, 3))
addOptPathEl(op, x = list(x = 2), y = c(2, 4))
addOptPathEl(op, x = list(x = 3), y = c(9, 4))
addOptPathEl(op, x = list(x = 4), y = c(4, 9))
as.data.frame(op)
getOptPathParetoFront(op)
getOptPathParetoFront(op, index = TRUE)

Description

Get data.frame of input points (X-space) referring to the param set from the optimization path.

Usage

getOptPathX(op, dob, eol)

Arguments

Value

data.frame.

See Also

Other optpath: OptPath, addOptPathEl(), getOptPathBestIndex(), getOptPathCols(), getOptPathCol(), getOptPathDOB(), getOptPathEOL(), getOptPathEl(), getOptPathErrorMessages(), getOptPathExecTimes(), getOptPathLength(), getOptPathParetoFront(), getOptPathY(), setOptPathElDOB(), setOptPathElEOL()

Description

Get y-vector or y-matrix from the optimization path.

Usage

getOptPathY(op, names, dob, eol, drop = TRUE)

Arguments

Value

(numeric | matrix). The columns of the matrix are always named.

See Also

Other optpath: OptPath, addOptPathEl(), getOptPathBestIndex(), getOptPathCols(), getOptPathCol(), getOptPathDOB(), getOptPathEOL(), getOptPathEl(), getOptPathErrorMessages(), getOptPathExecTimes(), getOptPathLength(), getOptPathParetoFront(), getOptPathX(), setOptPathElDOB(), setOptPathElEOL()

Description

Useful if vectors are included.

Usage

getParamIds(par, repeated = FALSE, with.nr = FALSE)

Arguments

Value

character.

Examples

ps = makeParamSet(
  makeNumericParam("u"),
  makeIntegerVectorParam("v", len = 2)
)
getParamIds(ps)
getParamIds(ps, repeated = TRUE)
getParamIds(ps, repeated = TRUE, with.nr = TRUE)

Description

Useful for vector parameters.

Usage

getParamLengths(par, dict = NULL)

Arguments

Value

(integer). Named and in the same order as the input for ParamSet() input.

Examples

ps = makeParamSet(
  makeNumericParam("u"),
  makeIntegerParam("v", lower = 1, upper = 2),
  makeDiscreteParam("w", values = 1:2),
  makeDiscreteVectorParam("x", len = 2, values = c("a", "b"))
)
getParamLengths(ps)
# the length of the vector x is 2, for all other single value parameters the length is 1.

par = makeNumericVectorParam("x", len = expression(k), lower = 0)
getParamLengths(par, dict = list(k = 4))

Description

Either number of parameters or sum over parameter lengths.

Usage

getParamNr(par.set, devectorize = FALSE)

Arguments

Value

integer.

Examples

ps = makeParamSet(
  makeNumericParam("u"),
  makeDiscreteVectorParam("x", len = 2, values = c("a", "b"))
)
getParamNr(ps)
getParamNr(ps, devectorize = TRUE)

Description

getParamSet is a generic and can be called to extract the ParamSet from different objects.

Usage

getParamSet(x)

Arguments

Value

ParamHelpers::ParamSet()

Description

Returns information on the number of parameters of a each type.

Usage

getParamTypeCounts(par.set)

Arguments

Value

list Named list which contains for each supported parameter type the number of parameters of this type in the given ParamSet.

Description

Returns type information for a parameter set.

Usage

getParamTypes(
  par.set,
  df.cols = FALSE,
  df.discretes.as.factor = TRUE,
  use.names = FALSE,
  with.nr = TRUE
)

Arguments

Value

character.

Description

Returns all requires-objects of a param set as a list.

Usage

getRequirements(par.set, remove.null = TRUE)

Arguments

Value

xnamed list. Named list of require-call-objects, lengths corresponds to number of params (potentially only the subset with requires-field), named with with param ids.

Description

Returns type strings used in param$type for certain groups of parameters.

Usage

getTypeStringsAll()

getTypeStringsNumeric(include.int = TRUE)

getTypeStringsNumericStrict()

getTypeStringsInteger()

getTypeStringsCharacter()

getTypeStringsDiscrete(include.logical = TRUE)

getTypeStringsLogical()

Arguments

Value

character.

Description

Checks if a parameter, parameter set or list of parameters contain expressions.

Usage

hasExpression(obj)

Arguments

Value

logical(1).

Examples

ps1 = makeParamSet(
  makeNumericParam("x", lower = 1, upper = 2),
  makeNumericParam("y", lower = 1, upper = 10)
)

ps2 = makeParamSet(
  makeNumericLearnerParam("x", lower = 1, upper = 2),
  makeNumericLearnerParam("y", lower = 1, upper = expression(p))
)

hasExpression(ps1)
hasExpression(ps2)

Description

Checks if a parameter or each parameter of a parameter set has ONLY finite lower and upper bounds.

Usage

hasFiniteBoxConstraints(par, dict = NULL)

Arguments

Value

logical(1)

Description

Check parameter set for forbidden region.

Usage

hasForbidden(par.set)

Arguments

Value

logical(1).

Description

TRUE iff the parameter has any requirements or any parameter in the set has requirements.

Usage

hasRequires(par)

Arguments

Value

logical(1).

Description

TRUE iff the parameter has any trafos or any parameter in the set has trafos.

Usage

hasTrafo(par)

Arguments

Value

logical(1).

Description

TRUE if the parameter set contains at least one parameter of the mentioned type x. Type x always subsumes x and x-vector.

Usage

hasDiscrete(par.set, include.logical = TRUE)

hasInteger(par.set)

hasLogical(par.set)

hasCharacter(par.set)

hasNumeric(par.set, include.int = TRUE)

Arguments

Value

logical(1)

Description

Check whether parameter set is empty.

Usage

isEmpty(par.set)

Arguments

Value

logical(1).

Description

Check if a parameter value satisfies the constraints of the parameter description. This includes the requires expressions and the forbidden expression, if par is a ParamSet(). If requires is not satisfied, the parameter value must be set to scalar NA to be still feasible, a single scalar even in a case of a vector parameter. If the result is FALSE the attribute "warning" is attached which gives the reason for the negative result.

If the parameter has cnames, these are also checked.

Usage

isFeasible(par, x, use.defaults = FALSE, filter = FALSE)

Arguments

Value

logical(1).

Examples

p = makeNumericParam("x", lower = -1, upper = 1)
isFeasible(p, 0) # True
isFeasible(p, 2) # False, out of bounds
isFeasible(p, "a") # False, wrong type
# now for parameter sets
ps = makeParamSet(
  makeNumericParam("x", lower = -1, upper = 1),
  makeDiscreteParam("y", values = c("a", "b"))
)
isFeasible(ps, list(0, "a")) # True
isFeasible(ps, list("a", 0)) # False, wrong order

Description

Parameter sets without a forbidden region always return FALSE.

Usage

isForbidden(par.set, x)

Arguments

Value

logical(1).

Description

Check if a parameter value satisfies the requirements of the parameter description. This only checks the requires expressions.

Usage

isRequiresOk(par.set, par.vals, ids = names(par.vals), use.defaults = TRUE)

Arguments

Value

logical(1)

Description

See title.

Usage

isSpecialValue(par, x)

Arguments

Value

logical(1).

Description

An empty param set is considered to be of all types.

Usage

isNumeric(par, include.int = TRUE)

isDiscrete(par, include.logical = TRUE)

isInteger(par)

isLogical(par)

isCharacter(par)

Arguments

Value

(logical(1))

Description

TRUE iff the type string is a certain type, e.g. isIntegerTypeString checks if we have “integer” or “integervector”, and isVectorTypeString check if we have “*vector”.

Usage

isNumericTypeString(type, include.int = TRUE)

isIntegerTypeString(type)

isCharacterTypeString(type)

isDiscreteTypeString(type, include.logical = TRUE)

isLogicalTypeString(type)

isVectorTypeString(type)

Arguments

Value

(logical(1))

Description

TRUE if the parameter is a vector parameter or all parameters in the set are vector parameters.

Usage

isVector(par)

Arguments

Value

logical(1).

Description

This specializes Param() by adding a few more attributes, like a default value, whether it refers to a training or a predict function, etc. Note that you can set length to NA

The S3 class is a Param() which additionally stores these elements:

when character(1)

See argument of same name.

See the note in Param() about being able to pass expressions to certain arguments.

Usage

makeNumericLearnerParam(
  id,
  lower = -Inf,
  upper = Inf,
  allow.inf = FALSE,
  default,
  when = "train",
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeNumericVectorLearnerParam(
  id,
  len = as.integer(NA),
  lower = -Inf,
  upper = Inf,
  allow.inf = FALSE,
  default,
  when = "train",
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeIntegerLearnerParam(
  id,
  lower = -Inf,
  upper = Inf,
  default,
  when = "train",
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeIntegerVectorLearnerParam(
  id,
  len = as.integer(NA),
  lower = -Inf,
  upper = Inf,
  default,
  when = "train",
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeDiscreteLearnerParam(
  id,
  values,
  default,
  when = "train",
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeDiscreteVectorLearnerParam(
  id,
  len = as.integer(NA),
  values,
  default,
  when = "train",
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeLogicalLearnerParam(
  id,
  default,
  when = "train",
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeLogicalVectorLearnerParam(
  id,
  len = as.integer(NA),
  default,
  when = "train",
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeUntypedLearnerParam(
  id,
  default,
  when = "train",
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeFunctionLearnerParam(
  id,
  default,
  when = "train",
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

Arguments

Value

LearnerParam().

Description

Convert a list of vectors or scalars to a data.frame with only one row. Names of the columns correspond to the names of elements in the list. If a vector is one list element it is spread over multiple columns and named sequentially, e.g. a = c(5,7) becomes data.frame(a1 = 5, a2 = 7).

Usage

listToDfOneRow(l)

Arguments

Value

(data.frame) with only one row, containing the list elements.

Description

makeParamSet: Construct from a bunch of parameters.

Multiple sets can be concatenated with c.

The constructed S3 class is simply a list that contains the element pars. pars is a list of the passed parameters, named by their ids.

If keys are provided it will automatically be checked whether all expressions within the provided parameters only contain arguments that are a subset of keys.

Usage

makeParamSet(..., params = NULL, forbidden = NULL, keys = NULL)

makeNumericParamSet(id = "x", len, lower = -Inf, upper = Inf, vector = TRUE)

Arguments

Value

ParamSet() | LearnerParamSet. If all parameters of the ParamSet are learner parameters, the output will inherit the class LearnerParamSet.

Examples

makeParamSet(
  makeNumericParam("u", lower = 1),
  makeIntegerParam("v", lower = 1, upper = 2),
  makeDiscreteParam("w", values = 1:2),
  makeLogicalParam("x"),
  makeDiscreteVectorParam("y", len = 2, values = c("a", "b"))
)
makeParamSet(
  makeNumericParam("u", lower = expression(ceiling(n))),
  makeIntegerParam("v", lower = expression(floor(n)), upper = 2),
  keys = c("p", "n")
)
makeParamSet(
  makeNumericParam("min", lower = 0, upper = 0.8),
  makeNumericParam("max", lower = 0.2, upper = 1),
  forbidden = expression(min > max)
)

Description

Optimizers can iteratively log their evaluated points into this object. Can be converted into a data.frame with as.data.frame(x, discretes.as.factor = TRUE / FALSE).

A optimization path has a number of path elements, where each element consists of: the value of the decision variables at this point, the values of the performance measures at this point, the date-of-birth (dob) of this point, the end-of-life (eol) of this point and possibly an error message. See also addOptPathEl().

For discrete parameters always the name of the value is stored as a character. When you retrieve an element with getOptPathEl(), this name is converted to the actual discrete value.

If parameters have associated transformation you are free to decide whether you want to add x values before or after transformation, see argument add.transformed.x and trafoOptPath().

The S3 class is a list which stores at least these elements:

par.set ParamSet()

See argument of same name.

y.names character

See argument of same name.

minimize logical

See argument of same name.

add.transformed.x logical(1)

See argument of same name.

env environment

Environment which stores the optimization path. Contents depend on implementation.

Usage

makeOptPathDF(
  par.set,
  y.names,
  minimize,
  add.transformed.x = FALSE,
  include.error.message = FALSE,
  include.exec.time = FALSE,
  include.extra = FALSE
)

Arguments

See Also

Other optpath: addOptPathEl(), getOptPathBestIndex(), getOptPathCols(), getOptPathCol(), getOptPathDOB(), getOptPathEOL(), getOptPathEl(), getOptPathErrorMessages(), getOptPathExecTimes(), getOptPathLength(), getOptPathParetoFront(), getOptPathX(), getOptPathY(), setOptPathElDOB(), setOptPathElEOL()

Description

For each parameter type a special constructor function is available, see below.

For the following arguments you can also pass an expression instead of a concrete value: default, len, lower, upper, values. These expressions can depend on arbitrary symbols, which are later filled in / substituted from a dictionary, in order to produce a concrete valu, see evaluateParamExpressions(). So this enables data / context dependent settings, which is sometimes useful.

The S3 class is a list which stores these elements:

id (character(1))

See argument of same name.

type (character(1))

Data type of parameter. For all type string see (getTypeStringsAll())

len (integer(1) | expression)

See argument of same name.

lower (numeric | expression)

See argument of same name. Length of this vector is len.

upper (numeric | expression)

See argument of same name. Length of this vector is len.

values (list | expression)

Discrete values, always stored as a named list.

cnames (character

See argument of same name.

allow.inf (logical(1))

See argument of same name.

trafo (NULL | ⁠function(x)⁠)

See argument of same name.

requires (NULL | expression)

See argument of same name.

default (any concrete value | expression)

See argument of same name.

has.default (logical(1))

Extra flag to really be able to check whether the user passed a default, to avoid troubles with NULL and NA.

tunable (logical(1))

See argument of same name.

special.vals (list)

See argument of same name.

Usage

makeNumericParam(
  id,
  lower = -Inf,
  upper = Inf,
  allow.inf = FALSE,
  default,
  trafo = NULL,
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeNumericVectorParam(
  id,
  len,
  lower = -Inf,
  upper = Inf,
  cnames = NULL,
  allow.inf = FALSE,
  default,
  trafo = NULL,
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeIntegerParam(
  id,
  lower = -Inf,
  upper = Inf,
  default,
  trafo = NULL,
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeIntegerVectorParam(
  id,
  len,
  lower = -Inf,
  upper = Inf,
  cnames = NULL,
  default,
  trafo = NULL,
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeLogicalParam(
  id,
  default,
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeLogicalVectorParam(
  id,
  len,
  cnames = NULL,
  default,
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeDiscreteParam(
  id,
  values,
  trafo = NULL,
  default,
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeDiscreteVectorParam(
  id,
  len,
  values,
  trafo = NULL,
  default,
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeFunctionParam(
  id,
  default = default,
  requires = NULL,
  special.vals = list()
)

makeUntypedParam(
  id,
  default,
  requires = NULL,
  tunable = TRUE,
  special.vals = list()
)

makeCharacterParam(id, default, requires = NULL, special.vals = list())

makeCharacterVectorParam(
  id,
  len,
  cnames = NULL,
  default,
  requires = NULL,
  special.vals = list()
)

Arguments

Value

[Param()].

Examples

makeNumericParam("x", lower = -1, upper = 1)
makeNumericVectorParam("x", len = 2)
makeDiscreteParam("y", values = c("a", "b"))
makeCharacterParam("z")

Description

Useful helper for logging. For discrete parameter values always the name of the discrete value is used.

Usage

paramValueToString(par, x, show.missing.values = FALSE, num.format = "%.3g")

Arguments

Value

character(1).

Examples

p = makeNumericParam("x")
paramValueToString(p, 1)
paramValueToString(p, 1.2345)
paramValueToString(p, 0.000039)
paramValueToString(p, 8.13402, num.format = "%.2f")

p = makeIntegerVectorParam("x", len = 2)
paramValueToString(p, c(1L, 2L))

p = makeLogicalParam("x")
paramValueToString(p, TRUE)

p = makeDiscreteParam("x", values = list(a = NULL, b = 2))
paramValueToString(p, NULL)

ps = makeParamSet(
  makeNumericVectorParam("x", len = 2L),
  makeDiscreteParam("y", values = list(a = NULL, b = 2))
)
paramValueToString(ps, list(x = c(1, 2), y = NULL))

Description

Can be used to plot OptPaths where information for bi-objective evaluation was logged for repeated runs of different algorithmic runs. Pretty directly calls eaf::eafplot().

Usage

plotEAF(opt.paths, xlim = NULL, ylim = NULL, ...)

Arguments

Value

data.frame Invisibly returns the data passed to eaf::eafplot().

Note

We changed the defaults of eaf::eafplot() in the following way: The axis are labeled by y.names, colors are set to our favorite grey values and linetypes changed, too. With our colors / linetypes default it is possible to distinguish 6 different algorithms. But this can again be overwritten by the user.

Description

Plot method for every type of optimization path, containing any numbers and types of variables. For every iteration up to 4 types of plots can be generated: One plot for the distribution of points in X and Y space respectively and plots for the trend of specified X variables, Y variables and extra measures over the time.

Usage

plotOptPath(
  op,
  iters,
  pause = TRUE,
  xlim = list(),
  ylim = list(),
  title = "Optimization Path Plots",
  ...
)

Arguments

Description

Plot function for renderYTraces()

Usage

plotYTraces(opt.paths, over.time = "dob")

Arguments

Value

NULL

Description

Removes all scalar NAs from a parameter setting list.

Usage

removeMissingValues(x)

Arguments

Value

list.

Description

Same as plotOptPath(), but renders the plots for just 1 iteration and returns a list of plots instead of printing the plot. Useful, if you want to extract single plots or to edit the ggplots by yourself.

Usage

renderOptPathPlot(
  op,
  iter,
  x.over.time,
  y.over.time,
  contour.name = NULL,
  xlim = list(),
  ylim = list(),
  alpha = TRUE,
  log = NULL,
  colours = c("red", "blue", "green", "orange"),
  size.points = 3,
  size.lines = 1.5,
  impute.scale = 1,
  impute.value = "missing",
  scale = "std",
  ggplot.theme = ggplot2::theme(legend.position = "top"),
  marked = NULL,
  subset.obs,
  subset.vars,
  subset.targets,
  short.x.names,
  short.y.names,
  short.rest.names
)

Arguments

Value

List of plots. List has up to elements: plot.x: Plot for XSpace. If both X and Y are 1D, Plot for both plot.y: Plot for YSpace. If both X and Y are 1D, NULL. plot.x.over.time: List of plots for x over time. Can also be NULL. plot.y.over.time: List of plots for y over time. Can also be NULL.

Description

Can be used for only single-objective optimization paths. Useful to compare runs of different algorithms on the same optimization problem. You can add your own ggplot layers to the resulting plot object.

Usage

renderYTraces(opt.paths, over.time = "dob")

Arguments

Value

ggplot2 plot object

Description

Clips values outside of box constraints to bounds.

Usage

repairPoint(par.set, x, warn = FALSE)

Arguments

Value

list: List of repaired points.

Description

Sample a random value from a parameter or a parameter set uniformly.

Dependent parameters whose requirements are not satisfied are represented by a scalar NA in the output.

Usage

sampleValue(par, discrete.names = FALSE, trafo = FALSE)

Arguments

Value

The return type is determined by the type of the parameter. For a set a named list of such values in the correct order is returned.

Examples

# bounds are necessary here, can't sample with Inf bounds:
u = makeNumericParam("x", lower = 0, upper = 1)
# returns a random number between 0 and 1:
sampleValue(u)

p = makeDiscreteParam("x", values = c("a", "b", "c"))
# can be either "a", "b" or "c"
sampleValue(p)

p = makeIntegerVectorParam("x", len = 2, lower = 1, upper = 5)
# vector of two random integers between 1 and 5:
sampleValue(p)

ps = makeParamSet(
  makeNumericParam("x", lower = 1, upper = 10),
  makeIntegerParam("y", lower = 1, upper = 10),
  makeDiscreteParam("z", values = 1:2)
)
sampleValue(ps)

Description

Sample n random values from a parameter or a parameter set uniformly.

Dependent parameters whose requirements are not satisfied are represented by a scalar NA in the output.

Usage

sampleValues(par, n, discrete.names = FALSE, trafo = FALSE)

Arguments

Value

list. For consistency always a list is returned.

Examples

p = makeIntegerParam("x", lower = -10, upper = 10)
sampleValues(p, 4)

p = makeNumericParam("x", lower = -10, upper = 10)
sampleValues(p, 4)

p = makeLogicalParam("x")
sampleValues(p, 4)

ps = makeParamSet(
  makeNumericParam("u", lower = 1, upper = 10),
  makeIntegerParam("v", lower = 1, upper = 10),
  makeDiscreteParam("w", values = 1:2)
)
sampleValues(ps, 2)

Description

Set the dates of birth of parameter values, in-place.

Usage

setOptPathElDOB(op, index, dob)

Arguments

Value

Nothing.

See Also

Other optpath: OptPath, addOptPathEl(), getOptPathBestIndex(), getOptPathCols(), getOptPathCol(), getOptPathDOB(), getOptPathEOL(), getOptPathEl(), getOptPathErrorMessages(), getOptPathExecTimes(), getOptPathLength(), getOptPathParetoFront(), getOptPathX(), getOptPathY(), setOptPathElEOL()

Description

Set the end of life dates of parameter values, in-place.

Usage

setOptPathElEOL(op, index, eol)

Arguments

Value

Nothing.

See Also

Other optpath: OptPath, addOptPathEl(), getOptPathBestIndex(), getOptPathCols(), getOptPathCol(), getOptPathDOB(), getOptPathEOL(), getOptPathEl(), getOptPathErrorMessages(), getOptPathExecTimes(), getOptPathLength(), getOptPathParetoFront(), getOptPathX(), getOptPathY(), setOptPathElDOB()

Description

If param has cnames set component names in a value. Otherwise x is left unchanged.

Usage

setValueCNames(par, x)

Arguments

Value

x with changed names.

Description

Transform optimization path with associated transformation functions of parameters. Can only be done when x values where added “untransformed”.

Usage

trafoOptPath(opt.path)

Arguments

Value

[OptPath()].

Examples

ps = makeParamSet(
  makeIntegerParam("u", trafo = function(x) 2 * x),
  makeNumericVectorParam("v", len = 2, trafo = function(x) x / sum(x)),
  makeDiscreteParam("w", values = c("a", "b"))
)
op = makeOptPathDF(ps, y.names = "y", minimize = TRUE)
addOptPathEl(op, x = list(3, c(2, 4), "a"), y = 0, dob = 1, eol = 1)
addOptPathEl(op, x = list(4, c(5, 3), "b"), y = 2, dob = 5, eol = 7)

as.data.frame(op)
op = trafoOptPath(op)
as.data.frame(op)

Description

Transform a value with associated transformation function(s).

Usage

trafoValue(par, x)

Arguments

Value

Transformed value.

Examples

# transform simple parameter:
p = makeNumericParam(id = "x", trafo = function(x) x^2)
trafoValue(p, 2)
# for a parameter set different transformation functions are possible:
ps = makeParamSet(
  makeIntegerParam("u", trafo = function(x) 2 * x),
  makeNumericVectorParam("v", len = 2, trafo = function(x) x / sum(x)),
  makeDiscreteParam("w", values = c("a", "b"))
)
# now the values of "u" and "v" are transformed:
trafoValue(ps, list(3, c(2, 4), "a"))

Description

Update the values of a given parameter setting with a new parameter setting. Settings that do not meet the requirements anymore will be deleted from the first given parameter setting. Default values of the Param Set are respected to check if the new param settings meet the requirements.

Usage

updateParVals(par.set, old.par.vals, new.par.vals, warn = FALSE)

Arguments

Value

list.