nieve (version 0.1.3)

GPD2: Density, Distribution Function, Quantile Function and Random Generation for the Two-Parameter Generalized Pareto Distribution (GPD)

Description

Density, distribution function, quantile function and random generation for the two-parameter Generalized Pareto Distribution (GPD) distribution with scale and shape.

Usage

dGPD2(x, scale = 1, shape = 0, log = FALSE, deriv = FALSE, hessian = FALSE)
pGPD2(
  q,
  scale = 1,
  shape = 0,
  lower.tail = TRUE,
  deriv = FALSE,
  hessian = FALSE
)
qGPD2(
  p,
  scale = 1,
  shape = 0,
  lower.tail = TRUE,
  deriv = FALSE,
  hessian = FALSE
)
rGPD2(n, scale = 1, shape = 0, array)

Value

A numeric vector with length equal to the maximum of the four lengths: that of the first argument and that of the two parameters scale and shape. When deriv is TRUE, the returned value has an attribute named "gradient" which is a matrix with \(n\) lines and \(2\)

columns containing the derivatives. A row contains the partial derivatives of the corresponding element w.r.t. the two parameters "scale" and "shape" in that order.

Arguments

x, q

Vector of quantiles.

scale

Scale parameter. Numeric vector with suitable length, see Details.

shape

Shape parameter. Numeric vector with suitable length, see Details.

log

Logical; if TRUE, densities p are returned as log(p).

deriv

Logical. If TRUE, the gradient of each computed value w.r.t. the parameter vector is computed, and returned as a "gradient" attribute of the result. This is a numeric array with dimension c(n, 2) where n is the length of the first argument, i.e. x, p or q, depending on the function.

hessian

Logical. If TRUE, the Hessian of each computed value w.r.t. the parameter vector is computed, and returned as a "hessian" attribute of the result. This is a numeric array with dimension c(n, 2, 2) where n is the length of the first argument, i.e. x, p or depending on the function.

lower.tail

Logical; if TRUE (default), probabilities are \(\textrm{Pr}[X \leq x]\), otherwise, \(\textrm{Pr}[X > x]\).

p

Vector of probabilities.

n

Sample size.

array

Logical. If TRUE, the simulated values form a numeric matrix with n columns and np rows where np is the number of GPD parameter values. This number is obtained by recycling the two GPD parameters vectors to a common length, so np is the maximum of the lengths of the parameter vectors scale and shape. This option is useful to cope with so-called non-stationary models with GPD margins. See Examples. The default value is TRUE if any of the vectors scale and shape has length > 1 and FALSE otherwise.

Details

Let \(\sigma >0\) and \(\xi\) denote the scale and the shape; the survival function \(S(x) := \textrm{Pr}[X > x]\) is given for \(x \geq 0\) by $$S(x) = \left[1 + \xi x/ \sigma \right]_+^{-1/\xi}$$ for \(\xi \neq 0\) where \(v_+ := \max\{v, \, 0\}\) and by $$S(x) = \exp\{-x/\sigma\}$$ for \(\xi = 0\). For \(x < 0\) we have \(S(x) = 1\): the support of the distribution is \((0,\,\infty(\).

The probability functions d, p and q all allow each of the two GP parameters to be a vector. Then the recycling rule is used to get three vectors of the same length, corresponding to the first argument and to the two GP parameters. This behaviour is the standard one for the probability functions of the stats. Note that the provided functions can be used e.g. to evaluate the quantile with a given probability for a large number of values of the parameter vector c(shape, scale). This is frequently required in he Bayesian framework with MCMC inference.

Examples

## Illustrate the effect of recycling rule.
pGPD2(1.0, scale = 1:4, shape = 0.0, lower.tail = FALSE) - exp(-1.0 / (1:4))
pGPD2(1:4, scale = 1:4, shape = 0.0, lower.tail = FALSE) - exp(-1.0)

## With gradient and Hessian.
pGPD2(c(1.1, 1.7), scale = 1, shape = 0, deriv = TRUE, hessian = TRUE)

## simulate 40 paths
ti <- 1:20
names(ti) <- 2000 + ti
y <- rGPD2(n = 40, scale = ti, shape = 0.05)
matplot(ti, y, type = "l", col = "gray", main = "varying scale")
lines(ti, apply(y, 1, mean))