NAG Library Routine Document

g02eef (linregm_fit_onestep)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:     $\mathbf{istep}$ – IntegerInput/Output

On entry: indicates which step in the forward selection process is to be carried out.

$\mathbf{istep}=0$

The process is initialized.

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

On exit: is incremented by $1$.

2:     $\mathbf{mean}$ – Character(1)Input

On entry: indicates if a mean term is to be included.

$\mathbf{mean}=\text{'M'}$

A mean term, intercept, will be included in the model.

$\mathbf{mean}=\text{'Z'}$

The model will pass through the origin, zero-point.

Constraint: $\mathbf{mean}=\text{'M'}$ or $\text{'Z'}$.

3:     $\mathbf{weight}$ – Character(1)Input

On entry: indicates if weights are to be used.

$\mathbf{weight}=\text{'U'}$

Least squares estimation is used.

$\mathbf{weight}=\text{'W'}$

Weighted least squares is used and weights must be supplied in array wt.

Constraint: $\mathbf{weight}=\text{'U'}$ or $\text{'W'}$.

4:     $\mathbf{n}$ – IntegerInput

On entry: $n$, the number of observations.

Constraint: $\mathbf{n}\ge 2$.

5:     $\mathbf{m}$ – IntegerInput

On entry: $m$, the total number of independent variables in the dataset.

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

