Package 'param6'

Description

By making use of 'set6', alongside the S3 and R6 paradigms, this package provides a fast and lightweight R6 interface for parameters and parameter sets.

Author(s)

Maintainer: Raphael Sonabend [email protected] (ORCID)

See Also

Useful links:

• https://xoopR.github.io/param6/

• https://github.com/xoopR/param6/

• Report bugs at https://github.com/xoopR/param6/issues

Description

Creates a new ParameterSet by extracting the given parameters. S3 method for the ⁠$extract⁠ public method.

Usage

## S3 method for class 'ParameterSet'
object[...]

Arguments

Description

Coercion from ParameterSet to data.table::data.table. Dependencies, transformations, and tag properties are all lost in coercion.

Usage

## S3 method for class 'ParameterSet'
as.data.table(x, sort = TRUE, ...)

Arguments

Description

Coercions to ParameterSet

Usage

as.ParameterSet(x, ...)

## S3 method for class 'data.table'
as.ParameterSet(x, ...)

## S3 method for class 'prm'
as.ParameterSet(x, ...)

## S3 method for class 'list'
as.ParameterSet(x, ...)

Arguments

Description

Methods for coercing various objects to a prm.

Usage

as.prm(x, ...)

## S3 method for class 'ParameterSet'
as.prm(x, ...)

## S3 method for class 'data.table'
as.prm(x, ...)

Arguments

Description

Concatenate multiple ParameterSet objects with unique ids and tags into a single ParameterSet.

Usage

## S3 method for class 'ParameterSet'
c(..., pss = list(...))

Arguments

Details

Concatenates ids, tags, tag properties and dependencies. Assumes ids and tags are unique; trafos are combined into a list.

Description

Function to create a condition for ParameterSet dependencies for use in the ⁠$deps⁠ public method.

Usage

cnd(type, value = NULL, id = NULL, error = NULL)

Arguments

Details

This function should never be used outside of creating a condition for a dependency in a ParameterSet. Currently the following conditions are supported based on the type argument, we refer to the parameter depended on as in the independent parameter, and the other as the dependent:

• "eq" - If value is not NULL then checks if the independent parameter equals value, otherwise checks if the independent and dependent parameter are equal.

• "neq" - If value is not NULL then checks if the independent parameter does not equal value, otherwise checks if the independent and dependent parameter are not equal.

• "gt"/"lt" - If value is not NULL then checks if the independent parameter is greater/less than value, otherwise checks if the independent parameter is greater/less than the dependent parameter.

• "geq"/"leq" - If value is not NULL then checks if the independent parameter is greater/less than or equal to value, otherwise checks if the independent parameter is greater/less than or equal to the dependent parameter.

• "any" - If value is not NULL then checks if the independent parameter equals any of value, otherwise checks if the independent parameter equals any of dependent parameter.

• "nany" - If value is not NULL then checks if the independent parameter does not equal any of value, otherwise checks if the independent parameter does not equal any of dependent parameter.

• "len" - If value is not NULL then checks if the length of the independent parameter equals value, otherwise checks if the independent and dependent parameter are the same length.

• "inc" - Checks if the parameter is increasing.

• "sinc" - Checks if the parameter is strictly increasing.

• "dec" - Checks if the parameter is decreasing.

• "sdec" - Checks if the parameter is strictly decreasing.

Description

Concatenate multiple ParameterSet objects into a single ParameterSet.

Usage

cpset(..., pss = list(...), clone = TRUE)

Arguments

Details

Concatenates ids, tags, tag properties and dependencies, but not transformations.

Description

Primarily for internal use

Usage

expect_equal_ps(obj, expected)

Arguments

Description

Gets the number of parameters in the ParameterSet.

Usage

## S3 method for class 'ParameterSet'
length(x)

Arguments

Description

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

Methods

Public methods

• ParameterSet$new()

• ParameterSet$print()

• ParameterSet$get_values()

• ParameterSet$add_dep()

• ParameterSet$rep()

• ParameterSet$extract()

• ParameterSet$remove()

• ParameterSet$getParameterValue()

• ParameterSet$setParameterValue()

• ParameterSet$set_values()

• ParameterSet$parameters()

• ParameterSet$transform()

• ParameterSet$clone()

Method new()

Constructs a ParameterSet object.

Usage

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

Arguments

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

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

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

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

Method extract()

Creates a new ParameterSet by extracting the given parameters.

Usage

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

Arguments

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

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

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

Method set_values()

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

Usage

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

Arguments

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

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

Returns

⁠named list(1)⁠

Method clone()

The objects of this class are cloneable with this method.

Usage

ParameterSet$clone(deep = FALSE)

Arguments

Examples

library(set6)

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

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

# simple transformation
p$get_values()
p$trafo <- function(x, self) {
 x$a <- exp(x$a)
 x
}
p$get_values()

# 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()


## ------------------------------------------------
## 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)

## ------------------------------------------------
## 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()
print(p)
p

## ------------------------------------------------
## 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()
p$get_values(inc_null = FALSE)
p$get_values(id = "a")
p$get_values(tags = "t1")

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

# not run as errors
## Not run: 
# 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)

## End(Not run)

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

# 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"]

Description

The prm class is required for ParameterSet objects, it allows specifying a parameter as a named set and optionally setting values and tags.

Usage

prm(id, support, value = NULL, tags = NULL, .check = TRUE)

Arguments

Examples

library(set6)

# Constructing a prm with a Set support
prm(
 id = "a",
 support = Reals$new(),
 value = 1
)

# Constructing a prm with a support already in the dictionary
prm(
 id = "a",
 support = "reals",
 value = 1
)

# Adding tags
prm(
 id = "a",
 support = "reals",
 value = 1,
 tags = c("tag1", "tag2")
)

Description

See ParameterSet for full details.

Usage

pset(..., prms = list(...), tag_properties = NULL, deps = NULL, trafo = NULL)

Arguments

Examples

library(set6)

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

# with properties, deps, trafo
p <- pset(
 prm("a", Set$new(1), 1, tags = "t1"),
 prm("b", "reals", 1.5, tags = "t1"),
 prm("d", "reals", 2, tags = "t2"),
 tag_properties = list(required = "t2"),
 deps = list(
   list(id = "a", on = "b", cond = cnd("eq", 1.5))
 ),
 trafo = function(x, self) return(x)
)

Description

In contrast to the ⁠$rep⁠ method in ParameterSet, this method deep clones the ParameterSet and returns a new object.

Usage

## S3 method for class 'ParameterSet'
rep(x, times, prefix, ...)

Arguments

Details

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.

Description

dictionar6::Dictionary for parameter supports

Details

See dictionar6::Dictionary for full details of how to add other set6::Set objects as supports to this dictionary.

Examples

support_dictionary$keys
support_dictionary$items