The Package ‘NormalLaplace’: Summary Information

Description

This package provides a collection of functions for Normal Laplace distributions. Functions are provided for the density function, distribution function, quantiles and random number generation. The mean, variance, skewness and kurtosis of a given Normal Laplace distribution are given by nlMean, nlVar, nlSkew, and nlKurt respectively.

Author(s)

David Scott d.scott@auckland.ac.nz, Jason Shicong Fu

Maintainer: David Scott <d.scott@auckland.ac.nz>

References

William J. Reed. (2006) The Normal-Laplace Distribution and Its Relatives. In Advances in Distribution Theory, Order Statistics and Inference, pp. 61–74. Birkhäuser, Boston.

See Also

dnl, millsR, NormalLaplaceMeanVar

Mills Ratio

Description

Calculates the Mills ratio

Usage

millsR(y, log = FALSE)

Arguments

Details

The function calculates the Mills' Ratio. Since the Mill's Ratio converges to zero for large positive z and infinity for large negative z. The range over which the logarithm of the Mill's ratio may be calculated is greater than that for which the Mill's ratio itself may be calculated.

Value

The Mills' Ratio is

R(z)=\frac{1-\Phi(z)}{\phi(z)}

where \Phi(z) and \phi(z) are respectively the distribution function and density function of the standard normal distribution.

Author(s)

David Scott d.scott@auckland.ac.nz, Jason Shicong Fu

Examples

## compare millsR calculated directly with the millsR calculated
## by transforming to log scale and then back-transformed
millsR(1:10)
exp(millsR(1:10, log = TRUE))
exp(millsR(10*(1:10)))
exp(millsR(10*(1:10), log = TRUE))

Normal Laplace Distribution

Description

Density function, distribution function, quantiles and random number generation for the normal Laplace distribution, with parameters \mu (location), \delta (scale), \beta (skewness), and \nu (shape).

Usage

dnl(x, mu = 0, sigma = 1, alpha = 1, beta = 1,
    param = c(mu,sigma,alpha,beta))
pnl(q, mu = 0, sigma = 1, alpha = 1, beta = 1,
    param = c(mu,sigma,alpha,beta))
qnl(p, mu = 0, sigma = 1, alpha = 1, beta = 1,
    param = c(mu,sigma,alpha,beta),
    tol = 10^(-5), nInterpol = 100, subdivisions = 100, ...)
rnl(n, mu = 0, sigma = 1, alpha = 1, beta = 1,
    param = c(mu,sigma,alpha,beta))

Arguments

Details

Users may either specify the values of the parameters individually or as a vector. If both forms are specified, then the values specified by the vector param will overwrite the other ones.

The density function is

f(y)=\frac{\alpha\beta}{\alpha+\beta}\phi\left(\frac{y-\mu}{\sigma }% \right)\left[R\left(\alpha\sigma-\frac{(y-\mu)}{\sigma}\right)+% R\left(\beta \sigma+\frac{(y-\mu)}{\sigma}\right)\right]

The distribution function is

F(y)=\Phi\left(\frac{y-\mu}{\sigma}\right)-% \phi\left(\frac{y-\mu}{\sigma}\right)% \left[\beta R(\alpha\sigma-\frac{y-\mu}{\sigma})-% \alpha R\left(\beta\sigma+\frac{y-\mu}{\sigma}\right)\right]/% (\alpha+\beta)

The function R(z) is the Mills' Ratio, see millsR.

Generation of random observations from the normal Laplace distribution using rnl is based on the representation

Y\sim Z+W

where Z and W are independent random variables with

Z\sim N(\mu,\sigma^2)

and W following an asymmetric Laplace distribution with pdf

