Context Aware Random Number Generation

Description

rando is designed to make random number generation easier by providing the ability to set a default number of numbers to generate or to assess the context in which the functions are being ran.

Convert to function

Description

This function is a wrapper around rlang::as_function() which adds a two extra features:

• formulas can use .t in place of .x to be easier to understand in time-based functions

• functions can take additional named arguments.

Usage

as_function(x, env = parent.frame())

Arguments

Value

Either:

• the function as it is passed to as_function(), whether as a string or a name

• the function derived from a formula, where the first argument is passed as ., .x or .t, the second argument is passed as .y and any other named arguments are passed as they are named

Examples

f1 <- as_function(mean)
f1(1:10)

f2 <- as_function("sum")
f2(1,2,3)

f3 <- as_function(~.x + 1)
f3(9)

f4 <- as_function(~ .t + 1)
f4(10)

f5 <- as_function(~.x + .y)
f5(1,2)

f6 <- as_function(~ .t + alpha)
f6(10, alpha = 2)

Blueprint a Dataset

Description

Allows for the generation of population based on a prescribed set of rando functions.

Usage

blueprint(...)

is_blueprint(bp)

Arguments

Value

A function that will produce a tibble, which matches the blueprint that was provided. The generated function will take the following arguments:

• ... - any arguments that are used within the blueprinting

• n - the number of rows that the resulting tibble should be

• .seed - the random seed to set before generating the data

is_blueprint() simply checks whether a function is a blueprinting function or not and returns a logical.

Examples

make_tbl <- blueprint(
  x = r_norm(),
  y = r_norm()
)

make_tbl(n = 2)

make_tbl(n = 5)

# Blueprints can use additional parameters:
make_tbl2 <- blueprint(
  x = r_norm(mean = x_mu),
  y = r_unif(min = y_min, max = y_max)
)

# Which are simply passed to the generated function
make_tbl2(x_mu = 10, y_min = -10, y_max = -5)

is_blueprint(make_tbl)

Blueprint based on a condition

Description

Runs a blueprint function where a condition is true, otherwise returns NA values

Usage

bp_where(condition, bp, ...)

Arguments

Value

a tibble

Examples

make_tbl <- blueprint(
  x = r_norm(),
  y = r_unif()
)

set_n(10)
i <- r_lgl()

bp_where(i, make_tbl)

df <- tibble::tibble(
  id = 1:10,
  cnd = r_lgl()
)
dplyr::mutate(df, bp_where(cnd, make_tbl))

Find the Default Value for n in Context

Description

Checks for various information surrounding the call to this function to figure out what value for n should be used

Usage

default_n(...)

blueprint_n()

tibble_n()

dplyr_n()

args_n(...)

Arguments

Details

The default_n() function will run through the other functions found here until it finds a viable value for n.

It first checks for contxt to see if calls external to default_n() indicate which value should be used:

• blueprint_n() - Checks if the function is being called within a blueprinting function, and returns the value supplied to that function, see blueprint().

• tibble_n() - Checks if the function is being called within the declaration of a tibble. It then checks the lengths of the other arguments being passed to the call. If you want to specify how many rows should be generate you can use the .rows argument in your tibble() call, see tibble()

• dplyr_n() - Checks if the function is being used within a dplyr verb, if so, it returns the value of n()

It then checks the lengths of the arguments supplied via ..., if there is a discrepancy between these arguments and the context aware value found above, it will throw an error.

If all the above values return 1 or NULL, we then check for a global n assigned by set_n(), if none is set then default_n() will return 1.

Value

The context aware value for n

Examples

# Global Values:
set_n(NULL)
default_n()
set_n(10)
default_n()

# In a blueprint:
bp <- blueprint(x=r_norm(),n=default_n())
bp(n=7)
bp <- blueprint(x=r_norm(),n=blueprint_n())
bp(n=8)

# In a tibble:
tibble::tibble(id = 1:3, n = default_n())
tibble::tibble(id = 1:5, n = tibble_n())

# In a dplyr verb:
df <- tibble::tibble(id = 1:4)
dplyr::mutate(df, n = default_n())
dplyr::mutate(df, n = dplyr_n())

# From arguments:
default_n(1:5)
default_n(1:5,c("a","b","c","d","e"))
args_n(1:3,c("a","b","d"))
args_n(1:3, 1:4)

## Not run: 
default_n(1:3, 1:4)
tibble::tibble(id=1:5,n=default_n(1:4))

## End(Not run)

Extract the ellipsis inside a function

Description

Allow the named entries in ... to be used easily within a function by attaching them to the function's environment

Usage

extract_dots()

Value

No return value, called for it's side effect

Examples

f <- function(...) {
  a + b
}

## Not run: 
# Throws an error because a and b are trapped inside `...`
 f(a = 1, b = 2)

## End(Not run)

