dials (version 1.3.0)

value_validate: Tools for working with parameter values

Description

Setters and validators for parameter values. Additionally, tools for creating sequences of parameter values and for transforming parameter values are provided.

Usage

value_validate(object, values, ..., call = caller_env())
value_seq(object, n, original = TRUE)
value_sample(object, n, original = TRUE)
value_transform(object, values)
value_inverse(object, values)
value_set(object, values)

Value

value_validate() throws an error or silently returns values if they are contained in the values of the object.

value_transform() and value_inverse() return a vector of numeric values.

value_seq() and value_sample() return a vector of values consistent with the type field of object.

Arguments

object

An object with class quant_param.

values

A numeric vector or list (including Inf). Values cannot include unknown(). For value_validate(), the units should be consistent with the parameter object's definition.

...

These dots are for future extensions and must be empty.

call

The call passed on to rlang::abort().

n

An integer for the (maximum) number of values to return. In some cases where a sequence is requested, the result might have less than n values. See Details.

original

A single logical. Should the range values be in the natural units (TRUE) or in the transformed space (FALSE, if applicable)?

Details

For sequences of integers, the code uses unique(floor(seq(min, max, length.out = n))) and this may generate an uneven set of values shorter than n. This also means that if n is larger than the range of the integers, a smaller set will be generated. For qualitative parameters, the first n values are returned.

For quantitative parameters, any values contained in the object are sampled with replacement. Otherwise, a sequence of values between the range values is returned. It is possible that less than n values are returned.

For qualitative parameters, sampling of the values is conducted with replacement. For qualitative values, a random uniform distribution is used.

Examples

library(dplyr)

penalty() %>% value_set(-4:-1)

# Is a specific value valid?
penalty()
penalty() %>% range_get()
value_validate(penalty(), 17)

# get a sequence of values
cost_complexity()
cost_complexity() %>% value_seq(4)
cost_complexity() %>% value_seq(4, original = FALSE)

on_log_scale <- cost_complexity() %>% value_seq(4, original = FALSE)
nat_units <- value_inverse(cost_complexity(), on_log_scale)
nat_units
value_transform(cost_complexity(), nat_units)

# random values in the range
set.seed(3666)
cost_complexity() %>% value_sample(2)