hide long namesshow long names
hide short namesshow short names
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 nn 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
Estimates ξ̂ξ^ and β̂β^ of the parameters ξξ and ββ are calculated by using one of:
The variances and covariance of the asymptotic Normal distribution of parameter estimates ξ̂ξ^ and β̂β^ are returned if ξ̂ξ^ satisfies:
If the MLE option is exercised, the observed variances and covariance of ξ̂ξ^ and β̂β^ is returned, given by the negative inverse Hessian of LL.

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 > 1n>1.
The nn observations yiyi, for i = 1,2,,ni=1,2,,n, assumed to follow a generalized Pareto distribution.
Constraints:
  • y(i)0.0yi0.0;
  • i = 1n y(i) > 0.0 i=1 n yi>0.0.
2:     optopt – int64int32nag_int scalar
Determines the method of estimation, set:
optopt = -2optopt=-2
For the method of probability-weighted moments.
optopt = -1optopt=-1
For the method of moments.
optopt = 1optopt=1
For maximum likelihood with starting values given by the method of moments estimates.
optopt = 2optopt=2
For maximum likelihood with starting values given by the method of probability-weighted moments.
Constraint: optopt = -2optopt=-2, -1-1, 11 or 22.

Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The dimension of the array y.
The number of observations.
Constraint: n > 1n>1.

Input Parameters Omitted from the MATLAB Interface

None.

Output Parameters

1:     xi – double scalar
The parameter estimate ξ̂ξ^.
2:     beta – double scalar
The parameter estimate β̂β^.
3:     asvc(44) – double array
The variance-covariance of the asymptotic Normal distribution of ξ̂ξ^ and β̂β^. asvc(1)asvc1 contains the variance of ξ̂ξ^; asvc(4)asvc4 contains the variance of β̂β^; asvc(2)asvc2 and asvc(3)asvc3 contain the covariance of ξ̂ξ^ and β̂β^.
4:     obsvc(44) – double array
If maximum likelihood estimates are requested, the observed variance-covariance of ξ̂ξ^ and β̂β^. obsvc(1)obsvc1 contains the variance of ξ̂ξ^; obsvc(4)obsvc4 contains the variance of β̂β^; obsvc(2)obsvc2 and obsvc(3)obsvc3 contain the covariance of ξ̂ξ^ and β̂β^.
5:     ll – double scalar
If maximum likelihood estimates are requested, ll contains the log-likelihood value LL at the end of the optimization; otherwise ll is set to 1.0-1.0.
6:     ifail – int64int32nag_int scalar
ifail = 0ifail=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 = 1ifail=1
Constraint: n > 1n>1.
  ifail = 2ifail=2
On entry, at least one y(i)0.0yi0.0.
  ifail = 3ifail=3
Constraint: optopt = -2optopt=-2, -1-1, 11 or 22.
W ifail = 6ifail=6
The asymptotic distribution is not available for the returned parameter estimates.
W ifail = 7ifail=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 = 8ifail=8
The distribution of maximum likelihood estimates cannot be calculated and the asymptotic distribution is not available for the returned parameter estimates.
  ifail = 9ifail=9
The maximum likelihood optimization failed; try a different starting point by selecting the other maximum likelihood estimation option in parameter optopt.
  ifail = 10ifail=10
Variance of data in y is too low for method of moments optimization.
  ifail = 11ifail=11
The sum of y is zero within machine precision.
  ifail = 999ifail=-999
Dynamic memory allocation failed.

Accuracy

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 LL 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