distr6 (version 1.4.2)

ParameterSet: Parameter Sets for Distributions

Description

ParameterSets are passed to the Distribution constructor when creating a custom probability distribution that takes parameters.

Active bindings

deps

Returns ParameterSet dependencies table.

checks

Returns ParameterSet assertions table.

trafos

Returns ParameterSet transformations table.

length

Number of parameters in ParameterSet.

Methods

Public methods

• ParameterSet$new()

• ParameterSet$print()

• ParameterSet$parameters()

• ParameterSet$getParameterSupport()

• ParameterSet$getParameterValue()

• ParameterSet$setParameterValue()

• ParameterSet$merge()

• ParameterSet$addDeps()

• ParameterSet$addChecks()

• ParameterSet$addTrafos()

• ParameterSet$values()

• ParameterSet$clone()

Method new()

Creates a new instance of this R6 class.

Usage

ParameterSet$new(
  id,
  value,
  support,
  settable = TRUE,
  updateFunc = NULL,
  description = NULL
)

Arguments

id

(character(1)|list()) id of the parameter(s) to construct, should be unique.

value

(ANY|list()) Value of parameter(s) to set.

support

([set6::Set]|list()) Support of parameter(s) to set

settable

(character(1)|list()) Logical flag indicating if the parameter(s) can be updated after construction.

updateFunc

(list()) Deprecated, please use $addDeps instead.

description

(character(1)|list()) Optional description for the parameter(s).

Details

Every argument can either be given as the type listed or as a list of that type. If arguments are provided as a list, then each argument must be of the same length, with values as NULL where appropriate. See examples for more.

Examples

id <- list("prob", "size")
value <- list(0.2, 5)
support <- list(set6::Interval$new(0, 1), set6::PosNaturals$new())
description <- list("Probability of success", NULL)
ParameterSet$new(id = id,
                 value = value,
                 support = support,
                 description = description
 )

ParameterSet$new(id = "prob", value = 0.2, support = set6::Interval$new(0, 1), description = "Probability of success" )

Method print()

Prints the ParameterSet.

Usage

ParameterSet$print(hide_cols = c("settable"), ...)

Arguments

hide_cols

(character()) Names of columns in the ParameterSet to hide whilst printing.

...

ANY Additional arguments, currently unused.

Method parameters()

Returns the full parameter details for the supplied parameter, or returns self if id is NULL.

Usage

ParameterSet$parameters(id = NULL)

Arguments

id

character() id of parameter to return.

Method getParameterSupport()

Returns the support of the supplied parameter.

Usage

ParameterSet$getParameterSupport(id, error = "warn")

Arguments

id

character() id of parameter support to return.

error

(character(1)) If "warn" then returns a warning on error, otherwise breaks if "stop".

Returns

A set6::Set object.

Examples

ps <- ParameterSet$new(id = "prob",
                 value = 0.2,
                 support = set6::Interval$new(0, 1),
                 settable = TRUE,
                 description = "Probability of success"
 )
ps$getParameterSupport("prob")

Method getParameterValue()

Returns the value of the supplied parameter.

Usage

ParameterSet$getParameterValue(id, error = "warn")

Arguments

id

character() id of parameter value to return.

error

(character(1)) If "warn" then returns a warning on error, otherwise breaks if "stop".

Examples

ps <- ParameterSet$new(id = "prob",
                 value = 0.2,
                 support = set6::Interval$new(0, 1),
                 settable = TRUE,
                 description = "Probability of success"
 )
ps$getParameterValue("prob")

Method setParameterValue()

Sets the value(s) of the given parameter(s).

Usage

ParameterSet$setParameterValue(..., lst = NULL, error = "warn")

Arguments

...

ANY Named arguments of parameters to set values for. See examples.

lst

(list(1)) Alternative argument for passing parameters. List names should be parameter names and list values are the new values to set.

error

(character(1)) If "warn" then returns a warning on error, otherwise breaks if "stop".

Examples

id <- list("rate", "scale")
value <- list(1, 1)
support <- list(set6::PosReals$new(), set6::PosReals$new())
settable <- list(TRUE, FALSE)
ps <- ParameterSet$new(
  id, value, support, settable,
)
ps$addDeps("scale", "rate", function(self) 1 / self$getParameterValue("scale"))
ps$addDeps("rate", "scale", function(self) 1 / self$getParameterValue("rate"))
ps$getParameterValue(id = "rate")
ps$setParameterValue(rate = 2)
ps$getParameterValue("rate")
ps$getParameterValue("scale") # Auto-updated to 1/2

Method merge()

Merges multiple parameter sets.

Usage

ParameterSet$merge(y, ...)

Arguments

y

([ParameterSet])

...

([ParameterSet]s)

Examples