f <- function(...) {
  extract_dots()
  a + b
}
f(a = 1, b = 2)

Check if a Number is Whole

Description

The built-in function is.integer() will check if a number is of the integer class. However, we would usually want a function that can check if a number is a whole number. It is also vectorised over the input.

Usage

is_wholenumber(x, tol = .Machine$double.eps^0.5)

Arguments

Value

A logical vector the same length as x

Examples

is.integer(2)
is_wholenumber(2)

is.integer(seq(2, 3, 0.25))
is_wholenumber(seq(2, 3, 0.25))

The logit and inverse logit functions

Description

Calculates the logit or the inverse logit of a value

Usage

logit(prob, base = exp(1))

invlogit(alpha, base = exp(1))

Arguments

Value

A numeric vector

Examples

logit(0.5)

logit(seq(0.01, 0.99, 0.01))
invlogit(-10:10)

Alternate Parametrisation of match.call()

Description

Alters the built-in function match.call() by providing an additional argument which means that by default a user can specify how far up the call stack they want to match a call of. See match.call() for more details.

Usage

match.call2(
  n = 0L,
  definition = sys.function(sys.parent(n + 1L)),
  call = sys.call(sys.parent(n + 1L)),
  expand.dots = TRUE,
  envir = parent.frame(n + 3L)
)

Arguments

Value

An object of class call

Examples

f <- function(n) {
  g(n)
}

g <- function(n) {
  h(n)
}

h <- function(n) {
  match.call2(n)
}

f(0)
f(1)
f(2)

Evaluate Expressions until not NULL

Description

Evaluates expressions until one that is not NULL is encountered and returns that. Expressions after the first non-NULL result are not evaluated. If all expressions are NULL, it will return NULL

Usage

null_switch(...)

Arguments

Value

The result of evaluating one of the expressions. Will only be NULL if they all evaluated to NULL

Examples

f <- function() {
  cat("Evaluating f\n")
  NULL
}
g <- function() {
  cat("Evaluating g\n")
  2
}

null_switch(NULL, f(), g())
null_switch(NULL, g(), f())
null_switch(f(), f(), f())

Generate Bernoulli Distributed Values

Description

Generates a set of Bernoulli distributed values.

Usage

r_bern(prob = 0.5, ..., n = default_n(prob), .seed = NULL)

Arguments

Value

A numeric vector of length n

Examples

set_n(5)

r_bern(0.9)

r_bern(seq(0, 1, 0.1))

r_bern(1 / 4, n = 10)

Generate Beta Distributed Values

Description

Generates a set of Beta distributed values.

Usage

r_beta(alpha, beta, ..., n = default_n(alpha, beta), .seed = NULL)

Arguments

Value

A numeric vector of length n

Examples

set_n(5)

r_beta(1, 1)

r_beta(1:10, 2)

r_beta(1, 2, n = 10)

Generate Binomial Distributed Values

Description

Generates a set of Binomial distributed values.

Usage

r_binom(size, prob = 0.5, ..., n = default_n(size, prob), .seed = NULL)

Arguments

Value

A numeric vector of length n

Examples

set_n(5)

r_binom(10)

r_binom(1:10)

r_binom(10, 0.2)

r_binom(1, 0.2, n = 10)

Generate Cauchy Distributed Values

Description

Generates a set of Cauchy distributed values.

Usage

r_cauchy(
  location = 0,
  scale = 1,
  ...,
  n = default_n(location, scale),
  .seed = NULL
)

Arguments

Value

A numeric vector of length n

Examples

set_n(5)

r_cauchy(10)

r_cauchy(1:10)

r_cauchy(10, 2)

r_cauchy(10, 2, n = 10)

Generate Random Numbers Based on an arbitrary CDF

Description

Generates Random Numbers based on a distribution defined by any arbitrary cumulative distribution function

Usage

r_cdf(
  Fun,
  min = -Inf,
  max = Inf,
  ...,
  data = NULL,
  n = default_n(..., data),
  .seed = NULL
)

Arguments

Details

The Fun argument accepts purrr style inputs. Must be vectorised, defined on the whole Real line and return a single numeric value between 0 and 1 for any input. The random variable will be passed to Fun as the first argument. This means that R's argument matching can be used with named arguments in ... if a different positional argument is wanted.

Value

A numeric vector of length n

Examples

set_n(5)

my_fun <- function(x, beta = 1) {
  1 - exp(-beta * x)
}

r_cdf(my_fun)


r_cdf(~ 1 - exp(-.x), min = 0)

r_cdf(~ 1 - exp(-.x * beta), beta = 1:10, min = 0)

Generate Chi-Squared Distributed Values

Description

Generates a set of Chi-Squared distributed values.

Usage

r_chisq(df, ..., n = default_n(df), .seed = NULL)

Arguments

Value