f_W(w) = \left\{ \begin{array}{ll}% (\alpha\beta)/(\alpha+\beta)e^{\beta w} & \textrm{for $w\le0$}\\ % (\alpha\beta)/(\alpha+\beta)e^{-\beta w} & \textrm{for $w>0$}% \end{array} \right.

Value

dnl gives the density function, pnl gives the distribution function, qnl gives the quantile function and rnl generates random variates.

Author(s)

David Scott d.scott@auckland.ac.nz, Jason Shicong Fu

References

William J. Reed. (2006) The Normal-Laplace Distribution and Its Relatives. In Advances in Distribution Theory, Order Statistics and Inference, pp. 61–74. Birkhäuser, Boston.

Examples

param <- c(0,1,3,2)
par(mfrow = c(1,2))


## Curves of density and distribution
curve(dnl(x, param = param), -5, 5, n = 1000)
title("Density of the Normal Laplace Distribution")
curve(pnl(x, param = param), -5, 5, n = 1000)
title("Distribution Function of the Normal Laplace Distribution")


## Example of density and random numbers
 par(mfrow = c(1,1))
 param1  <-  c(0,1,1,1)
 data1  <-  rnl(1000, param = param1)
 curve(dnl(x, param = param1),
       from = -5, to = 5, n = 1000, col = 2)
 hist(data1, freq = FALSE, add = TRUE)
 title("Density and Histogram")

Mean, Variance, Skewness and Kurtosis of the Normal Laplace Distribution.

Description

Functions to calculate the mean, variance, skewness and kurtosis of a specified normal Laplace distribution.

Usage

nlMean(mu = 0, sigma = 1, alpha = 1, beta = 1,
         param = c(mu, sigma, alpha, beta))
nlVar(mu = 0, sigma = 1, alpha = 1, beta = 1,
         param = c(mu, sigma, alpha, beta))
nlSkew(mu = 0, sigma = 1, alpha = 1, beta = 1,
         param = c(mu, sigma, alpha, beta))
nlKurt(mu = 0, sigma = 1, alpha = 1, beta = 1,
         param = c(mu, sigma, alpha, beta))

Arguments

Details

Users may either specify the values of the parameters individually or as a vector. If both forms are specified, then the values specified by the vector param will overwrite the other ones.

The mean function is

E(Y)=\mu+1/\alpha-1/\beta.

The variance function is

V(Y)=\sigma^2+1/\alpha^2+1/\beta^2.%

The skewness function is

\Upsilon = [2/\alpha^3-2/\beta^3]/[\sigma^2+1/\alpha^2+1/\beta^2]^{3/2}.%

The kurtosis function is

\Gamma = [6/\alpha^4 + 6/\beta^4]/[\sigma^2+1/\alpha^2+1/\beta^2]^2.

Value

nlMean gives the mean of the skew hyperbolic nlVar the variance, nlSkew the skewness, and nlKurt the kurtosis.

Author(s)

David Scott d.scott@auckland.ac.nz, Jason Shicong Fu

References

William J. Reed. (2006) The Normal-Laplace Distribution and Its Relatives. In Advances in Distribution Theory, Order Statistics and Inference, pp. 61–74. Birkhäuser, Boston.

Examples

param <- c(10,1,5,9)
nlMean(param = param)
nlVar(param = param)
nlSkew(param = param)
nlKurt(param = param)


curve(dnl(x, param = param), -10, 10)

Check Parameters of the Normal Laplace Distribution

Description

Given a set of parameters for the normal Laplace distribution, the functions checks the validity of each parameter and if they and if they correspond to the boundary cases.

Usage

nlCheckPars(param)

Arguments

Details

The vector param takes the form c(mu, sigma, alpha, beta).

If any of sigma, alpha or beta is negative or NA, an error is returned.

Author(s)

David Scott d.scott@auckland.ac.nz, Simon Potter

References

William J. Reed. (2006) The Normal-Laplace Distribution and Its Relatives. In Advances in Distribution Theory, Order Statistics and Inference, pp. 61–74. Birkhäuser, Boston.

Examples

## Correct parameters
nlCheckPars(c(0, 1.5, 1, 2))
nlCheckPars(c(3, 1, 1.5, 2))

## Incorrect parameters, each error providing a different error message
nlCheckPars(c(2, -1, 1, 1))          # invalid sigma
nlCheckPars(c(2, 1, -1, 2))          # invalid alpha
nlCheckPars(c(0, 1, 2, -1))          # invalid beta
nlCheckPars(c(0, -0.01, -0.1, 1))    # sigma and alpha incorrect
nlCheckPars(c(2, -0.5, 1, -0.2))     # sigma and beta incorrect
nlCheckPars(c(1, 1, -0.2, -1))       # alpha and beta incorrect
nlCheckPars(c(0, -0.1, -0.2, -0.3))  # all three parameters erroneous
nlCheckPars(c(0.5, NA, 1, 1))        # NA introduced
nlCheckPars(c(-1, 1, 1))             # incorrect number of parameters

Fit the Normal Laplace Distribution to Data

Description

Fits a normal Laplace distribution to data. Displays the histogram, log-histogram (both with fitted densities), Q-Q plot and P-P plot for the fit which has the maximum likelihood.

Usage

  nlFit(x, freq = NULL, breaks = "FD", paramStart = NULL,
        startMethod = "Nelder-Mead",
        startValues = c("MoM", "US"),
        method = c("Nelder-Mead", "BFGS", "L-BFGS-B",
                   "nlm", "nlminb"),
        hessian = FALSE,
        plots = FALSE, printOut = FALSE,
        controlBFGS = list(maxit = 200),
        controlLBFGSB = list(maxit = 200),
        controlNLMINB = list(),
        controlNM = list(maxit = 1000),
        maxitNLM = 1500, ...)
  ## S3 method for class 'nlFit'
print(x, digits = max(3, getOption("digits") - 3), ...)
  ## S3 method for class 'nlFit'
plot(x, which = 1:4,
    plotTitles = paste(c("Histogram of ","Log-Histogram of ",
                         "Q-Q Plot of ","P-P Plot of "), x$obsName,
                       sep = ""),
    ask = prod(par("mfcol")) < length(which) & dev.interactive(), ...)
  ## S3 method for class 'nlFit'
coef(object, ...)
  ## S3 method for class 'nlFit'
vcov(object, ...)

Arguments

Details

startMethod must be "Nelder-Mead".

startValues can only be "MoM" when using the Method of Moments for estimation, or "US" for user-supplied parameters. For details regarding the use of paramStart, startMethod and startValues, see nlFitStart.

Three optimisation methods are available for use:

"BFGS"

Uses the quasi-Newton method "BFGS" as documented in optim.

"L-BFGS-B"

Uses the constrained method "L-BFGS-B" as documented in optim.

"Nelder-Mead"

Uses an implementation of the Nelder and Mead method as documented in optim.

"nlm"

Uses the nlm function in R.

"nlminb"

Uses the nlminb function in R, with constrained parameters.

For details on how to pass control information for optimisation using optim and nlm, see optim and nlm.

When method = "nlm" or method = "nlm" is used, warnings may be produced. However, these do not appear to be problematic.

Value

A list with components:

Author(s)

David Scott d.scott@auckland.ac.nz, Simon Potter

See Also

optim, nlm, par, hist, logHist, qqnl, ppnl, dnl and nlFitStart.

Examples

param <- c(0, 2, 1, 1)
dataVector <- rnl(1000, param = param)

## Let's see how well nlFit works
nlFit(dataVector)
nlFit(dataVector, plots = TRUE)
fit <- nlFit(dataVector)
par(mfrow = c(1, 2))
plot(fit, which = c(1, 3))  # See only histogram and Q-Q plot

Find Starting Values for Fitting a Normal Laplace Distribution

Description

Finds starting values for input to a maximum likelihood routine for fitting a normal Laplace distribution to data.

Usage

  nlFitStart(x, breaks = "FD",
             paramStart = NULL,
             startValues = c("MoM", "US"),
             startMethodMoM = "Nelder-Mead", ...)
  nlFitStartMoM(x, startMethodMoM = "Nelder-Mead", ...)

Arguments

Details

Possible values of the argument startValues are the following:

"US"

User-supplied.

"MoM"

Method of moments.

If startValues = "US" then a value must be supplied for paramStart.

If startValues = "MoM", nlFitStartMoM is called.

If startValues = "MoM" an initial optimisation is needed to find the starting values. These optimisations call optim.

Value

nlFitStart returns a list with components:

nlFitStartMoM returns only the method of moments estimates as a vector with elements mu, sigma, alpha and beta.

Author(s)

David Scott d.scott@auckland.ac.nz, Simon Potter

See Also

dnl, nlFit, hist, and optim.

Examples

param <- c(2, 2, 1, 1)
dataVector <- rnl(500, param = param)
nlFitStart(dataVector, startValues = "MoM")

Normal Laplace Quantile-Quantile and Percent-Percent Plots

Description

qqnl produces a normal Laplace Q-Q plot of the values in y.

ppnl produces a normal Laplace P-P (percent-percent) or probability plot of the values in y.

Graphical parameters may be given as arguments to qqnl, and ppnl.

Usage

qqnl(y, mu = 0, sigma = 1, alpha = 1, beta = 1,
     param = c(mu, sigma, alpha, beta),
     main = "Normal Laplace Q-Q Plot",
     xlab = "Theoretical Quantiles",
     ylab = "Sample Quantiles",
     plot.it = TRUE, line = TRUE, ...)
ppnl(y, mu = 0, sigma = 1, alpha = 1, beta = 1,
     param = c(mu, sigma, alpha, beta),
     main = "Normal Laplace P-P Plot",
     xlab = "Uniform Quantiles",
     ylab = "Probability-integral-transformed Data",
     plot.it = TRUE, line = TRUE, ...)

Arguments

Value

For qqnl and ppnl, a list with components:

References

Wilk, M. B. and Gnanadesikan, R. (1968) Probability plotting methods for the analysis of data. Biometrika. 55, 1–17.

See Also

ppoints, dnl, nlFit

Examples

par(mfrow = c(1, 2))
param <- c(2, 2, 1, 1)
y <- rnl(200, param = param)
qqnl(y, param = param, line = FALSE)
abline(0, 1, col = 2)
ppnl(y, param = param)

Summarizing Normal Laplace Distribution Fit

Description

summary Method for class "nlFit".

Usage

  ## S3 method for class 'nlFit'
summary(object, ...)
  ## S3 method for class 'summary.nlFit'
print(x,
        digits = max(3, getOption("digits") - 3), ...)

Arguments

Details

summary.nlFit calculates standard errors for the estimates of \mu, \sigma, \alpha, and \beta of the normal laplace distribution parameter vector param if the Hessian from the call to nlFit is available.

Value

If the Hessian is available, summary.nlFit computes standard errors for the estimates of \mu, \sigma, \alpha, and \beta, and adds them to object as object$sds. Otherwise, no calculations are performed and the composition of object is unaltered.

summary.nlFit invisibly returns object with class changed to summary.nlFit.

See nlFit for the composition of an object of class nlFit.

print.summary.nlFit prints a summary in the same format as print.nlFit when the Hessian is not available from the fit. When the Hessian is available, the standard errors for the parameter estimates are printed in parentheses beneath the parameter estimates, in the manner of fitdistr in the package MASS.

See Also

nlFit, summary.

Examples

## Continuing the  nlFit() example:
param <- c(2, 2, 1, 1)
dataVector <- rnl(500, param = param)
fit <- nlFit(dataVector, hessian = TRUE)
print(fit)
summary(fit)