gpd {VGAM} R Documentation

## Generalized Pareto Distribution Family Function

### Description

Maximum likelihood estimation of the 2-parameter generalized Pareto distribution (GPD).

### Usage

```gpd(threshold = 0, lscale = "loge", lshape = logoff(offset = 0.5),
percentiles = c(90, 95), iscale = NULL, ishape = NULL,
tolshape0 = 0.001, giveWarning = TRUE, imethod = 1, zero = -2)
```

### Arguments

 `threshold` Numeric, values are recycled if necessary. The threshold value(s), called mu below. `lscale` Parameter link function for the scale parameter sigma. See `Links` for more choices. `lshape` Parameter link function for the shape parameter xi. See `Links` for more choices. The default constrains the parameter to be greater than -0.5 because if xi <= -0.5 then Fisher scoring does not work. See the Details section below for more information. For the shape parameter, the default `logoff` link has an offset called A below; and then the second linear/additive predictor is log(xi+A) which means that xi > -A. The working weight matrices are positive definite if A = 0.5.
 `percentiles` Numeric vector of percentiles used for the fitted values. Values should be between 0 and 100. See the example below for illustration. However, if `percentiles = NULL` then the mean mu + sigma / (1-xi) is returned; this is only defined if xi<1. `iscale, ishape` Numeric. Optional initial values for sigma and xi. The default is to use `imethod` and compute a value internally for each parameter. Values of `ishape` should be between -0.5 and 1. Values of `iscale` should be positive.
 `tolshape0, giveWarning` Passed into `dgpd` when computing the log-likelihood.
 `imethod` Method of initialization, either 1 or 2. The first is the method of moments, and the second is a variant of this. If neither work, try assigning values to arguments `ishape` and/or `iscale`. `zero` An integer-valued vector specifying which linear/additive predictors are modelled as intercepts only. For one response, the value should be from the set {1,2} corresponding respectively to sigma and xi. It is often a good idea for the sigma parameter only to be modelled through a linear combination of the explanatory variables because the shape parameter is probably best left as an intercept only: `zero = 2`. Setting `zero = NULL` means both parameters are modelled with explanatory variables. See `CommonVGAMffArguments` for more details.

### Details

The distribution function of the GPD can be written

G(y) = 1 - [1 + xi (y-mu)/ sigma ]_{+}^{- 1/ xi}

where mu is the location parameter (known, with value `threshold`), sigma > 0 is the scale parameter, xi is the shape parameter, and h_+ = max(h,0). The function 1-G is known as the survivor function. The limit xi --> 0 gives the shifted exponential as a special case:

G(y) = 1 - exp[-(y-mu)/ sigma].

The support is y>mu for xi>0, and mu < y <mu-sigma / xi for xi<0.

Smith (1985) showed that if xi <= -0.5 then this is known as the nonregular case and problems/difficulties can arise both theoretically and numerically. For the (regular) case xi > -0.5 the classical asymptotic theory of maximum likelihood estimators is applicable; this is the default.

Although for xi < -0.5 the usual asymptotic properties do not apply, the maximum likelihood estimator generally exists and is superefficient for -1 < xi < -0.5, so it is “better” than normal. When xi < -1 the maximum likelihood estimator generally does not exist as it effectively becomes a two parameter problem.

The mean of Y does not exist unless xi < 1, and the variance does not exist unless xi < 0.5. So if you want to fit a model with finite variance use `lshape = "elogit"`.

### Value

An object of class `"vglmff"` (see `vglmff-class`). The object is used by modelling functions such as `vglm` and `vgam`. However, for this VGAM family function, `vglm` is probably preferred over `vgam` when there is smoothing.

### Warning

Fitting the GPD by maximum likelihood estimation can be numerically fraught. If 1 + xi*(y-mu)/sigma <= 0 then some crude evasive action is taken but the estimation process can still fail. This is particularly the case if `vgam` with `s` is used. Then smoothing is best done with `vglm` with regression splines (`bs`