NAG Library Routine Document

G13FAF

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     DIST – CHARACTER(1)Input

On entry: 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:     YT(NUM) – REAL (KIND=nag_wp) arrayInput

On entry: the sequence of observations, $y_{\mathit{t}}$, for $\mathit{t}=1,2,\dots ,T$.

3:     X(LDX,$*$) – REAL (KIND=nag_wp) arrayInput

Note: the second dimension of the array X must be at least $\mathbf{NREG}$.

On entry: 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:     LDX – INTEGERInput

On entry: the first dimension of the array X as declared in the (sub)program from which G13FAF is called.

Constraint: $\mathbf{LDX}\ge \mathbf{NUM}$.

5:     NUM – INTEGERInput

On entry: $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}$.

6:     IP – INTEGERInput

On entry: the number of coefficients, ${\beta }_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,p$.

Constraint: $\mathbf{IP}\ge 0$ (see also NPAR).

7:     IQ – INTEGERInput

On entry: the number of coefficients, ${\alpha }_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,q$.

Constraint: $\mathbf{IQ}\ge 1$ (see also NPAR).

8:     NREG – INTEGERInput

On entry: $k$, the number of regression coefficients.

Constraint: $\mathbf{NREG}\ge 0$ (see also NPAR).

9:     MN – INTEGERInput

On entry: if $\mathbf{MN}=1$, the mean term $b_0$ will be included in the model.

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

10:   ISYM – INTEGERInput

On entry: if $\mathbf{ISYM}=1$, the asymmetry term $\gamma$ will be included in the model.

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

11:   NPAR – INTEGERInput

On entry: 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$.

12:   THETA(NPAR) – REAL (KIND=nag_wp) arrayInput/Output

On entry: 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)=\mathrm{.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$.

On exit: 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$.

13:   SE(NPAR) – REAL (KIND=nag_wp) arrayOutput

On exit: 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$.

14:   SC(NPAR) – REAL (KIND=nag_wp) arrayOutput

On exit: 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$.

15:   COVR(LDCOVR,NPAR) – REAL (KIND=nag_wp) arrayOutput

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

16:   LDCOVR – INTEGERInput

On entry: the first dimension of the array COVR as declared in the (sub)program from which G13FAF is called.

Constraint: $\mathbf{LDCOVR}\ge \mathbf{NPAR}$.

17:   HP – REAL (KIND=nag_wp)Input/Output

On entry: if $\mathbf{COPTS}\left(2\right)=\mathrm{.FALSE.}$, HP is the value to be used for the pre-observed conditional variance; otherwise HP is not referenced.

On exit: if $\mathbf{COPTS}\left(2\right)=\mathrm{.TRUE.}$, HP is the estimated value of the pre-observed conditional variance.

18:   ET(NUM) – REAL (KIND=nag_wp) arrayOutput

On exit: the estimated residuals, ${\epsilon }_{\mathit{t}}$, for $\mathit{t}=1,2,\dots ,T$.

19:   HT(NUM) – REAL (KIND=nag_wp) arrayOutput

On exit: the estimated conditional variances, $h_{\mathit{t}}$, for $\mathit{t}=1,2,\dots ,T$.

20:   LGF – REAL (KIND=nag_wp)Output

On exit: the value of the log-likelihood function at $\hat{\theta }$.

21:   COPTS($2$) – LOGICAL arrayInput

On entry: the options to be used by G13FAF.

$\mathbf{COPTS}\left(1\right)=\mathrm{.TRUE.}$

Stationary conditions are enforced, otherwise they are not.

$\mathbf{COPTS}\left(2\right)=\mathrm{.TRUE.}$

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

22:   MAXIT – INTEGERInput

On entry: the maximum number of iterations to be used by the optimization routine 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; however the value of $\theta$ is not updated.

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

23:   TOL – REAL (KIND=nag_wp)Input

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

24:   WORK(LWORK) – REAL (KIND=nag_wp) arrayWorkspace

25:   LWORK – INTEGERInput

On entry: the dimension of the array WORK as declared in the (sub)program from which G13FAF is called.

Constraint: $\mathbf{LWORK}\ge \left(\mathbf{NREG}+3\right)\times \mathbf{NUM}+\mathbf{NPAR}+403$.

26:   IFAIL – INTEGERInput/Output

On entry: IFAIL must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, because for this routine the values of the output parameters may be useful even if $\mathbf{IFAIL}\ne \mathbf{0}$ on exit, the recommended value is $-1$. When the value $-\mathbf{1}\text{ or }1$ is used it is essential to test the value of IFAIL on exit.

On exit: $\mathbf{IFAIL}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6  Error Indicators and 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	$\mathbf{LDCOVR}<\mathbf{NPAR}$,
or	$\mathbf{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,

$\mathbf{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.

$\mathbf{IFAIL}=6$

The log-likelihood cannot be optimized any further.

$\mathbf{IFAIL}=7$

No feasible model parameters could be found.

7  Accuracy

8  Further Comments

9  Example

9.1  Program Text

Program Text (g13fafe.f90)

9.2  Program Data

Program Data (g13fafe.d)

9.3  Program Results

Program Results (g13fafe.r)