NAG Toolbox: nag_tsa_uni_garch_asym1_estim (g13fa)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{dist}$ – string (length ≥ 1)

The type of distribution to use for $e_t$.

$\mathbf{dist}=\text{'N'}$

A Normal distribution is used.

$\mathbf{dist}=\text{'T'}$

A Student's $t$-distribution is used.

Constraint: $\mathbf{dist}=\text{'N'}$ or $\text{'T'}$.

2:     $\mathrm{yt}\left(\mathbf{num}\right)$ – double array

The sequence of observations, $y_{\mathit{t}}$, for $\mathit{t}=1,2,\dots ,T$.

3:     $\mathrm{x}\left(\mathit{ldx},:\right)$ – double array

The first dimension of the array x must be at least $\mathbf{num}$.

The second dimension of the array x must be at least $\mathbf{nreg}$.

Row $\mathit{t}$ of x must contain the time dependent exogenous vector $x_{\mathit{t}}$, where $x_{\mathit{t}}^{\mathrm{T}}=\left(x_{\mathit{t}}^1,\dots ,x_{\mathit{t}}^k\right)$, for $\mathit{t}=1,2,\dots ,T$.

4:     $\mathrm{ip}$ – int64int32nag_int scalar

The number of coefficients, ${\beta }_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,p$.

Constraint: $\mathbf{ip}\ge 0$ (see also npar).

5:     $\mathrm{iq}$ – int64int32nag_int scalar

The number of coefficients, ${\alpha }_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,q$.

Constraint: $\mathbf{iq}\ge 1$ (see also npar).

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

$k$, the number of regression coefficients.

Constraint: $\mathbf{nreg}\ge 0$ (see also npar).

7:     $\mathrm{mn}$ – int64int32nag_int scalar

If $\mathbf{mn}=1$, the mean term $b_0$ will be included in the model.

Constraint: $\mathbf{mn}=0$ or $1$.

8:     $\mathrm{isym}$ – int64int32nag_int scalar

If $\mathbf{isym}=1$, the asymmetry term $\gamma$ will be included in the model.

Constraint: $\mathbf{isym}=0$ or $1$.

9:     $\mathrm{theta}\left(\mathbf{npar}\right)$ – double array

The initial parameter estimates for the vector $\theta$.

The first element must contain the coefficient ${\alpha }_o$ and the next iq elements must contain the coefficients ${\alpha }_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,q$.

The next ip elements must contain the coefficients ${\beta }_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,p$.

If $\mathbf{isym}=1$, the next element must contain the asymmetry parameter $\gamma$.

If $\mathbf{dist}=\text{'T'}$, the next element must contain $\mathit{df}$, the number of degrees of freedom of the Student's $t$-distribution.

If $\mathbf{mn}=1$, the next element must contain the mean term $b_o$.

If $\mathbf{copts}\left(2\right)=\mathit{false}$, the remaining nreg elements are taken as initial estimates of the linear regression coefficients $b_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,k$.

10:   $\mathrm{hp}$ – double scalar

If $\mathbf{copts}\left(2\right)=\mathit{false}$, hp is the value to be used for the pre-observed conditional variance; otherwise hp is not referenced.

11:   $\mathrm{copts}\left(2\right)$ – logical array

The options to be used by nag_tsa_uni_garch_asym1_estim (g13fa).

$\mathbf{copts}\left(1\right)=\mathit{true}$

Stationary conditions are enforced, otherwise they are not.

$\mathbf{copts}\left(2\right)=\mathit{true}$

The function provides initial parameter estimates of the regression terms, otherwise these are to be provided by you.

12:   $\mathrm{maxit}$ – int64int32nag_int scalar

The maximum number of iterations to be used by the optimization function when estimating the $\text{GARCH}\left(p,q\right)$ parameters. If maxit is set to $0$, the standard errors, score vector and variance-covariance are calculated for the input value of $\theta$ in theta when $\mathbf{dist}=\text{'N'}$; however the value of $\theta$ is not updated.

Constraint: $\mathbf{maxit}\ge 0$.

13:   $\mathrm{tol}$ – double scalar

