hyperbFit {GeneralizedHyperbolic}

Fit the Hyperbolic Distribution to Data

Description

Fits a hyperbolic 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

  hyperbFit(x, freq = NULL, paramStart = NULL,
            startMethod = c("Nelder-Mead","BFGS"),
            startValues = c("BN","US","FN","SL","MoM"),
            criterion = "MLE",
            method = c("Nelder-Mead","BFGS","nlm",
                       "L-BFGS-B","nlminb","constrOptim"),
            plots = FALSE, printOut = FALSE,
            controlBFGS = list(maxit = 200),
            controlNM = list(maxit = 1000), maxitNLM = 1500,
            controlLBFGSB = list(maxit = 200),
            controlNLMINB = list(),
            controlCO = list(), ...)

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

  ## S3 method for class 'hyperbFit'
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 'hyperbFit'
coef(object, ...)

  ## S3 method for class 'hyperbFit'
vcov(object, ...)

Arguments

x

Data vector for hyperbFit. Object of class "hyperbFit" for print.hyperbFit and plot.hyperbFit.

freq

A vector of weights with length equal to length(x).

paramStart

A user specified starting parameter vector param taking the form c(mu, delta, alpha, beta).

startMethod

Method used by hyperbFitStart in calls to optim.

startValues

Code giving the method of determining starting values for finding the maximum likelihood estimate of param.

criterion

Currently only "MLE" is implemented.

method

Different optimisation methods to consider. See Details.

plots

Logical. If FALSE suppresses printing of the histogram, log-histogram, Q-Q plot and P-P plot.

printOut

Logical. If FALSE suppresses printing of results of fitting.

controlBFGS

A list of control parameters for optim when using the "BFGS" optimisation.

controlNM

A list of control parameters for optim when using the "Nelder-Mead" optimisation.

maxitNLM

A positive integer specifying the maximum number of iterations when using the "nlm" optimisation.

controlLBFGSB

A list of control parameters for optim when using the "L-BFGS-B" optimisation.

controlNLMINB

A list of control parameters for nlminb when using the "nlminb" optimisation.

controlCO

A list of control parameters for constrOptim when using the "constrOptim" optimisation.

digits

Desired number of digits when the object is printed.

which

If a subset of the plots is required, specify a subset of the numbers 1:4.

plotTitles

Titles to appear above the plots.

ask

Logical. If TRUE, the user is asked before each plot, see par(ask = .).

...

Passes arguments to par, hist, logHist, qqhyperb and pphyperb.

object

Object of class "hyperbFit" for coef.hyperbFit and for vcov.hyperbFit.

Details

startMethod can be either "BFGS" or "Nelder-Mead".

startValues can be one of the following:

"US"

User-supplied.

"BN"

Based on Barndorff-Nielsen (1977).

"FN"

A fitted normal distribution.

"SL"

Based on a fitted skew-Laplace distribution.

"MoM"

Method of moments.

For the details concerning the use of paramStart, startMethod, and startValues, see hyperbFitStart.

The six optimisation methods currently available are:

"BFGS"

Uses the quasi-Newton method "BFGS" 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.

"L-BFGS-B"

Uses the quasi-Newton method with box constraints "L-BFGS-B" as documented in optim.

"nlminb"

Uses the nlminb function in R.

"constrOptim"

Uses the constrOptim function in R.

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

When method = "nlm" is used, warnings may be produced. These do not appear to be a problem.

Value

hyperbFit returns a list with components:

param

A vector giving the maximum likelihood estimate of param, as c(mu, delta, alpha, beta).

maxLik

The value of the maximised log-likelihood.

method

Optimisation method used.

conv

Convergence code. See the relevant documentation (either optim or nlm) for details on convergence.

iter

Number of iterations of optimisation routine.

obs

The data used to fit the hyperbolic distribution.

obsName

A character string with the actual x argument name.

paramStart

Starting value of param returned by call to hyperbFitStart.

svName

Descriptive name for the method finding start values.

startValues

Acronym for the method of finding start values.

breaks

The cell boundaries found by a call to hist.

midpoints

The cell midpoints found by a call to hist.

empDens

The estimated density found by a call to hist.

Author(s)

David Scott [e-mail], Ai-Wei Lee, Jennifer Tso, Richard Trendall, Thomas Tran, Christine Yang Dong

References

Barndorff-Nielsen, O. (1977) Exponentially decreasing distributions for the logarithm of particle size, Proc. Roy. Soc. Lond. A353, 401–419.

Fieller, N. J., Flenley, E. C. and Olbricht, W. (1992) Statistics of particle size data. Appl. Statist. 41, 127–146.

See Also

optim, nlm, nlminb, constrOptim, par, hist, logHist (pkg DistributionUtils), qqhyperb, pphyperb, dskewlap and hyperbFitStart.

Examples

param <- c(2, 2, 2, 1)
dataVector <- rhyperb(500, param = param)
## See how well hyperbFit works
hyperbFit(dataVector)
hyperbFit(dataVector, plots = TRUE)
fit <- hyperbFit(dataVector)
par(mfrow = c(1, 2))
plot(fit, which = c(1, 3))

## Use nlm instead of default
hyperbFit(dataVector, method = "nlm")