ps1 <- ParameterSet$new(id = c("prob", "qprob"),
                 value = c(0.2, 0.8),
                 support = list(set6::Interval$new(0, 1), set6::Interval$new(0, 1))
 )
 ps1$addChecks("prob", function(x, self) x > 0)
 ps1$addDeps("prob", "qprob", function(self) 1 - self$getParameterValue("prob"))
 ps2 <- ParameterSet$new(id = "size",
                 value = 10,
                 support = set6::Interval$new(0, 10, class = "integer"),
 )
 ps2$addTrafos("size", function(x, self) x + 1)
 ps1$merge(ps2)
 ps1$print()
 ps1$trafos
 ps1$checks
 ps1$deps

Method addDeps()

Add parameter dependencies for automatic updating.

Usage

ParameterSet$addDeps(x, y, fun, dt = NULL)

Arguments

x

(character(1)) id of parameter that updates y.

y

(character(1)) id of parameter that is updated by x.

fun

(function(1)) Function used to update y, must include self in formal arguments and self$getParameterValue("<x>") in body where "<x>" is the id supplied to x. See first example.

dt

([data.table::data.table]) Alternate method to directly construct data.table of dependencies to add. See second example.

Examples

id <- list("rate", "scale")
value <- list(1, 1)
support <- list(set6::PosReals$new(), set6::PosReals$new())
settable <- list(TRUE, FALSE)
ps <- ParameterSet$new(
  id, value, support, settable
)
ps$addDeps("scale", "rate", function(self) 1 / self$getParameterValue("scale"))
ps$addDeps("rate", "scale", function(self) 1 / self$getParameterValue("rate"))
ps$deps

# Alternate method ps <- ParameterSet$new( id, value, support, settable ) ps$addDeps(dt = data.table::data.table(x = c("scale", "rate"), y = c("rate", "scale"), fun = c(function(self) 1 / self$getParameterValue("scale"), function(self) 1 / self$getParameterValue("rate")) ) ) ps$deps

Method addChecks()

Add parameter checks for automatic assertions. Note checks are made after any transformations.

Usage

ParameterSet$addChecks(x, fun, dt = NULL)

Arguments

x

(character(1)) id of parameter to be checked.

fun

(function(1)) Function used to check x, must include x, self in formal arguments and x in body where x is the value of the parameter to check. Result should be a logical. See first example.

dt

([data.table::data.table]) Alternate method to directly construct data.table of checks to add. See second example.

Examples

id <- list("lower", "upper")
value <- list(1, 3)
support <- list(set6::PosReals$new(), set6::PosReals$new())
ps <- ParameterSet$new(
  id, value, support
)
ps$addChecks("lower", function(x, self) x < self$getParameterValue("upper"))
ps$checks
\dontrun{
# errors as check fails
ps$setParameterValue(lower = 4)
}
ps$setParameterValue(lower = 2)

# Alternate method (better with more parameters) ps <- ParameterSet$new( id, value, support ) ps$addChecks(dt = data.table::data.table( x = "lower", fun = function(x, self) x < self$getParameterValue("upper") ))

Method addTrafos()

Transformations to apply to parameter before setting. Note transformations are made before checks. NOTE: If a transformation for a parameter already exists then this will be overwritten.

Usage

ParameterSet$addTrafos(x, fun, dt = NULL)

Arguments

x

(character(1)) id of parameter to be transformed. Only one trafo function per parameter allowed - though multiple transformations can be encoded within this.

fun

(function(1)) Function used to transform x, must include x, self in formal arguments and x in body where x is the value of the parameter to check. See first example.

dt

([data.table::data.table]) Alternate method to directly construct data.table of transformations to add. See second example.

Examples

ps <- ParameterSet$new(
  "probs", list(c(1, 1)), set6::Interval$new(0,1)^2
)
ps$addTrafos("probs", function(x, self) return(x / sum(x)))
ps$trafos
ps$setParameterValue(probs = c(1, 2))
ps$getParameterValue("probs")

# Alternate method (better with more parameters) ps <- ParameterSet$new( "probs", list(c(1, 1)), set6::Interval$new(0,1)^2 ) ps$addTrafos(dt = data.table::data.table( x = "probs", fun = function(x, self) return(x / sum(x)) ))

Method values()

Returns parameter set values as a named list.

Usage

ParameterSet$values(settable = TRUE)

Arguments

settable

(logical(1)) If TRUE (default) only returns values of settable parameters, otherwise returns all.

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

# NOT RUN {
## ------------------------------------------------
## Method `ParameterSet$new`
## ------------------------------------------------

id <- list("prob", "size")
value <- list(0.2, 5)
support <- list(set6::Interval$new(0, 1), set6::PosNaturals$new())
description <- list("Probability of success", NULL)
ParameterSet$new(id = id,
                 value = value,
                 support = support,
                 description = description
 )

