Parameter Set

Source: R/ParameterSet.R

ParameterSet objects store parameters (prm objects) and add internal validation checks and methods for:

  • Getting and setting parameter values

  • Transforming parameter values

  • Providing dependencies of parameters on each other

  • Tagging parameters, which may enable further properties

  • Storing subsets of parameters under prefixes

Active bindings

tags

None -> named_list()
Get tags from the parameter set.

ids

None -> character()
Get ids from the parameter set.

length

None -> integer(1)
Get the length of the parameter set as the number of parameters.

deps

None -> data.table::data.table Get parameter dependencies, NULL if none.

supports

None -> named_list()
Get supports from the parameter set.

tag_properties

list() -> self / None -> list()
If x is missing then returns tag properties if any.
If x is not missing then used to tag properties. Currently properties can either be:
i) 'required' - parameters with this tag must have set (non-NULL) values; if a parameter is both 'required' and 'linked' then exactly one parameter in the 'linked' tag must be tagged;
ii) 'linked' - parameters with 'linked' tags are dependent on one another and only one can be set (non-NULL at a time);
iii) 'unique' - parameters with this tag must have no duplicated elements, therefore this tag only makes sense for vector parameters;
iv) 'immutable' - parameters with this tag cannot be updated after construction.

values

list() -> self / None -> list()
If x is missing then returns the set (non-NULL) values without transformation or filtering; use $get_values for a more sophisticated getter of values.
If x is not missing then used to set values of parameters, which are first checked internally with the $check method before setting the new values.
See examples at end.

trafo

function()|list() -> self / None -> function()|list()
If x is missing then returns a transformation function if previously set, a list of transformation functions, otherwise NULL.
If x is not missing then it should either be:

  • a function with arguments x and self, which internally correspond to self being the ParameterSet the transformation is being added to, and x <- self$values.

  • a list of functions like above

The transformation function is automatically called after a call to self$get_values() and is used to transform set values, it should therefore result in a list. If using self$get_values() within the transformation function, make sure to set transform = FALSE to prevent infinite recursion, see examples at end.

It is generally safer to call the transformation with $transform(self$values) as this will first check to see if $trafo is a function or list. If the latter then each function in the list is applied, one after the other.

Methods

Public methods

Method new()

Constructs a ParameterSet object.

Usage

ParameterSet$new(prms = list(), tag_properties = NULL)

Arguments

prms

(list())
List of prm objects. Ids should be unique.

tag_properties

(list())
List of tag properties. Currently supported properties are: i) 'required' - parameters with this tag property must be non-NULL; ii) 'linked' - only one parameter in a linked tag group can be non-NULL and the others should be NULL, this only makes sense with an associated trafo; iii) 'unique' - parameters with this tag must have no duplicated elements, only makes sense for vector parameters; iv) 'immutable' - parameters with this tag cannot be updated after construction.

Examples

prms <- list(
 prm("a", Set$new(1), 1, tags = "t1"),
 prm("b", "reals", 1.5, tags = "t1"),
 prm("d", "reals", 2, tags = "t2")
)
ParameterSet$new(prms)

Method print()

Prints the ParameterSet after coercion with as.data.table.ParameterSet.

Usage

ParameterSet$print(sort = TRUE)

Arguments

sort

(logical(1))
If TRUE (default) sorts the ParameterSet alphabetically by id.

Examples

prms <- list(
 prm("a", Set$new(1), 1, tags = "t1"),
 prm("b", "reals", 1.5, tags = "t1"),
 prm("d", "reals", 2, tags = "t2")
)
p <- ParameterSet$new(prms)
p$print()
print(p)
p

Method get_values()

Gets values from the ParameterSet with options to filter by specific IDs and tags, and also to transform the values.

Usage

ParameterSet$get_values(
  id = NULL,
  tags = NULL,
  transform = TRUE,
  inc_null = TRUE,
  simplify = TRUE
)

Arguments

id

(character())
If not NULL then returns values for given ids.

tags

(character())
If not NULL then returns values for given tags.

transform

(logical(1))
If TRUE (default) and $trafo is not NULL then runs the set transformation function before returning the values.

inc_null

(logical(1))
If TRUE (default) then returns values for all ids even if NULL.

simplify

(logical(1))
If TRUE (default) then unlists scalar values, otherwise always returns a list.

Examples

prms <- list(
 prm("a", "reals", 1, tags = "t1"),
 prm("b", "reals", 1.5, tags = "t1"),
 prm("d", "reals", tags = "t2")
)
p <- ParameterSet$new(prms)
p$trafo <- function(x, self) {
 x$a <- exp(x$a)
 x
}
p$get_values()
p$get_values(inc_null = FALSE)
p$get_values(id = "a")
p$get_values(tags = "t1")

Method add_dep()

Gets values from the ParameterSet with options to filter by specific IDs and tags, and also to transform the values.

Usage

ParameterSet$add_dep(id, on, cnd)

Arguments

id

(character(1))
The dependent variable for the condition that depends on the given variable, on, being a particular value. Should be in self$ids.

on

(character(1))
The independent variable for the condition that is depended on by the given variable, id. Should be in self$ids.