A numeric vector of length n

Examples

set_n(5)

r_chisq(10)

r_chisq(1:10)

r_chisq(10, n = 10)

Generate Exponentially Distributed Values

Description

Generates a set of Exponentially distributed values.

Usage

r_exp(rate = 1, ..., n = default_n(rate), .seed = NULL)

Arguments

Value

A numeric vector of length n

Examples

set_n(5)

r_exp(10)

r_exp(1:10)

r_exp(10, n = 10)

Generate F Distributed Values

Description

Generates a set of F distributed values.

Usage

r_fdist(df1, df2, ..., n = default_n(df1, df2), .seed = NULL)

Arguments

Value

A numeric vector of length n

Examples

set_n(5)

r_fdist(1, 1)

r_fdist(1:10, 2)

r_fdist(10, 2)

r_fdist(10, 2, n = 10)

Generate Gamma Distributed Values

Description

Generates a set of Gamma distributed values. Can be defined by one and only one of scale, rate or mean. This must be named in the call.

Usage

r_gamma(
  shape,
  ...,
  scale = 1,
  rate = NULL,
  mean = NULL,
  n = default_n(shape, scale, rate, mean),
  .seed = NULL
)

Arguments

Value

A numeric vector of length n

Examples

set_n(5)

r_gamma(10)

r_gamma(1:10, scale = 2)
r_gamma(1:10, rate = 1 / 2)
r_gamma(1:10, mean = 5)

r_gamma(10, n = 10)

Generate Geometric Distributed Values

Description

Generates a set of Geometric distributed values.

Usage

r_geom(prob = 0.5, ..., n = default_n(prob), .seed = NULL)

Arguments

Value

A numeric vector of length n

Examples

set_n(5)

r_geom(0.1)

r_geom(seq(0.1, 1, 0.1))

r_geom(0.1, n = 10)

Generate Hypergeometric Distributed Values

Description

Generates a set of Hypergeometric distributed values.

Usage

r_hyper(
  total,
  positives,
  num,
  ...,
  n = default_n(total, positives, num),
  .seed = NULL
)

Arguments

Value

A numeric vector of length n

Examples

set_n(5)

r_hyper(10, 5, 5)

r_hyper(10:20, 10, 5)

r_hyper(10, 5, 5, n = 10)

Generate Random Letters

Description

Generates a set of Random Letters.

Usage

r_letters(nchar = 1, ..., n = default_n(nchar), .seed = NULL)

r_LETTERS(nchar = 1, ..., n = default_n(nchar), .seed = NULL)

r_Letters(nchar = 1, ..., n = default_n(nchar), .seed = NULL)

Arguments

Value

A character vector of length n

Functions

• r_letters: Uses only lower-case letters

• r_LETTERS: Uses only upper-case letters

• r_Letters: Uses lower- & upper-case letters

Examples

set_n(5)

r_letters(3)

r_letters(1:10)

r_letters(3, n = 10)

r_LETTERS(3)

r_LETTERS(1:10)

r_LETTERS(3, n = 10)

r_Letters(3)

r_Letters(1:10)

r_Letters(3, n = 10)

Generate Logical Values

Description

Generates a set of Logical values.

Usage

r_lgl(prob = 0.5, ..., n = default_n(prob), .seed = NULL)

Arguments

Value

A logical vector of length n

Examples

set_n(5)

r_lgl(0.9)

r_lgl(seq(0, 1, 0.1))

r_lgl(1 / 4, n = 10)

Generate Log Normal Distributed Values

Description

Generates a set of Log Normal distributed values.

Usage

r_lnorm(
  mean_log = 0,
  sd_log = 1,
  ...,
  n = default_n(mean_log, sd_log),
  .seed = NULL
)

Arguments

Value

A numeric vector of length n

Examples

set_n(5)

r_lnorm(10)

r_lnorm(10, 2)

r_lnorm(1:10)

r_lnorm(-2, n = 10)

Generate a random Matrix

Description

Generate a random matrix, given a rando function and it's dimensions. By default, this will generate a square matrix.

Usage

r_matrix(
  engine,
  row_names = NULL,
  col_names = NULL,
  ...,
  nrow = default_n(row_names),
  ncol = default_n(col_names),
  .seed = NULL
)

Arguments

Value

A matrix with nrow rows and ncol columns an a type as decided by the function passed to engine.

Examples

set_n(5)

r_matrix(r_norm)


r_matrix(r_unif,min=1,max=2)


r_matrix(r_norm,mean=10,sd=2,ncol=2)

Generate Negative Binomial Distributed Values

Description

Generates a set of Negative Binomial distributed values. Only two of r, prob and mu can be provided.

Usage

r_nbinom(
  r = NULL,
  prob = 0.5,
  ...,
  mu = NULL,
  n = default_n(r, prob, mu),
  .seed = NULL
)

