LambertW-toolkit {LambertW}

Do-it-yourself toolkit for Lambert W \times F distribution

Description

IMPORTANT: This toolkit functionality is still under active development; function names, arguments, return values, etc. may change.

This do-it-yourself Lambert W \times F toolkit implements the flexible input/output framework of Lambert W \times F random variables (see References). Using a modular approach, it allows users to create their own Lambert W \times 'MyFavoriteDistribution' RVs. See Details below.

If the distribution you inted to use is not already implemented (get_distnames), then you can create it:

create input:

use create_LambertW_input with your favorite distribution,

create output:

pass it as an input argument to create_LambertW_output,

use output:

use Rs standard functionality for distributions such as random number generation (rY), pdf (dY) and cdf (pY), quantile function (qY), etc. for this newly generated Lambert W \times 'MyFavoriteDistribution'.

create_LambertW_output converts the input LambertW_input representing random variable X \sim F_X to the Lambert W \times F_X output.

Usage

create_LambertW_input(
  distname = NULL,
  beta,
  input.u = list(beta2tau = NULL, d = NULL, p = NULL, r = NULL, q = NULL, distname =
    "MyFavoriteDistribution", is.non.negative = FALSE)
)

create_LambertW_output(
  LambertW.input = NULL,
  theta = NULL,
  distname = LambertW.input$distname
)

Arguments

distname

character; name of input distribution; see get_distnames.

beta

numeric vector (deprecated); parameter \boldsymbol \beta of the input distribution. See check_beta on how to specify beta for each distribution.

input.u

optional; users can make their own 'Lambert W x F' distribution by supplying the necessary functions. See Description for details.

LambertW.input

an object of class LambertW_input

theta

list; a (possibly incomplete) list of parameters alpha, beta, gamma, delta. complete_theta fills in default values for missing entries.

Details

create_LambertW_output takes an object of class LambertW_input and creates a class LambertW_output for standard distributions as well as the user-defined distribution. This LambertW_output represents the RV Y \sim Lambert W \times 'MyFavoriteDistribution' with all its properties and R functionality, such as random number generation (rY), pdf (dY) and cdf (pY), etc.

create_LambertW_input allows users to define their own Lambert W\times F distribution by supplying the necessary functions about the input random variable U and \boldsymbol \beta. Here U is the zero mean and/or unit variance version of X \sim F_X(x \mid \boldsymbol \beta) (see References).

The argument input.u must be a list containing all of the following:

beta2tau

R function of (beta): converts \boldsymbol \beta to \tau for the user defined distribution

distname

optional; users can specify the name of their input distribution. By default it's called "MyFavoriteDistribution". The distribution name will be used in plots and summaries of the Lambert W\times F input (and output) object.

is.non.negative

logical; users should specify whether the distribution is for non-negative random variables or not. This will help for plotting and theoretical quantile computation.

d

R function of (u, beta): probability density function (pdf) of U,

p

R function of (u, beta): cumulative distribution function (cdf) of U,

q

R function of (p, beta): quantile function of U,

r

R function (n, beta): random number generator for U,

Value

create_LambertW_output returns a list of class LambertW_output with values that are (for the most part) functions themselves (see Examples):

d

pdf of Y \sim Lambert W \times 'MyFavoriteDistribution',

p

cdf of Y,

q

quantile function for Y,

r

random number generator for Y,

distname

character string with the name of the new distribution. Format: "Lambert W x 'MyFavoriteDistribution'",

beta, theta

see Arguments,

distname.with.beta

name of the new distribution including the parameter beta. Format: "Lambert W x 'MyFavoriteDistribution'(beta)".

Author(s)

Georg M. Goerg

Examples

# create a Gaussian N(1, 2) input
Gauss.input <- create_LambertW_input("normal", beta = c(1, 2))

# create a heavy-tailed version of a normal
# gamma = 0, alpha = 1 are set by default; beta comes from input
params <- list(delta = c(0.3)) 
LW.Gauss <- create_LambertW_output(LambertW.input = Gauss.input, 
                                   theta = params)
LW.Gauss

op <- par(no.readonly = TRUE)
par(mfrow = c(2, 1), mar = c(3, 3, 2, 1))
curve(LW.Gauss$d(x, params), -7, 10, col = "red")
# parameter will get detected automatically from the input
curve(LW.Gauss$d(x), -7, 10, col = "blue") # same in blue; 

# compare to the input case (i.e. set delta = 0)
params.0 <- params 
params.0$delta <- 0

# to evaluate the RV at a different parameter value, 
# it is necessary to pass the new parameter
curve(LW.Gauss$d(x, params.0), -7, 10, add = TRUE, col = 1) #' par(op)

curve(LW.Gauss$p(x, params), -7, 10, col = "red")
curve(LW.Gauss$p(x, params.0), -7, 10, add = TRUE, col = 1)

test_normality(LW.Gauss$r(n = 100), add.legend = FALSE)

## generate a positively skewed version of a shifted, scaled t_3
t.input <- create_LambertW_input("t", beta = c(2, 1, 3))
t.input
params <- list(gamma = 0.05) # skew it
LW.t <- create_LambertW_output(LambertW.input = t.input, theta = params)
LW.t

plot(t.input$d, -7, 11, col = 1)
plot(LW.t$d, -7, 11, col = 2, add = TRUE)
abline(v = t.input$beta["location"], lty = 2)

# draw samples from the skewed t_3
yy <- LW.t$r(n = 100)
test_normality(yy)

### create a skewed exponential distribution
exp.input <- create_LambertW_input("exp", beta = 1)
plot(exp.input)
params <- list(gamma = 0.2)
LW.exp <- create_LambertW_output(exp.input, theta = params)
plot(LW.exp)

# create a heavy-tail exponential distribution
params <- list(delta = 0.2)
LW.exp <- create_LambertW_output(exp.input, theta = params)
plot(LW.exp)

# create a skewed chi-square distribution with 5 df
chi.input <- create_LambertW_input("chisq", beta = 5)
plot(chi.input)
params <- list(gamma = sqrt(2)*0.2)
LW.chi <- create_LambertW_output(chi.input, theta = params)
plot(LW.chi)


# a demo on how a user-defined U input needs to look like
user.tmp <- list(d = function(u, beta) dnorm(u),
                 r = function(n, beta) rnorm(n),
                 p = function(u, beta) pnorm(u),
                 q = function(p, beta) qnorm(p),
                 beta2tau = function(beta) {
                   c(mu_x = beta[1], sigma_x = beta[2], 
                     gamma = 0, alpha = 1, delta = 0)
                   },
                 distname = "MyNormal",
                 is.non.negative = FALSE)
my.input <- create_LambertW_input(input.u = user.tmp, beta = c(0, 1))
my.input
plot(my.input)