cnd

(cnd(1))
The condition defined by cnd which determines how id depends on on.

Examples

# not run as errors
\dontrun{
# Dependency on specific value
prms <- list(
 prm("a", "reals", NULL),
 prm("b", "reals", 1)
)
p <- ParameterSet$new(prms)
p$add_dep("a", "b", cnd("eq", 2))
# 'a' can only be set if 'b' equals 2
p$values$a <- 1
p$values <- list(a = 1, b = 2)

# Dependency on variable value
prms <- list(
 prm("a", "reals", NULL),
 prm("b", "reals", 1)
)
p <- ParameterSet$new(prms)
p$add_dep("a", "b", cnd("eq", id = "b"))
# 'a' can only be set if it equals 'b'
p$values$a <- 2
p$values <- list(a = 2, b = 2)
}

Method rep()

Replicate the ParameterSet with identical parameters. In order to avoid duplicated parameter ids, every id in the ParameterSet is given a prefix in the format prefix__id. In addition, linked tags are also given the same prefix to prevent incorrectly linking parameters.

The primary use-case of this method is to treat the ParameterSet as a collection of identical ParameterSet objects.

Note that this mutates the ParameterSet, if you want to instead create a new object then use rep.ParameterSet instead (or copy and deep clone) first.

Usage

ParameterSet$rep(times, prefix)

Arguments

times

(integer(1))
Numer of times to replicate the ParameterSet.

prefix

(character(1)|character(length(times)))
The prefix to add to ids and linked tags. If length 1 then is internally coerced to paste0(prefix, seq(times)), otherwise the length should be equal to times.

Method extract()

Creates a new ParameterSet by extracting the given parameters.

Usage

ParameterSet$extract(id = NULL, tags = NULL, prefix = NULL)

Arguments

id

(character())
If not NULL then specifies the parameters by id to extract. Should be NULL if prefix is not NULL.

tags

(character())
If not NULL then specifies the parameters by tag to extract. Should be NULL if prefix is not NULL.

prefix

(character())
If not NULL then extracts parameters according to their prefix and additionally removes the prefix from the id. A prefix is determined as the string before "__" in an id.

Examples

# extract by id
prms <- list(
 prm("a", "reals", NULL),
 prm("b", "reals", 1)
)
p <- ParameterSet$new(prms)
p$extract("a")
# equivalently
p["a"]

# extract by prefix
prms <- list(
  prm("Pre1__par1", Set$new(1), 1, tags = "t1"),
  prm("Pre1__par2", "reals", 3, tags = "t2"),
  prm("Pre2__par1", Set$new(1), 1, tags = "t1"),
  prm("Pre2__par2", "reals", 3, tags = "t2")
)
p <- ParameterSet$new(prms)
p$extract(tags = "t1")
p$extract(prefix = "Pre1")
# equivalently
p[prefix = "Pre1"]

Method remove()

Removes the given parameters from the set.

Usage

ParameterSet$remove(id = NULL, prefix = NULL)

Arguments

id

(character())
If not NULL then specifies the parameters by id to extract. Should be NULL if prefix is not NULL.

prefix

(character())
If not NULL then extracts parameters according to their prefix and additionally removes the prefix from the id. A prefix is determined as the string before "__" in an id.

Method getParameterValue()

Deprecated method added for distr6 compatibility. Use $values/$get_values() in the future. Will be removed in 0.3.0.

Usage

ParameterSet$getParameterValue(id, ...)

Arguments

id

Parameter id

...

Unused

Method setParameterValue()

Deprecated method added for distr6 compatibility. Use $set_values in the future. Will be removed in 0.3.0.

Usage

ParameterSet$setParameterValue(..., lst = list(...))

Arguments

...

Parameter ids

lst

List of parameter ids

Method set_values()

Convenience function for setting multiple parameters without changing or accidentally removing others.

Usage

ParameterSet$set_values(..., lst = list(...))

Arguments

...

Parameter ids

lst

List of parameter ids

Method parameters()

Deprecated method added for distr6 compatibility. Use $print/as.data.table() in the future. Will be removed in 0.3.0.

Usage

ParameterSet$parameters(...)

Arguments

...

Unused

Method transform()

Applies the internal transformation function. If no function has been passed to $trafo then x is returned unchanged. If $trafo is a function then x is passed directly to this. If $trafo is a list then x is evaluated and passed down the list iteratively.

Usage

ParameterSet$transform(x = self$values)

Arguments

x

(named list(1))
List of values to transform.

Returns

named list(1)

Method clone()

The objects of this class are cloneable with this method.

Usage

ParameterSet$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

library(set6)

## $value examples
p <- ParameterSet$new(list(prm(id = "a", support = Reals$new())))
p$values$a <- 2
p$values
#> $a
#> [1] 2
#> 

## $trafo examples
p <- ParameterSet$new(list(prm(id = "a", 2, support = Reals$new())))
p$trafo
#> NULL

# simple transformation
p$get_values()
#> [1] 2
p$trafo <- function(x, self) {
 x$a <- exp(x$a)
 x
}
p$get_values()
#> [1] 7.389056