Arguments

Value

A numeric vector of length n

Note

It is important to note that this is the number of failures, and not the number of successes, as in rnbinom(), so rnbinom(prob = x,...) is equivalent to r_nbinom(prob=1-x,...)

Examples

set_n(5)

r_nbinom(10, 0.5)

r_nbinom(1:10, mu = 2)
#'
r_nbinom(10, 0.2, n = 10)

Generate Normally Distributed Values

Description

Generates a set of Normally distributed values.

Usage

r_norm(mean = 0, sd = 1, ..., n = default_n(mean, sd), .seed = NULL)

Arguments

Value

A numeric vector of length n

Examples

set_n(5)

r_norm(10)

r_norm(10, 2)

r_norm(1:10)

r_norm(-2, n = 10)

Generate Poisson Distributed Values

Description

Generates a set of Poisson distributed values.

Usage

r_pois(rate, ..., n = default_n(rate), .seed = NULL)

Arguments

Value

A numeric vector of length n

Examples

set_n(5)

r_pois(10)

r_pois(1:10)

r_pois(10, n = 10)

Generate Random Sample

Description

Generates a Sample from a set, with replacement

Usage

r_sample(sample, weights = NULL, ..., n = default_n(), .seed = NULL)

Arguments

Value

A vector of length n of the same type as sample

Examples

set_n(15)

r_sample(c("blue", "red", "yellow"))

r_sample(c("blue", "red", "yellow"),
  weights = c(1, 5, 1)
)

r_sample(c("blue", "red", "yellow"), n = 10)

Generate T Distributed Values

Description

Generates a set of Student's T distributed values.

Usage

r_tdist(df, ..., n = default_n(df), .seed = NULL)

Arguments

Value

A numeric vector of length n

Examples

set_n(5)

r_tdist(10)

r_tdist(1:10)

r_tdist(10, n = 10)

Generate Uniformly Distributed Values

Description

Generates a set of Uniformly distributed values.

Usage

r_unif(min = 0, max = 1, ..., n = default_n(min, max), .seed = NULL)

Arguments

Value

A numeric vector of length n

Examples

set_n(5)

r_unif()

r_unif(1:5, 6:10)

r_unif(1:5, 10)

r_unif(n = 10)

Generate Weibull Distributed Values

Description

Generates a set of Weibull distributed values.

Usage

r_weibull(
  shape,
  scale = 1,
  ...,
  b_scale = NULL,
  B_scale = NULL,
  n = default_n(shape, scale, b_scale, B_scale),
  .seed = NULL
)

Arguments

Details

This function provides alternative definitions for the scale parameter depending on the user's parametrisation of the Weibull distribution, with k = shape.

Using \lambda = scale:

F(x) = 1 - exp(-(x/\lambda)^k)

Using b = b_scale:

F(x) = 1 - exp(-bx^k)

Using \beta = B_scale:

F(x) = 1 - exp(-(\beta x)^k)

Value

A numeric vector of length n

Examples

set_n(5)

r_weibull(10)

r_weibull(1:10, 2)

r_weibull(1:10, scale = 2)
r_weibull(1:10, b_scale = 2)
r_weibull(1:10, B_scale = 2)

r_weibull(10, 2, n = 10)

Random Seed Defining Functions

Description

Functions related to generating random seeds and utilising them for reproducibility.

Usage

gen_seed()

set_seed(seed)

fix_seed(reset = FALSE)

with_seed(seed, expression)

pull_seed(x)

Arguments

Details

Random values are generated based on the current seed used by the R system. This means by deliberately setting a seed in R, we can make work reproducible.

Value

gen_seed() returns a single numeric value

with_seed() returns the value of the evaluated expression after with the relevant seed as an attribute (if required)

pull_seed() returns a single numeric value

fix_seed() and set_seed() do not return anything

Functions

• gen_seed: Generates a random seed, which can be used in set_seed()

• set_seed: Sets the current seed

• fix_seed: Resets the seed to re-run code

• with_seed: Evaluates the expression after setting the seed. If seed is TRUE, then it first generates a seed using gen_seed(). Results are output with the seed attached (if set).#'

• pull_seed: Extracts the seed used to generate the results of with_seed()

Examples

my_seed <- gen_seed()


set_seed(my_seed)
r_norm(n=10)
set_seed(my_seed)
r_norm(n=10)


fix_seed()
r_norm(n=3)

fix_seed()
r_norm(n=3)

fix_seed(reset=TRUE)
r_norm(n=3)


res <- with_seed(my_seed, r_norm(n = 10))
res


pull_seed(res)

Set and Get the Default Value for n

Description

Set and get the global value for n for rando functions

Usage

set_n(n)

get_n()

Arguments

Value

The current global default value for n.
set_n() returns this value invisibly

Examples

set_n(100)

get_n()