NAG Library Routine Document

G02DDF

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     $\mathrm{N}$ – INTEGERInput

On entry: the number of observations.

Constraint: $\mathbf{N}\ge 1$.

2:     $\mathrm{IP}$ – INTEGERInput

On entry: $p$, the number of terms in the regression model.

Constraint: $\mathbf{IP}\ge 1$.

3:     $\mathrm{Q}\left(\mathbf{LDQ},\mathbf{IP}+1\right)$ – REAL (KIND=nag_wp) arrayInput

On entry: must be the array Q as output by G02DCF, G02DEF, G02DFF or G02EEF. If on entry $\mathbf{RSS}\le 0.0$ then all N elements of $c$ are needed. This is provided by routines G02DEF, G02DFF or G02EEF.

4:     $\mathrm{LDQ}$ – INTEGERInput

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

Constraints:

• if $\mathbf{RSS}\le 0.0$, $\mathbf{LDQ}\ge \mathbf{N}$;
• otherwise $\mathbf{LDQ}\ge \mathbf{IP}$.

5:     $\mathrm{RSS}$ – REAL (KIND=nag_wp)Input/Output

On entry: either the residual sum of squares or a value less than or equal to $0.0$ to indicate that the residual sum of squares is to be calculated by the routine.

On exit: if $\mathbf{RSS}\le 0.0$ on entry, then on exit RSS will contain the residual sum of squares as calculated by G02DDF.

If RSS was positive on entry, it will be unchanged.

6:     $\mathrm{IDF}$ – INTEGEROutput

On exit: the degrees of freedom associated with the residual sum of squares.

7:     $\mathrm{B}\left(\mathbf{IP}\right)$ – REAL (KIND=nag_wp) arrayOutput

On exit: the estimates of the $p$ parameters, $\hat{\beta }$.

8:     $\mathrm{SE}\left(\mathbf{IP}\right)$ – REAL (KIND=nag_wp) arrayOutput

On exit: the standard errors of the $p$ parameters given in B.

9:     $\mathrm{COV}\left(\mathbf{IP}\times \left(\mathbf{IP}+1\right)/2\right)$ – REAL (KIND=nag_wp) arrayOutput

On exit: the upper triangular part of the variance-covariance matrix of the $p$ parameter estimates given in B. They are stored packed by column, i.e., the covariance between the parameter estimate given in $\mathbf{B}\left(i\right)$ and the parameter estimate given in $\mathbf{B}\left(j\right)$, $j\ge i$, is stored in $\mathbf{COV}\left(j\times \left(j-1\right)/2+i\right)$.

10:   $\mathrm{SVD}$ – LOGICALOutput

On exit: if a singular value decomposition has been performed, $\mathbf{SVD}=\mathrm{.TRUE.}$, otherwise $\mathbf{SVD}=\mathrm{.FALSE.}$.

11:   $\mathrm{IRANK}$ – INTEGEROutput

On exit: the rank of the independent variables.

If $\mathbf{SVD}=\mathrm{.FALSE.}$, $\mathbf{IRANK}=\mathbf{IP}$.

If $\mathbf{SVD}=\mathrm{.TRUE.}$, IRANK is an estimate of the rank of the independent variables.

IRANK is calculated as the number of singular values greater than $\mathbf{TOL}\times$ (largest singular value). It is possible for the SVD to be carried out but IRANK to be returned as IP.

12:   $\mathrm{P}\left(\mathbf{IP}\times \mathbf{IP}+2\times \mathbf{IP}\right)$ – REAL (KIND=nag_wp) arrayOutput

On exit: contains details of the singular value decomposition if used.

If $\mathbf{SVD}=\mathrm{.FALSE.}$, P is not referenced.

If $\mathbf{SVD}=\mathrm{.TRUE.}$, the first IP elements of P will not be referenced, the next IP values contain the singular values. The following $\mathbf{IP}\times \mathbf{IP}$ values contain the matrix $P^{*}$ stored by columns.

13:   $\mathrm{TOL}$ – REAL (KIND=nag_wp)Input

On entry: the value of TOL is used to decide if the independent variables are of full rank and, if not, what is the rank of the independent variables. The smaller the value of TOL the stricter the criterion for selecting the singular value decomposition. If $\mathbf{TOL}=0.0$, the singular value decomposition will never be used, this may cause run time errors or inaccuracies if the independent variables are not of full rank.

Suggested value: $\mathbf{TOL}=0.000001$.

Constraint: $\mathbf{TOL}\ge 0.0$.

14:   $\mathrm{WK}\left(\mathbf{IP}\times \mathbf{IP}+\left(\mathbf{IP}-1\right)\times 5\right)$ – REAL (KIND=nag_wp) arrayWorkspace

15:   $\mathrm{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, if you are not familiar with this parameter, the recommended value is $0$. When the value $-\mathbf{1}\text{ or }\mathbf{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{N}<1$,
or	$\mathbf{IP}<1$,
or	$\mathbf{LDQ}<\mathbf{IP}$,
or	$\mathbf{LDQ}<\mathbf{N}$,
or	$\mathbf{TOL}<0.0$.

$\mathbf{IFAIL}=2$

The degrees of freedom for error are less than or equal to $0$. In this case the estimates of $\beta$ are returned but not the standard errors or covariances.

$\mathbf{IFAIL}=3$

The singular value decomposition, if used, has failed to converge, see F02WUF. This is an unlikely error exit.

$\mathbf{IFAIL}=-99$

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

See Section 3.8 in the Essential Introduction for further information.

$\mathbf{IFAIL}=-399$

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

See Section 3.7 in the Essential Introduction for further information.

$\mathbf{IFAIL}=-999$

Dynamic memory allocation failed.

See Section 3.6 in the Essential Introduction for further information.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (g02ddfe.f90)

10.2  Program Data

Program Data (g02ddfe.d)

10.3  Program Results

Program Results (g02ddfe.r)