ParameterSet$new(id = "prob",
                 value = 0.2,
                 support = set6::Interval$new(0, 1),
                 description = "Probability of success"
 )

## ------------------------------------------------
## Method `ParameterSet$getParameterSupport`
## ------------------------------------------------

ps <- ParameterSet$new(id = "prob",
                 value = 0.2,
                 support = set6::Interval$new(0, 1),
                 settable = TRUE,
                 description = "Probability of success"
 )
ps$getParameterSupport("prob")

## ------------------------------------------------
## Method `ParameterSet$getParameterValue`
## ------------------------------------------------

ps <- ParameterSet$new(id = "prob",
                 value = 0.2,
                 support = set6::Interval$new(0, 1),
                 settable = TRUE,
                 description = "Probability of success"
 )
ps$getParameterValue("prob")

## ------------------------------------------------
## Method `ParameterSet$setParameterValue`
## ------------------------------------------------

id <- list("rate", "scale")
value <- list(1, 1)
support <- list(set6::PosReals$new(), set6::PosReals$new())
settable <- list(TRUE, FALSE)
ps <- ParameterSet$new(
  id, value, support, settable,
)
ps$addDeps("scale", "rate", function(self) 1 / self$getParameterValue("scale"))
ps$addDeps("rate", "scale", function(self) 1 / self$getParameterValue("rate"))
ps$getParameterValue(id = "rate")
ps$setParameterValue(rate = 2)
ps$getParameterValue("rate")
ps$getParameterValue("scale") # Auto-updated to 1/2

## ------------------------------------------------
## Method `ParameterSet$merge`
## ------------------------------------------------

ps1 <- ParameterSet$new(id = c("prob", "qprob"),
                 value = c(0.2, 0.8),
                 support = list(set6::Interval$new(0, 1), set6::Interval$new(0, 1))
 )
 ps1$addChecks("prob", function(x, self) x > 0)
 ps1$addDeps("prob", "qprob", function(self) 1 - self$getParameterValue("prob"))
 ps2 <- ParameterSet$new(id = "size",
                 value = 10,
                 support = set6::Interval$new(0, 10, class = "integer"),
 )
 ps2$addTrafos("size", function(x, self) x + 1)
 ps1$merge(ps2)
 ps1$print()
 ps1$trafos
 ps1$checks
 ps1$deps

## ------------------------------------------------
## Method `ParameterSet$addDeps`
## ------------------------------------------------

id <- list("rate", "scale")
value <- list(1, 1)
support <- list(set6::PosReals$new(), set6::PosReals$new())
settable <- list(TRUE, FALSE)
ps <- ParameterSet$new(
  id, value, support, settable
)
ps$addDeps("scale", "rate", function(self) 1 / self$getParameterValue("scale"))
ps$addDeps("rate", "scale", function(self) 1 / self$getParameterValue("rate"))
ps$deps

# Alternate method
ps <- ParameterSet$new(
  id, value, support, settable
)
ps$addDeps(dt = data.table::data.table(x = c("scale", "rate"),
                          y = c("rate", "scale"),
                          fun = c(function(self) 1 / self$getParameterValue("scale"),
                                  function(self) 1 / self$getParameterValue("rate"))
                         )
           )
ps$deps

## ------------------------------------------------
## Method `ParameterSet$addChecks`
## ------------------------------------------------

id <- list("lower", "upper")
value <- list(1, 3)
support <- list(set6::PosReals$new(), set6::PosReals$new())
ps <- ParameterSet$new(
  id, value, support
)
ps$addChecks("lower", function(x, self) x < self$getParameterValue("upper"))
ps$checks
# }
# NOT RUN {
# errors as check fails
ps$setParameterValue(lower = 4)
# }
# NOT RUN {
ps$setParameterValue(lower = 2)

# Alternate method (better with more parameters)
ps <- ParameterSet$new(
  id, value, support
)
ps$addChecks(dt = data.table::data.table(
                          x = "lower",
                          fun = function(x, self) x < self$getParameterValue("upper")
           ))

## ------------------------------------------------
## Method `ParameterSet$addTrafos`
## ------------------------------------------------

ps <- ParameterSet$new(
  "probs", list(c(1, 1)), set6::Interval$new(0,1)^2
)
ps$addTrafos("probs", function(x, self) return(x / sum(x)))
ps$trafos
ps$setParameterValue(probs = c(1, 2))
ps$getParameterValue("probs")

# Alternate method (better with more parameters)
ps <- ParameterSet$new(
  "probs", list(c(1, 1)), set6::Interval$new(0,1)^2
)
ps$addTrafos(dt = data.table::data.table(
                          x = "probs",
                          fun = function(x, self) return(x / sum(x))
           ))
# }