6:     $\mathbf{x}\left(\mathbf{ldx},\mathbf{m}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: $\mathbf{x}\left(\mathit{i},\mathit{j}\right)$ must contain the $\mathit{i}$th observation for the $\mathit{j}$th independent variable, for $\mathit{i}=1,2,\dots ,\mathbf{n}$ and $\mathit{j}=1,2,\dots ,\mathbf{m}$.

7:     $\mathbf{ldx}$ – IntegerInput

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

Constraint: $\mathbf{ldx}\ge \mathbf{n}$.

8:     $\mathbf{vname}\left(\mathbf{m}\right)$ – Character(*) arrayInput

On entry: $\mathbf{vname}\left(\mathit{j}\right)$ must contain the name of the independent variable in column $\mathit{j}$ of x, for $\mathit{j}=1,2,\dots ,\mathbf{m}$.

9:     $\mathbf{isx}\left(\mathbf{m}\right)$ – Integer arrayInput

On entry: indicates which independent variables could be considered for inclusion in the regression.

$\mathbf{isx}\left(j\right)\ge 2$

The variable contained in the $\mathit{j}$th column of x is automatically included in the regression model, for $\mathit{j}=1,2,\dots ,\mathbf{m}$.

$\mathbf{isx}\left(j\right)=1$

The variable contained in the $\mathit{j}$th column of x is considered for inclusion in the regression model, for $\mathit{j}=1,2,\dots ,\mathbf{m}$.

$\mathbf{isx}\left(j\right)=0$

The variable in the $\mathit{j}$th column is not considered for inclusion in the model, for $\mathit{j}=1,2,\dots ,\mathbf{m}$.

Constraint: $\mathbf{isx}\left(\mathit{j}\right)\ge 0$ and at least one value of $\mathbf{isx}\left(\mathit{j}\right)=1$, for $\mathit{j}=1,2,\dots ,\mathbf{m}$.

10:   $\mathbf{maxip}$ – IntegerInput

On entry: the maximum number of independent variables to be included in the model.

Constraints:

• if $\mathbf{mean}=\text{'M'}$, $\mathbf{maxip}\ge 1+$ number of values of $\mathbf{isx}>0$;
• if $\mathbf{mean}=\text{'Z'}$, $\mathbf{maxip}\ge$ number of values of $\mathbf{isx}>0$.

11:   $\mathbf{y}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the dependent variable.

12:   $\mathbf{wt}\left(*\right)$ – Real (Kind=nag_wp) arrayInput

Note: the dimension of the array wt must be at least $\mathbf{n}$ if $\mathbf{weight}=\text{'W'}$.

On entry: if $\mathbf{weight}=\text{'W'}$, wt must contain the weights to be used in the weighted regression, $W$.

If $\mathbf{wt}\left(i\right)=0.0$, the $i$th observation is not included in the model, in which case the effective number of observations is the number of observations with nonzero weights.

If $\mathbf{weight}=\text{'U'}$, wt is not referenced and the effective number of observations is n.

Constraint: if $\mathbf{weight}=\text{'W'}$, $\mathbf{wt}\left(\mathit{i}\right)\ge 0.0$, for $\mathit{i}=1,2,\dots ,\mathbf{n}$.

13:   $\mathbf{fin}$ – Real (Kind=nag_wp)Input

On entry: the critical value of the $F$ statistic for the term to be included in the model, $F_{\mathrm{c}}$.

Suggested value: $2.0$ is a commonly used value in exploratory modelling.

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

14:   $\mathbf{addvar}$ – LogicalOutput

On exit: indicates if a variable has been added to the model.

$\mathbf{addvar}=\mathrm{.TRUE.}$

A variable has been added to the model.

$\mathbf{addvar}=\mathrm{.FALSE.}$

No variable had an $F$ value greater than $F_{\mathrm{c}}$ and none were added to the model.

15:   $\mathbf{newvar}$ – Character(*)Output

On exit: if $\mathbf{addvar}=\mathrm{.TRUE.}$, newvar contains the name of the variable added to the model.

Constraint: the declared size of newvar must be greater than or equal to the declared size of vname.

16:   $\mathbf{chrss}$ – Real (Kind=nag_wp)Output

On exit: if $\mathbf{addvar}=\mathrm{.TRUE.}$, chrss contains the change in the residual sum of squares due to adding variable newvar.

17:   $\mathbf{f}$ – Real (Kind=nag_wp)Output

On exit: if $\mathbf{addvar}=\mathrm{.TRUE.}$, f contains the $F$ statistic for the inclusion of the variable in newvar.

18:   $\mathbf{model}\left(\mathbf{maxip}\right)$ – Character(*) arrayInput/Output

On entry: if $\mathbf{istep}=0$, model need not be set.

If $\mathbf{istep}\ne 0$, model must contain the values returned by the previous call to g02eef.

Constraint: the declared size of model must be greater than or equal to the declared size of vname.

On exit: the names of the variables in the current model.

19:   $\mathbf{nterm}$ – IntegerInput/Output

On entry: if $\mathbf{istep}=0$, nterm need not be set.

If $\mathbf{istep}\ne 0$, nterm must contain the value returned by the previous call to g02eef.

Constraint: if $\mathbf{istep}\ne 0$, $\mathbf{nterm}>0$.

On exit: the number of independent variables in the current model, not including the mean, if any.

20:   $\mathbf{rss}$ – Real (Kind=nag_wp)Input/Output

On entry: if $\mathbf{istep}=0$, rss need not be set.

If $\mathbf{istep}\ne 0$, rss must contain the value returned by the previous call to g02eef.

Constraint: if $\mathbf{istep}\ne 0$, $\mathbf{rss}>0.0$.

On exit: the residual sums of squares for the current model.

21:   $\mathbf{idf}$ – IntegerInput/Output

On entry: if $\mathbf{istep}=0$, idf need not be set.

If $\mathbf{istep}\ne 0$, idf must contain the value returned by the previous call to g02eef.

On exit: the degrees of freedom for the residual sum of squares for the current model.

22:   $\mathbf{ifr}$ – IntegerInput/Output

On entry: if $\mathbf{istep}=0$, ifr need not be set.

If $\mathbf{istep}\ne 0$, ifr must contain the value returned by the previous call to g02eef.

On exit: the number of free independent variables, i.e., the number of variables not in the model that are still being considered for selection.

23:   $\mathbf{free}\left(\mathbf{maxip}\right)$ – Character(*) arrayInput/Output

On entry: if $\mathbf{istep}=0$, free need not be set.

If $\mathbf{istep}\ne 0$, free must contain the values returned by the previous call to g02eef.

Constraint: the declared size of free must be greater than or equal to the declared size of vname.

On exit: the first ifr values of free contain the names of the free variables.

24:   $\mathbf{exss}\left(\mathbf{maxip}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: the first ifr values of exss contain what would be the change in regression sum of squares if the free variables had been added to the model, i.e., the extra sum of squares for the free variables. $\mathbf{exss}\left(i\right)$ contains what would be the change in regression sum of squares if the variable $\mathbf{free}\left(i\right)$ had been added to the model.

25:   $\mathbf{q}\left(\mathbf{ldq},\mathbf{maxip}+2\right)$ – Real (Kind=nag_wp) arrayInput/Output

On entry: if $\mathbf{istep}=0$, q need not be set.

If $\mathbf{istep}\ne 0$, q must contain the values returned by the previous call to g02eef.

On exit: the results of the $QR$ decomposition for the current model:

• the first column of q contains $c=Q^{\mathrm{T}}y$ (or $Q^{\mathrm{T}}{W}^{\frac{1}{2}}y$ where $W$ is the vector of weights if used);
• the upper triangular part of columns $2$ to $p+1$ contain the $R$ matrix;
• the strictly lower triangular part of columns $2$ to $p+1$ contain details of the $Q$ matrix;
• the remaining $p+1$ to $p+\mathbf{ifr}$ columns of contain $Q^{\mathrm{T}}{X}_{\mathit{free}}$ (or $Q^{\mathrm{T}}{W}^{\frac{1}{2}}{X}_{\mathit{free}}$),

where $p=\mathbf{nterm}$, or $p=\mathbf{nterm}+1$ if $\mathbf{mean}=\text{'M'}$.

26:   $\mathbf{ldq}$ – IntegerInput

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

Constraint: $\mathbf{ldq}\ge \mathbf{n}$.

27:   $\mathbf{p}\left(\mathbf{maxip}+1\right)$ – Real (Kind=nag_wp) arrayInput/Output

On entry: if $\mathbf{istep}=0$, p need not be set.

If $\mathbf{istep}\ne 0$, p must contain the values returned by the previous call to g02eef.

On exit: the first $p$ elements of p contain details of the $QR$ decomposition, where $p=\mathbf{nterm}$, or $p=\mathbf{nterm}+1$ if $\mathbf{mean}=\text{'M'}$.

28:   $\mathbf{wk}\left(2\times \mathbf{maxip}\right)$ – Real (Kind=nag_wp) arrayWorkspace

29:   $\mathbf{ifail}$ – IntegerInput/Output

On entry: ifail must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation 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 argument, 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{fin}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{fin}\ge 0.0$.

On entry, $\mathbf{istep}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{istep}\ge 0$.

On entry, $\mathbf{istep}=〈\mathit{\text{value}}〉$ and $\mathbf{nterm}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{istep}\ne 0$, $\mathbf{nterm}>0$.

On entry, $\mathbf{ldq}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ldq}\ge \mathbf{n}$.

On entry, $\mathbf{ldx}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ldx}\ge \mathbf{n}$.

