Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_univar_estim_genpareto (g07bf)

## Purpose

nag_univar_estim_genpareto (g07bf) estimates parameter values for the generalized Pareto distribution by using either moments or maximum likelihood.

## Syntax

[xi, beta, asvc, obsvc, ll, ifail] = g07bf(y, optopt, 'n', n)
[xi, beta, asvc, obsvc, ll, ifail] = nag_univar_estim_genpareto(y, optopt, 'n', n)

## Description

Let the distribution function of a set of n$n$ observations
 yi ,   i = 1,2, … ,n $yi , i=1,2,…,n$
be given by the generalized Pareto distribution:
F(y) =
 { 1 − (1 + (ξy)/β) − 1 / ξ , ξ ≠ 0 1 − e − y/β , ξ = 0;
$F(y) = { 1- ( 1+ ξy β ) -1/ξ , ξ≠0 1-e-yβ , ξ=0;$
where
• β > 0$\beta >0$ and
• y0$y\ge 0$, when ξ0$\xi \ge 0$;
• 0yβ/ξ$0\le y\le -\frac{\beta }{\xi }$, when ξ < 0$\xi <0$.
Estimates ξ̂$\stackrel{^}{\xi }$ and β̂$\stackrel{^}{\beta }$ of the parameters ξ$\xi$ and β$\beta$ are calculated by using one of:
• method of moments (MOM);
• probability-weighted moments (PWM);
• maximum likelihood estimates (MLE) that seek to maximise the log-likelihood:
 n L = − nln β̂ − (1 + 1/(ξ̂)) ∑ ln(1 + ( ξ̂yi )/(β̂)) . i = 1
$L = -n ln⁡ β^ - ( 1+ 1ξ^ ) ∑ i=1 n ln( 1+ ξ^yi β^ ) .$
The variances and covariance of the asymptotic Normal distribution of parameter estimates ξ̂$\stackrel{^}{\xi }$ and β̂$\stackrel{^}{\beta }$ are returned if ξ̂$\stackrel{^}{\xi }$ satisfies:
• ξ̂ < (1/4)$\stackrel{^}{\xi }<\frac{1}{4}$ for the MOM;
• ξ̂ < (1/2)$\stackrel{^}{\xi }<\frac{1}{2}$ for the PWM method;
• ξ̂ < (1/2)$\stackrel{^}{\xi }<-\frac{1}{2}$ for the MLE method.
If the MLE option is exercised, the observed variances and covariance of ξ̂$\stackrel{^}{\xi }$ and β̂$\stackrel{^}{\beta }$ is returned, given by the negative inverse Hessian of L$L$.

## References

Hosking J R M and Wallis J R (1987) Parameter and quantile estimation for the generalized Pareto distribution Technometrics 29(3)
McNeil A J, Frey R and Embrechts P (2005) Quantitative Risk Management Princeton University Press

## Parameters

### Compulsory Input Parameters

1:     y(n) – double array
n, the dimension of the array, must satisfy the constraint n > 1${\mathbf{n}}>1$.
The n$n$ observations yi${y}_{\mathit{i}}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$, assumed to follow a generalized Pareto distribution.
Constraints:
• y(i)0.0${\mathbf{y}}\left(i\right)\ge 0.0$;
• i = 1n y(i) > 0.0$\sum _{\mathit{i}=1}^{n}{\mathbf{y}}\left(i\right)>0.0$.
2:     optopt – int64int32nag_int scalar
Determines the method of estimation, set:
optopt = -2${\mathbf{optopt}}=-2$
For the method of probability-weighted moments.
optopt = -1${\mathbf{optopt}}=-1$
For the method of moments.
optopt = 1${\mathbf{optopt}}=1$
For maximum likelihood with starting values given by the method of moments estimates.
optopt = 2${\mathbf{optopt}}=2$
For maximum likelihood with starting values given by the method of probability-weighted moments.
Constraint: optopt = -2${\mathbf{optopt}}=-2$, -1$-1$, 1$1$ or 2$2$.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The dimension of the array y.
The number of observations.
Constraint: n > 1${\mathbf{n}}>1$.

None.

### Output Parameters

1:     xi – double scalar
The parameter estimate ξ̂$\stackrel{^}{\xi }$.
2:     beta – double scalar
The parameter estimate β̂$\stackrel{^}{\beta }$.
3:     asvc(4$4$) – double array
The variance-covariance of the asymptotic Normal distribution of ξ̂$\stackrel{^}{\xi }$ and β̂$\stackrel{^}{\beta }$. asvc(1)${\mathbf{asvc}}\left(1\right)$ contains the variance of ξ̂$\stackrel{^}{\xi }$; asvc(4)${\mathbf{asvc}}\left(4\right)$ contains the variance of β̂$\stackrel{^}{\beta }$; asvc(2)${\mathbf{asvc}}\left(2\right)$ and asvc(3)${\mathbf{asvc}}\left(3\right)$ contain the covariance of ξ̂$\stackrel{^}{\xi }$ and β̂$\stackrel{^}{\beta }$.
4:     obsvc(4$4$) – double array
If maximum likelihood estimates are requested, the observed variance-covariance of ξ̂$\stackrel{^}{\xi }$ and β̂$\stackrel{^}{\beta }$. obsvc(1)${\mathbf{obsvc}}\left(1\right)$ contains the variance of ξ̂$\stackrel{^}{\xi }$; obsvc(4)${\mathbf{obsvc}}\left(4\right)$ contains the variance of β̂$\stackrel{^}{\beta }$; obsvc(2)${\mathbf{obsvc}}\left(2\right)$ and obsvc(3)${\mathbf{obsvc}}\left(3\right)$ contain the covariance of ξ̂$\stackrel{^}{\xi }$ and β̂$\stackrel{^}{\beta }$.
5:     ll – double scalar
If maximum likelihood estimates are requested, ll contains the log-likelihood value L$L$ at the end of the optimization; otherwise ll is set to 1.0$-1.0$.
6:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Errors or warnings detected by the function:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

ifail = 1${\mathbf{ifail}}=1$
Constraint: n > 1${\mathbf{n}}>1$.
ifail = 2${\mathbf{ifail}}=2$
On entry, at least one y(i)0.0${\mathbf{y}}\left(i\right)\le 0.0$.
ifail = 3${\mathbf{ifail}}=3$
Constraint: optopt = -2${\mathbf{optopt}}=-2$, -1$-1$, 1$1$ or 2$2$.
W ifail = 6${\mathbf{ifail}}=6$
The asymptotic distribution is not available for the returned parameter estimates.
W ifail = 7${\mathbf{ifail}}=7$
The distribution of maximum likelihood estimates cannot be calculated for the returned parameter estimates because the Hessian matrix could not be inverted.
W ifail = 8${\mathbf{ifail}}=8$
The distribution of maximum likelihood estimates cannot be calculated and the asymptotic distribution is not available for the returned parameter estimates.
ifail = 9${\mathbf{ifail}}=9$
The maximum likelihood optimization failed; try a different starting point by selecting the other maximum likelihood estimation option in parameter optopt.
ifail = 10${\mathbf{ifail}}=10$
Variance of data in y is too low for method of moments optimization.
ifail = 11${\mathbf{ifail}}=11$
The sum of y is zero within machine precision.
ifail = 999${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

Not applicable.

## Further Comments

The search for maximum likelihood parameter estimates is further restricted by requiring
 1 + (ξ̂yi)/(β̂) > 0 , $1+ ξ^yi β^ > 0 ,$
as this avoids the possibility of making the log-likelihood L$L$ arbitrarily high.

## Example

```function nag_univar_estim_genpareto_example
optopt = int64(2);
y = [1.5800; 0.1390; 2.3624; 2.9435; 0.1363; 0.9688; 0.6585; 2.8011; ...
0.9880; 1.7887; 0.0630; 0.3862; 1.5130; 0.0669; 1.3659; 0.4256; ...
0.3485; 27.8760; 5.2503; 1.1028; 0.5273; 1.3189; 0.6490];
% Calculate the GPD parameter estimates
[xi, beta, asvc, obsvc, ll, ifail] = nag_univar_estim_genpareto(y, optopt);

if ifail == 0 || (ifail > 5 && ifail < 9)
% Display parameter estimates
fprintf('\nxi             %14.6f\n', xi);
fprintf('beta           %14.6f\n\n', beta);

% Display Parameter Distributions
if optopt > 0
if (ifail == 7 || ifail == 8)
fprintf('Invalid observed distribution\n');
else
fprintf('Observed distribution\n');
fprintf('Var(xi)        %14.6f\n', obsvc(1));
fprintf('Var(beta)      %14.6f\n', obsvc(4));
fprintf('Covar(xi,beta) %14.6f\n', obsvc(2));
fprintf('Final log-likelihood: %14.6f\n\n', ll);
end
else
if (ifail == 6 || ifail == 7)
fprintf('Invalid asymptotic distribution\n');
else
fprintf('Asymptotic distribution\n');
fprintf('Var(xi)        %14.6f\n', asvc(1));
fprintf('Var(beta)      %14.6f\n', asvc(4));
fprintf('Covar(xi,beta) %14.6f\n', asvc(2));
end
end
end
```
```
Warning: nag_univar_estim_genpareto (g07bf) returned a warning indicator (6)

xi                   0.540439
beta                 1.040549

Observed distribution
Var(xi)              0.079932
Var(beta)            0.119872
Covar(xi,beta)      -0.045509
Final log-likelihood:     -36.344327

```
```function g07bf_example
optopt = int64(2);
y = [1.5800; 0.1390; 2.3624; 2.9435; 0.1363; 0.9688; 0.6585; 2.8011; ...
0.9880; 1.7887; 0.0630; 0.3862; 1.5130; 0.0669; 1.3659; 0.4256; ...
0.3485; 27.8760; 5.2503; 1.1028; 0.5273; 1.3189; 0.6490];
% Calculate the GPD parameter estimates
[xi, beta, asvc, obsvc, ll, ifail] = g07bf(y, optopt);

if ifail == 0 || (ifail > 5 && ifail < 9)
% Display parameter estimates
fprintf('\nxi             %14.6f\n', xi);
fprintf('beta           %14.6f\n\n', beta);

% Display Parameter Distributions
if optopt > 0
if (ifail == 7 || ifail == 8)
fprintf('Invalid observed distribution\n');
else
fprintf('Observed distribution\n');
fprintf('Var(xi)        %14.6f\n', obsvc(1));
fprintf('Var(beta)      %14.6f\n', obsvc(4));
fprintf('Covar(xi,beta) %14.6f\n', obsvc(2));
fprintf('Final log-likelihood: %14.6f\n\n', ll);
end
else
if (ifail == 6 || ifail == 7)
fprintf('Invalid asymptotic distribution\n');
else
fprintf('Asymptotic distribution\n');
fprintf('Var(xi)        %14.6f\n', asvc(1));
fprintf('Var(beta)      %14.6f\n', asvc(4));
fprintf('Covar(xi,beta) %14.6f\n', asvc(2));
end
end
end
```
```
Warning: nag_univar_estim_genpareto (g07bf) returned a warning indicator (6)

xi                   0.540439
beta                 1.040549

Observed distribution
Var(xi)              0.079932
Var(beta)            0.119872
Covar(xi,beta)      -0.045509
Final log-likelihood:     -36.344327

```

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013