The tolerance to be used by the optimization function when estimating the $\text{GARCH}\left(p,q\right)$ parameters.

Optional Input Parameters

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

Default: the dimension of the array yt and the first dimension of the array x. (An error is raised if these dimensions are not equal.)

$T$, the number of terms in the sequence.

Constraints:

• $\mathbf{num}\ge \max \left(\mathbf{ip},\mathbf{iq}\right)$;
• $\mathbf{num}\ge \mathbf{nreg}+\mathbf{mn}$.

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

Default: the dimension of the array theta.

The number of parameters to be included in the model. $\mathbf{npar}=1+\mathbf{iq}+\mathbf{ip}+\mathbf{isym}+\mathbf{mn}+\mathbf{nreg}$ when $\mathbf{dist}=\text{'N'}$, and $\mathbf{npar}=2+\mathbf{iq}+\mathbf{ip}+\mathbf{isym}+\mathbf{mn}+\mathbf{nreg}$ when $\mathbf{dist}=\text{'T'}$.

Constraint: $\mathbf{npar}<20$.

Output Parameters

1:     $\mathrm{theta}\left(\mathbf{npar}\right)$ – double array

The estimated values $\hat{\theta }$ for the vector $\theta$.

The first element contains the coefficient ${\alpha }_o$, the next iq elements contain the coefficients ${\alpha }_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,q$.

The next ip elements are the coefficients ${\beta }_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,p$.

If $\mathbf{isym}=1$, the next element contains the estimate for the asymmetry parameter $\gamma$.

If $\mathbf{dist}=\text{'T'}$, the next element contains an estimate for $\mathit{df}$, the number of degrees of freedom of the Student's $t$-distribution.

If $\mathbf{mn}=1$, the next element contains an estimate for the mean term $b_o$.

The final nreg elements are the estimated linear regression coefficients $b_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,k$.

2:     $\mathrm{se}\left(\mathbf{npar}\right)$ – double array

The standard errors for $\hat{\theta }$.

The first element contains the standard error for ${\alpha }_o$. The next iq elements contain the standard errors for ${\alpha }_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,q$. The next ip elements are the standard errors for ${\beta }_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,p$.

If $\mathbf{isym}=1$, the next element contains the standard error for $\gamma$.

If $\mathbf{dist}=\text{'T'}$, the next element contains the standard error for $\mathit{df}$, the number of degrees of freedom of the Student's $t$-distribution.

If $\mathbf{mn}=1$, the next element contains the standard error for $b_o$.

The final nreg elements are the standard errors for $b_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,k$.

3:     $\mathrm{sc}\left(\mathbf{npar}\right)$ – double array

The scores for $\hat{\theta }$.

The first element contains the score for ${\alpha }_o$.

The next iq elements contain the score for ${\alpha }_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,q$.

The next ip elements are the scores for ${\beta }_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,p$.

If $\mathbf{isym}=1$, the next element contains the score for $\gamma$.

If $\mathbf{dist}=\text{'T'}$, the next element contains the score for $\mathit{df}$, the number of degrees of freedom of the Student's $t$-distribution.

If $\mathbf{mn}=1$, the next element contains the score for $b_o$.

The final nreg elements are the scores for $b_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,k$.

4:     $\mathrm{covr}\left(\mathit{ldcovr},\mathbf{npar}\right)$ – double array

The covariance matrix of the parameter estimates $\hat{\theta }$, that is the inverse of the Fisher Information Matrix.

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

If $\mathbf{copts}\left(2\right)=\mathit{true}$, hp is the estimated value of the pre-observed conditional variance.

6:     $\mathrm{et}\left(\mathbf{num}\right)$ – double array

The estimated residuals, ${\epsilon }_{\mathit{t}}$, for $\mathit{t}=1,2,\dots ,T$.

7:     $\mathrm{ht}\left(\mathbf{num}\right)$ – double array

The estimated conditional variances, $h_{\mathit{t}}$, for $\mathit{t}=1,2,\dots ,T$.

8:     $\mathrm{lgf}$ – double scalar

