NAG Library Function Document

nag_step_regsn (g02eec)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     order – Nag_OrderTypeInput

On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by $\mathbf{order}=\mathrm{Nag\_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.

Constraint: $\mathbf{order}=\mathrm{Nag\_RowMajor}$ or $\mathrm{Nag\_ColMajor}$.

2:     istep – Integer *Input/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$.

3:     mean – Nag_IncludeMeanInput

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

$\mathbf{mean}=\mathrm{Nag\_MeanInclude}$

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

$\mathbf{mean}=\mathrm{Nag\_MeanZero}$

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

Constraint: $\mathbf{mean}=\mathrm{Nag\_MeanInclude}$ or $\mathrm{Nag\_MeanZero}$.

4:     n – IntegerInput

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

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

5:     m – IntegerInput

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

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

6:     x[$\mathit{dim}$] – const doubleInput

Note: the dimension, dim, of the array x must be at least

• $\max \left(1,\mathbf{pdx}\times \mathbf{m}\right)$ when $\mathbf{order}=\mathrm{Nag\_ColMajor}$;
• $\max \left(1,\mathbf{n}\times \mathbf{pdx}\right)$ when $\mathbf{order}=\mathrm{Nag\_RowMajor}$.

Where $\mathbf{X}\left(i,j\right)$ appears in this document, it refers to the array element

• $\mathbf{x}\left[\left(j-1\right)\times \mathbf{pdx}+i-1\right]$ when $\mathbf{order}=\mathrm{Nag\_ColMajor}$;
• $\mathbf{x}\left[\left(i-1\right)\times \mathbf{pdx}+j-1\right]$ when $\mathbf{order}=\mathrm{Nag\_RowMajor}$.

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:     pdx – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array x.

Constraints:

• if $\mathbf{order}=\mathrm{Nag\_ColMajor}$, $\mathbf{pdx}\ge \mathbf{n}$;
• if $\mathbf{order}=\mathrm{Nag\_RowMajor}$, $\mathbf{pdx}\ge \mathbf{m}$.

8:     var_names[m] – const char *Input

On entry: $\mathbf{var\_names}\left[\mathit{i}-1\right]$ must contain the name of the independent variable in row $\mathit{i}$ of x, for $\mathit{i}=1,2,\dots ,\mathbf{m}$.

9:     sx[m] – const IntegerInput

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

$\mathbf{sx}\left[j-1\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{sx}\left[j-1\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{sx}\left[j-1\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{sx}\left[\mathit{j}-1\right]\ge 0$ and at least one value of $\mathbf{sx}\left[\mathit{j}-1\right]=1$, for $\mathit{j}=1,2,\dots ,\mathbf{m}$.

10:   maxip – IntegerInput

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

Constraints:

• if $\mathbf{mean}=\mathrm{Nag\_MeanInclude}$, $\mathbf{maxip}\ge 1+$ number of values of $\mathbf{sx}>0$;
• if $\mathbf{mean}=\mathrm{Nag\_MeanZero}$, $\mathbf{maxip}\ge$ number of values of $\mathbf{sx}>0$.

11:   y[n] – const doubleInput

On entry: the dependent variable.

12:   wt[$\mathit{dim}$] – const doubleInput

Note: the dimension, dim, of the array wt must be at least $\mathbf{n}$.

On entry: $W$, wt must contain the weights to be used in the weighted regression.

If $\mathbf{wt}\left[i-1\right]=0.0$, then 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 weights are not provided then wt must be set to the null pointer, i.e., (double *)0, and the effective number of observations is n.

Constraint: if $\mathbf{wt}\text{is not}\mathbf{NULL}$, $\mathbf{wt}\left[\mathit{i}\right]\ge 0.0$, for $\mathit{i}=0,1,\dots ,\mathbf{n}-1$.

13:   fin – doubleInput

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:   addvar – Nag_Boolean *Output

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

$\mathbf{addvar}=\mathrm{Nag\_TRUE}$

A variable has been added to the model.

$\mathbf{addvar}=\mathrm{Nag\_FALSE}$

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

15:   newvar[$1$] – const char *Output

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

16:   chrss – double *Output

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

17:   f – double *Output

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

18:   model[maxip] – const char *Input/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 nag_step_regsn (g02eec).

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

19:   nterm – Integer *Input/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 nag_step_regsn (g02eec).

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

20:   rss – double *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 nag_step_regsn (g02eec).

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

21:   idf – Integer *Input/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 nag_step_regsn (g02eec).

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

22:   ifr – Integer *Input/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 nag_step_regsn (g02eec).

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:   free_vars[maxip] – const char *Input/Output

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

If $\mathbf{istep}\ne 0$, free_vars must contain the values returned by the previous call to nag_step_regsn (g02eec).

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

24:   exss[maxip] – doubleOutput

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-1\right]$ contains what would be the change in regression sum of squares if the variable $\mathbf{free\_vars}\left[i-1\right]$ had been added to the model.

25:   q[$\mathit{dim}$] – doubleInput/Output

Note: the dimension, dim, of the array q must be at least

• $\max \left(1,\mathbf{pdq}\times \mathbf{maxip}+2\right)$ when $\mathbf{order}=\mathrm{Nag\_ColMajor}$;
• $\max \left(1,\mathbf{n}\times \mathbf{pdq}\right)$ when $\mathbf{order}=\mathrm{Nag\_RowMajor}$.

The $\left(i,j\right)$th element of the matrix $Q$ is stored in

• $\mathbf{q}\left[\left(j-1\right)\times \mathbf{pdq}+i-1\right]$ when $\mathbf{order}=\mathrm{Nag\_ColMajor}$;
• $\mathbf{q}\left[\left(i-1\right)\times \mathbf{pdq}+j-1\right]$ when $\mathbf{order}=\mathrm{Nag\_RowMajor}$.

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 nag_step_regsn (g02eec).

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}=\mathrm{Nag\_MeanInclude}$.

26:   pdq – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array q.

Constraints:

• if $\mathbf{order}=\mathrm{Nag\_ColMajor}$, $\mathbf{pdq}\ge \mathbf{n}$;
• if $\mathbf{order}=\mathrm{Nag\_RowMajor}$, $\mathbf{pdq}\ge \mathbf{maxip}+2$.

27:   p[$\mathbf{maxip}+1$] – doubleInput/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 nag_step_regsn (g02eec).

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}=\mathrm{Nag\_MeanInclude}$.

28:   fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.

NE_DENOM_ZERO

Denominator of f statistic is $\le 0.0$.

NE_FREE_VARS

There are no free variables in the regression.

NE_FULL_RANK

Forced variables not of full rank.

NE_INT

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

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

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

On entry, $\mathbf{pdq}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{pdq}>0$.

On entry, $\mathbf{pdx}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{pdx}>0$.

NE_INT_2

On entry, istep and nterm are inconsistent: $\mathbf{istep}=⟨\mathit{\text{value}}⟩$ and $\mathbf{nterm}=⟨\mathit{\text{value}}⟩$.

On entry, $\mathbf{pdq}=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{pdq}\ge \mathbf{n}$.

On entry, $\mathbf{pdx}=⟨\mathit{\text{value}}⟩$ and $\mathbf{m}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{pdx}\ge \mathbf{m}$.

On entry, $\mathbf{pdx}=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{pdx}\ge \mathbf{n}$.

NE_INT_ARRAY

On entry, maxip is too small for number of terms given by sx: $\mathbf{maxip}=⟨\mathit{\text{value}}⟩$.

NE_INT_ARRAY_ELEM_CONS

On entry, $\mathbf{sx}\left[⟨\mathit{\text{value}}⟩\right]<0$.

NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

NE_REAL

On entry, $\mathbf{fin}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{fin}\ge 0.0$.

On entry, with nonzero istep, $\mathbf{rss}\le 0.0$: $\mathbf{rss}=⟨\mathit{\text{value}}⟩$.

NE_REAL_ARRAY_ELEM_CONS

On entry, $\mathbf{wt}\left[⟨\mathit{\text{value}}⟩\right]<0.0$.

NE_ZERO_DF

Degrees of freedom for error will equal $0$ if new variable is added.

On entry, number of forced variables $\ge \mathbf{n}$, i.e., idf would be zero.

NE_ZERO_VARS

Maximum number of variables to be included is $0$.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (g02eece.c)

10.2  Program Data

Program Data (g02eece.d)

10.3  Program Results

Program Results (g02eece.r)