Create 'RAVE' constrained variables

Create a variable that automatically validates

Usage

new_constraints(type, assertions = NULL)

new_constrained_variable(name, initial_value, constraints = NULL, ...)

new_constrained_binding(name, expr, quoted = FALSE, constraints = NULL, ...)

Arguments

type

variable type; checkmate::assert_* will be automatically applied if applicable

assertions

named list; each name stands for an assertion type, and the corresponding item can be one of the follows; please see 'Examples' for usages.

list of arguments or NULL

name of the assertion must be a valid assertion function in package checkmate. For example, list(numeric=NULL) will call checkmate::assert_numeric when value is validated

a function

name of the assertion can be arbitrary, users are in charge of the validation function. This function should take only one argument and return either TRUE if the validation passes, or a character of the error message.

name

character(1), variable name

initial_value

initial value, if missing, then variable will be assigned with an empty list with class name 'key_missing'

constraints, ...

when constraints is an instance of RAVEVariableConstraints, ... will be ignored. When constraints is a string, then constraints will be passed to new_constraints (see argument type), and ... will be packed as assertion parameters (see assertions)

expr

expression for binding

quoted

whether expr is quoted, default is false

Examples

# ---- Basic usage ----------------------------------------
analysis_range <- new_constrained_variable("Analysis range")

# Using checkmates::assert_numeric
analysis_range$use_constraints(
  constraints = "numeric",
  any.missing = FALSE,
  len = 2,
  sorted = TRUE,
  null.ok = FALSE
)

analysis_range$initialized # FALSE
#> [1] FALSE
print(analysis_range)
#> <RAVEVariable>[type=numeric,constrants=1,label=Analysis range] (missing)

# set value
analysis_range$set_value(c(1, 2))

# get value
analysis_range$value   # or $get_value()
#> [1] 1 2

# ---- Fancy constraints ------------------------------------
# construct an analysis range between -1~1 or 4~10
time_window <- validate_time_window(c(-1, 1, 4, 10))
analysis_range <- new_constrained_variable("Analysis range")
analysis_range$use_constraints(
  constraints = new_constraints(
    type = "numeric",
    assertions = list(
      # validator 1
      "numeric" = list(
        any.missing = FALSE,
        len = 2,
        sorted = TRUE,
        null.ok = FALSE
      ),

      # validator 2
      "range" = quote({
        check <- FALSE
        if(length(.x) == 2) {
          check <- sapply(time_window, function(w) {
            if(
              .x[[1]] >= w[[1]] &&
              .x[[2]] <= w[[2]]
            ) { return (TRUE) }
            return( FALSE )
          })
        }
        if(any(check)) { return(TRUE) }

        valid_ranges <- paste(
          sapply(time_window, function(w) {
            paste(sprintf("%.2f", w), collapse = ",")
          }),
          collapse = "] or ["
        )
        return(sprintf("Invalid range: must be [%s]", valid_ranges))
      })
    )
  )
)

# validate and print out error messages
# remove `on_error` argument to stop on errors
analysis_range$validate(on_error = "message")
#> RAVE validation failed: 
#> * Variable 'Analysis range': Must be of type 'numeric', not 'key_missing'.
#> Collection of 1 assertion.

# Try with values (-2,1) instead of c(0,1)
analysis_range$value <- c(0, 1)
#> Error in pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE): 1 assertions failed:
#>  * Variable 'Analysis range': Error when checking `numeric`
#>  * (validator=range): object 'time_window' not found.

print(analysis_range)
#> <RAVEVariable>[type=numeric,constrants=2,label=Analysis range] (missing)
analysis_range[]
#> <Key Missing>

# Change the context
time_window <- validate_time_window(c(0, 0.5))

# re-validate will error out
analysis_range$validate(on_error = "message")
#> RAVE validation failed: 
#> * Variable 'Analysis range': Must be of type 'numeric', not 'key_missing'.
#> Collection of 1 assertion.