The value of the log-likelihood function at $\hat{\theta }$.

9:     $\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$

On entry,	$\mathbf{nreg}<0$,
or	$\mathbf{mn}>1$,
or	$\mathbf{mn}<0$,
or	$\mathbf{isym}>1$,
or	$\mathbf{isym}<0$,
or	$\mathbf{iq}<1$,
or	$\mathbf{ip}<0$,
or	$\mathbf{npar}\ge 20$,
or	npar has an invalid value,
or	$\mathit{ldcovr}<\mathbf{npar}$,
or	$\mathit{ldx}<\mathbf{num}$,
or	$\mathbf{dist}\ne \text{'N'}$,
or	$\mathbf{dist}\ne \text{'T'}$,
or	$\mathbf{maxit}<0$,
or	$\mathbf{num}<\max \left(\mathbf{ip},\mathbf{iq}\right)$,
or	$\mathbf{num}<\mathbf{nreg}+\mathbf{mn}$.

   $\mathbf{ifail}=2$

On entry,

$\mathit{lwork}<\left(\mathbf{nreg}+3\right)\times \mathbf{num}+\mathbf{npar}+403$.

   $\mathbf{ifail}=3$

The matrix $X$ is not full rank.

   $\mathbf{ifail}=4$

The information matrix is not positive definite.

   $\mathbf{ifail}=5$

The maximum number of iterations has been reached.

W  $\mathbf{ifail}=6$

The log-likelihood cannot be optimized any further.

   $\mathbf{ifail}=7$

No feasible model parameters could be found.

   $\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: g13fa_example

function g13fa_example


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

num  = 100;

% Series
yt = [ 9.04;  9.49;  9.12;  9.23;  9.35;
       9.09;  9.75;  9.23;  8.76;  9.17;
       9.20;  9.64;  8.74;  9.23;  9.42;
       9.70;  9.55; 10.00;  9.18;  9.77;
       9.80;  9.56;  9.28;  9.68;  9.51;
       9.51;  8.97;  9.30;  9.52;  9.41;
       9.53;  9.75;  9.72;  9.38;  9.28;
       9.42;  9.74;  9.75;  9.60;  9.90;
       9.06;  9.92;  9.21;  9.57;  9.42;
       8.65;  8.85;  9.61; 10.77; 10.19;
      10.47; 10.10; 10.21;  9.96;  9.66;
       9.79; 10.30;  9.68; 10.08; 10.38;
       9.69;  9.02;  9.89; 10.46; 10.47;
       9.99;  9.76;  9.78;  9.62; 10.43;
      10.42;  9.95;  9.95;  9.70; 10.24;
       9.78;  9.98;  8.73; 10.23;  9.10;
      10.27;  9.85; 10.44; 10.30; 10.08;
      10.20; 10.14;  9.89;  9.90; 11.33;
       9.71;  9.40;  9.97; 10.92;  9.76;
      10.16; 10.43;  9.60; 10.29; 10.03];