On entry, $\mathbf{m}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{m}\ge 1$.

On entry, $\mathbf{mean}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{mean}=\text{'M'}$ or $\text{'Z'}$.

On entry, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{n}\ge 2$.

On entry, $\mathbf{rss}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{rss}>0.0$.

On entry, $\mathbf{weight}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{weight}=\text{'W'}$ or $\text{'U'}$.

$\mathbf{ifail}=2$

On entry, $\mathbf{wt}\left(〈\mathit{\text{value}}〉\right)<0.0$.
Constraint: $\mathbf{wt}\left(i\right)\ge 0.0$, for $i=1,2,\dots ,n$.

$\mathbf{ifail}=3$

Degrees of freedom for error will equal $0$ if new variable is added, i.e., the number of variables in the model plus $1$ is equal to the effective number of observations.

On entry, number of forced variables $\ge \mathbf{n}$.

$\mathbf{ifail}=4$

On entry, $\mathbf{isx}\left(〈\mathit{\text{value}}〉\right)<0$.
Constraint: $\mathbf{isx}\left(i\right)\ge 0$, for $i=1,2,\dots ,\mathbf{m}$.

On entry, $\mathbf{isx}\left(i\right)=0$, for all $i=1,2,\dots ,\mathbf{m}$.
Constraint: at least one value of isx must be nonzero.

On entry, $\mathbf{maxip}=〈\mathit{\text{value}}〉$.
Constraint: maxip must be large enough to accommodate the number of terms given by isx.

$\mathbf{ifail}=5$

On entry, the variables forced into the model are not of full rank, i.e., some of these variables are linear combinations of others.

$\mathbf{ifail}=6$

There are no free variables, i.e., no element of $\mathbf{isx}=0$.

$\mathbf{ifail}=7$

The value of the change in the sum of squares is greater than the input value of rss. This may occur due to rounding errors if the true residual sum of squares for the new model is small relative to the residual sum of squares for the previous model.

$\mathbf{ifail}=-99$

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

See Section 3.9 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-399$

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

See Section 3.8 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (g02eefe.f90)

10.2

Program Data

Program Data (g02eefe.d)

10.3

Program Results

Program Results (g02eefe.r)