# more complex transformation on tags
p <- ParameterSet$new(
  list(prm(id = "a", 2, support = Reals$new(), tags = "t1"),
       prm(id = "b", 3, support = Reals$new(), tags = "t1"),
       prm(id = "d", 4, support = Reals$new()))
)
# make sure `transform = FALSE` to prevent infinite recursion
p$trafo <- function(x, self) {
 out <- lapply(self$get_values(tags = "t1", transform = FALSE),
               function(.x) 2^.x)
 out <- c(out, list(d = x$d))
 out
}
p$get_values()
#> $a
#> [1] 4
#> 
#> $b
#> [1] 8
#> 
#> $d
#> [1] 4
#> 


## ------------------------------------------------
## Method `ParameterSet$new`
## ------------------------------------------------

prms <- list(
 prm("a", Set$new(1), 1, tags = "t1"),
 prm("b", "reals", 1.5, tags = "t1"),
 prm("d", "reals", 2, tags = "t2")
)
ParameterSet$new(prms)
#>    Id Support Value Tags
#> 1:  a     {1}     1   t1
#> 2:  b       ℝ   1.5   t1
#> 3:  d       ℝ     2   t2

## ------------------------------------------------
## Method `ParameterSet$print`
## ------------------------------------------------

prms <- list(
 prm("a", Set$new(1), 1, tags = "t1"),
 prm("b", "reals", 1.5, tags = "t1"),
 prm("d", "reals", 2, tags = "t2")
)
p <- ParameterSet$new(prms)
p$print()
#>    Id Support Value Tags
#> 1:  a     {1}     1   t1
#> 2:  b       ℝ   1.5   t1
#> 3:  d       ℝ     2   t2
print(p)
#>    Id Support Value Tags
#> 1:  a     {1}     1   t1
#> 2:  b       ℝ   1.5   t1
#> 3:  d       ℝ     2   t2
p
#>    Id Support Value Tags
#> 1:  a     {1}     1   t1
#> 2:  b       ℝ   1.5   t1
#> 3:  d       ℝ     2   t2

## ------------------------------------------------
## Method `ParameterSet$get_values`
## ------------------------------------------------

prms <- list(
 prm("a", "reals", 1, tags = "t1"),
 prm("b", "reals", 1.5, tags = "t1"),
 prm("d", "reals", tags = "t2")
)
p <- ParameterSet$new(prms)
p$trafo <- function(x, self) {
 x$a <- exp(x$a)
 x
}
p$get_values()
#> $a
#> [1] 2.718282
#> 
#> $b
#> [1] 1.5
#> 
#> $d
#> NULL
#> 
p$get_values(inc_null = FALSE)
#> $a
#> [1] 2.718282
#> 
#> $b
#> [1] 1.5
#> 
p$get_values(id = "a")
#> [1] 2.718282
p$get_values(tags = "t1")
#> $a
#> [1] 2.718282
#> 
#> $b
#> [1] 1.5
#> 

## ------------------------------------------------
## Method `ParameterSet$add_dep`
## ------------------------------------------------

# not run as errors
if (FALSE) {
# Dependency on specific value
prms <- list(
 prm("a", "reals", NULL),
 prm("b", "reals", 1)
)
p <- ParameterSet$new(prms)
p$add_dep("a", "b", cnd("eq", 2))
# 'a' can only be set if 'b' equals 2
p$values$a <- 1
p$values <- list(a = 1, b = 2)

# Dependency on variable value
prms <- list(
 prm("a", "reals", NULL),
 prm("b", "reals", 1)
)
p <- ParameterSet$new(prms)
p$add_dep("a", "b", cnd("eq", id = "b"))
# 'a' can only be set if it equals 'b'
p$values$a <- 2
p$values <- list(a = 2, b = 2)
}

## ------------------------------------------------
## Method `ParameterSet$extract`
## ------------------------------------------------

# extract by id
prms <- list(
 prm("a", "reals", NULL),
 prm("b", "reals", 1)
)
p <- ParameterSet$new(prms)
p$extract("a")
#>    Id Support Value Tags
#> 1:  a       ℝ           
# equivalently
p["a"]
#>    Id Support Value Tags
#> 1:  a       ℝ           

# extract by prefix
prms <- list(
  prm("Pre1__par1", Set$new(1), 1, tags = "t1"),
  prm("Pre1__par2", "reals", 3, tags = "t2"),
  prm("Pre2__par1", Set$new(1), 1, tags = "t1"),
  prm("Pre2__par2", "reals", 3, tags = "t2")
)
p <- ParameterSet$new(prms)
p$extract(tags = "t1")
#>            Id Support Value Tags
#> 1: Pre1__par1     {1}     1   t1
#> 2: Pre2__par1     {1}     1   t1
p$extract(prefix = "Pre1")
#>      Id Support Value Tags
#> 1: par1     {1}     1   t1
#> 2: par2       ℝ     3   t2
# equivalently
p[prefix = "Pre1"]
#>      Id Support Value Tags
#> 1: par1     {1}     1   t1
#> 2: par2       ℝ     3   t2