% Exogenous variables
x = [0.12, 2.40; 0.12, 2.40; 0.13, 2.40; 0.14, 2.40; 0.14, 2.40;
     0.15, 2.40; 0.16, 2.40; 0.16, 2.40; 0.17, 2.40; 0.18, 2.41;
     0.19, 2.41; 0.19, 2.41; 0.20, 2.41; 0.21, 2.41; 0.21, 2.41;
     0.22, 2.41; 0.23, 2.41; 0.23, 2.41; 0.24, 2.41; 0.25, 2.42;
     0.25, 2.42; 0.26, 2.42; 0.26, 2.42; 0.27, 2.42; 0.28, 2.42;
     0.28, 2.42; 0.29, 2.42; 0.30, 2.42; 0.30, 2.42; 0.31, 2.43;
     0.32, 2.43; 0.32, 2.43; 0.33, 2.43; 0.33, 2.43; 0.34, 2.43;
     0.35, 2.43; 0.35, 2.43; 0.36, 2.43; 0.37, 2.43; 0.37, 2.44;
     0.38, 2.44; 0.38, 2.44; 0.39, 2.44; 0.39, 2.44; 0.40, 2.44;
     0.41, 2.44; 0.41, 2.44; 0.42, 2.44; 0.42, 2.44; 0.43, 2.45;
     0.43, 2.45; 0.44, 2.45; 0.45, 2.45; 0.45, 2.45; 0.46, 2.45;
     0.46, 2.45; 0.47, 2.45; 0.47, 2.45; 0.48, 2.45; 0.48, 2.46;
     0.49, 2.46; 0.49, 2.46; 0.50, 2.46; 0.50, 2.46; 0.51, 2.46;
     0.51, 2.46; 0.52, 2.46; 0.52, 2.46; 0.53, 2.46; 0.53, 2.47;
     0.54, 2.47; 0.54, 2.47; 0.54, 2.47; 0.55, 2.47; 0.55, 2.47;
     0.56, 2.47; 0.56, 2.47; 0.57, 2.47; 0.57, 2.47; 0.57, 2.48;
     0.58, 2.48; 0.58, 2.48; 0.59, 2.48; 0.59, 2.48; 0.59, 2.48;
     0.60, 2.48; 0.60, 2.48; 0.61, 2.48; 0.61, 2.48; 0.61, 2.49;
     0.62, 2.49; 0.62, 2.49; 0.62, 2.49; 0.63, 2.49; 0.63, 2.49;
     0.63, 2.49; 0.64, 2.49; 0.64, 2.49; 0.64, 2.49; 0.64, 2.50];

% Details of model to fit
dist = 't';
n1 = int64(1);
ip = n1;
iq = n1;
isym = n1;
mn   = n1;
nreg = 2*n1;

% Control parameters
copts = [true; true];
maxit = int64(200);
tol = 0.00001;

% Initial values
gammaval = -0.1;
theta = [0.05; 0.1; 0.15; gammaval; 2.6; 1.5; 0; 0];

% Forecast horizon
nt = 4*n1;

% Fit the GARCH model
[theta, se, sc, covar, hp, et, ht, lgf, ifail] = ...
  g13fa( ...
         dist, yt, x, ip, iq, mn, isym, theta, 0, copts, maxit, tol);

% Calculate the volatility forecast
[fht, ifail] = g13fb( ...
                      nt, ip, iq, theta, gammaval, ht, et);

% Output the results
fprintf('\n               Parameter        Standard\n');
fprintf('               estimates         errors\n');

% Output the coefficient alpha_0
fprintf('Alpha0 %16.2f%16.2f\n', theta(1), se(1));
l = 2;

% Output the coefficients alpha_i
for i = l:l+iq-1
  fprintf('Alpha%d %16.2f%16.2f\n', i-1, theta(i), se(i));
end
l = l+iq;

% Output the coefficients beta_j
fprintf('\n');
for i = l:l+ip-1
  fprintf(' Beta%d %16.2f%16.2f\n', i-l+1, theta(i), se(i));
end
l = l+ip;

% Output the estimated asymmetry parameter, gamma
if (isym == 1)
  fprintf('\n Gamma %16.2f%16.2f\n', theta(l), se(l));
  l = l+1;
end
% Output the estimated degrees of freedom, df
if (dist == 't')
  fprintf('\n    DF %16.2f%16.2f\n', theta(l), se(l));
  l = l + 1;
end

% Output the estimated mean term, b_0
if (mn == 1)
  fprintf('\n    B0 %16.2f%16.2f\n', theta(l), se(l));
  l = l + 1;
end

% Output the estimated linear regression coefficients, b_i
for i = l:l+nreg-1
  fprintf('    B%d %16.2f%16.2f\n', i-l+1, theta(i), se(i));
end

% Display the volatility forecast
fprintf('\nVolatility forecast = %12.4f\n', fht(nt));

g13fa example results


               Parameter        Standard
               estimates         errors
Alpha0             0.00            0.06
Alpha1             0.11            0.13

 Beta1             0.66            0.23

 Gamma            -0.62            0.62

    DF             6.25            4.70

    B0             3.85           24.11
    B1             1.48            1.82
    B2             2.15           10.16

Volatility forecast =       0.0626