NAG Toolbox: nag_univar_estim_genpareto (g07bf)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{y}\left(\mathbf{n}\right)$ – double array

The $n$ observations $y_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$, assumed to follow a generalized Pareto distribution.

Constraints:

• $\mathbf{y}\left(i\right)\ge 0.0$;
• ${\displaystyle \sum _{\mathit{i}=1}^n}\mathbf{y}\left(i\right)>0.0$.

2:     $\mathrm{optopt}$ – int64int32nag_int scalar

Determines the method of estimation, set:

$\mathbf{optopt}=-2$

For the method of probability-weighted moments.

$\mathbf{optopt}=-1$

For the method of moments.

$\mathbf{optopt}=1$

For maximum likelihood with starting values given by the method of moments estimates.

$\mathbf{optopt}=2$

For maximum likelihood with starting values given by the method of probability-weighted moments.

Constraint: $\mathbf{optopt}=-2$, $-1$, $1$ or $2$.

Optional Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

Default: the dimension of the array y.

The number of observations.

Constraint: $\mathbf{n}>1$.

Output Parameters

1:     $\mathrm{xi}$ – double scalar

The parameter estimate $\hat{\xi }$.

2:     $\mathrm{beta}$ – double scalar

The parameter estimate $\hat{\beta }$.

3:     $\mathrm{asvc}\left(4\right)$ – double array

The variance-covariance of the asymptotic Normal distribution of $\hat{\xi }$ and $\hat{\beta }$. $\mathbf{asvc}\left(1\right)$ contains the variance of $\hat{\xi }$; $\mathbf{asvc}\left(4\right)$ contains the variance of $\hat{\beta }$; $\mathbf{asvc}\left(2\right)$ and $\mathbf{asvc}\left(3\right)$ contain the covariance of $\hat{\xi }$ and $\hat{\beta }$.

4:     $\mathrm{obsvc}\left(4\right)$ – double array

If maximum likelihood estimates are requested, the observed variance-covariance of $\hat{\xi }$ and $\hat{\beta }$. $\mathbf{obsvc}\left(1\right)$ contains the variance of $\hat{\xi }$; $\mathbf{obsvc}\left(4\right)$ contains the variance of $\hat{\beta }$; $\mathbf{obsvc}\left(2\right)$ and $\mathbf{obsvc}\left(3\right)$ contain the covariance of $\hat{\xi }$ and $\hat{\beta }$.

5:     $\mathrm{ll}$ – double scalar

If maximum likelihood estimates are requested, ll contains the log-likelihood value $L$ at the end of the optimization; otherwise ll is set to $-1.0$.

6:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

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

   $\mathbf{ifail}=1$

Constraint: $\mathbf{n}>1$.

   $\mathbf{ifail}=2$

Constraint: $\mathbf{y}\left(i\right)\ge 0.0$ for all $i$.

   $\mathbf{ifail}=3$

Constraint: $\mathbf{optopt}=-2$, $-1$, $1$ or $2$.

W  $\mathbf{ifail}=6$

The asymptotic distribution is not available for the returned parameter estimates.

W  $\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  $\mathbf{ifail}=8$

The asymptotic distribution of parameter estimates is invalid and the distribution of maximum likelihood estimates cannot be calculated for the returned parameter estimates because the Hessian matrix could not be inverted.

   $\mathbf{ifail}=9$

The optimization of log-likelihood failed to converge; no maximum likelihood estimates are returned. Try using the other maximum likelihood option by resetting optopt. If this also fails, moments-based estimates can be returned by an appropriate setting of optopt.

   $\mathbf{ifail}=10$

Variance of data in y is too low for method of moments optimization.

   $\mathbf{ifail}=11$

The sum of y is zero within machine precision.

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: g07bf_example

function g07bf_example


fprintf('g07bf example results\n\n');

optopt = int64(2);

% Catch warnings for ifail=6,7,8
warn_state = nag_issue_warnings();
nag_issue_warnings(true);
wstat = warning();
warning('OFF');

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('xi             %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(wstat);

nag_issue_warnings(warn_state);

g07bf example results

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