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

LambertW-toolkit {LambertW} | R Documentation

## 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 β 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 β. Here U is the zero mean and/or unit variance version of X \sim F_X(x \mid \boldsymbol β) (see References).

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

`beta2tau`

  R function of `(beta)`: converts \boldsymbol β to τ 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)

[Package LambertW version 0.6.7 Index]