g02 Chapter Contents
g02 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_step_regsn (g02eec)

## 1  Purpose

nag_step_regsn (g02eec) carries out one step of a forward selection procedure in order to enable the ‘best’ linear regression model to be found.

## 2  Specification

 #include #include
 void nag_step_regsn (Nag_OrderType order, Integer *istep, Nag_IncludeMean mean, Integer n, Integer m, const double x[], Integer pdx, const char *var_names[], const Integer sx[], Integer maxip, const double y[], const double wt[], double fin, Nag_Boolean *addvar, const char *newvar[], double *chrss, double *f, const char *model[], Integer *nterm, double *rss, Integer *idf, Integer *ifr, const char *free_vars[], double exss[], double q[], Integer pdq, double p[], NagError *fail)

## 3  Description

One method of selecting a linear regression model from a given set of independent variables is by forward selection. The following procedure is used:
 (i) Select the best fitting independent variable, i.e., the independent variable which gives the smallest residual sum of squares. If the $F$-test for this variable is greater than a chosen critical value, ${F}_{\mathrm{c}}$, then include the variable in the model, else stop. (ii) Find the independent variable that leads to the greatest reduction in the residual sum of squares when added to the current model. (iii) If the $F$-test for this variable is greater than a chosen critical value, ${F}_{\mathrm{c}}$, then include the variable in the model and go to (ii), otherwise stop.
At any step the variables not in the model are known as the free terms.
nag_step_regsn (g02eec) allows you to specify some independent variables that must be in the model, these are known as forced variables.
The computational procedure involves the use of $QR$ decompositions, the $R$ and the $Q$ matrices being updated as each new variable is added to the model. In addition the matrix ${Q}^{\mathrm{T}}{X}_{\mathrm{free}}$, where ${X}_{\mathrm{free}}$ is the matrix of variables not included in the model, is updated.
nag_step_regsn (g02eec) computes one step of the forward selection procedure at a call. The results produced at each step may be printed or used as inputs to nag_regsn_mult_linear_upd_model (g02ddc), in order to compute the regression coefficients for the model fitted at that step. Repeated calls to nag_step_regsn (g02eec) should be made until $F<{F}_{\mathrm{c}}$ is indicated.

## 4  References

Draper N R and Smith H (1985) Applied Regression Analysis (2nd Edition) Wiley
Weisberg S (1985) Applied Linear Regression Wiley

## 5  Arguments

Note:  after the initial call to nag_step_regsn (g02eec) with ${\mathbf{istep}}=0$ all arguments except fin must not be changed by you between calls.
1:    $\mathbf{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 2.3.1.3 in How to Use the NAG Library and its Documentation for a more detailed explanation of the use of this argument.
Constraint: ${\mathbf{order}}=\mathrm{Nag_RowMajor}$ or $\mathrm{Nag_ColMajor}$.
2:    $\mathbf{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:    $\mathbf{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:    $\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[\mathit{dim}\right]$const doubleInput
Note: the dimension, dim, of the array x must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdx}}×{\mathbf{m}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}×{\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)×{\mathbf{pdx}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{x}}\left[\left(i-1\right)×{\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:    $\mathbf{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:    $\mathbf{var_names}\left[{\mathbf{m}}\right]$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:    $\mathbf{sx}\left[{\mathbf{m}}\right]$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:  $\mathbf{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+\text{}$ number of values of ${\mathbf{sx}}>0$;
• if ${\mathbf{mean}}=\mathrm{Nag_MeanZero}$, ${\mathbf{maxip}}\ge \text{}$ number of values of ${\mathbf{sx}}>0$.
11:  $\mathbf{y}\left[{\mathbf{n}}\right]$const doubleInput
On entry: the dependent variable.
12:  $\mathbf{wt}\left[\mathit{dim}\right]$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}}\phantom{\rule{0.25em}{0ex}}\text{is not}\phantom{\rule{0.25em}{0ex}}\mathbf{NULL}$, ${\mathbf{wt}}\left[\mathit{i}\right]\ge 0.0$, for $\mathit{i}=0,1,\dots ,{\mathbf{n}}-1$.
13:  $\mathbf{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:  $\mathbf{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:  $\mathbf{newvar}\left[1\right]$const char *Output
On exit: if ${\mathbf{addvar}}=\mathrm{Nag_TRUE}$, newvar contains the name of the variable added to the model.
16:  $\mathbf{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:  $\mathbf{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:  $\mathbf{model}\left[{\mathbf{maxip}}\right]$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:  $\mathbf{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:  $\mathbf{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:  $\mathbf{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:  $\mathbf{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:  $\mathbf{free_vars}\left[{\mathbf{maxip}}\right]$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:  $\mathbf{exss}\left[{\mathbf{maxip}}\right]$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:  $\mathbf{q}\left[\mathit{dim}\right]$doubleInput/Output
Note: the dimension, dim, of the array q must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdq}}×{\mathbf{maxip}}+2\right)$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{n}}×{\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)×{\mathbf{pdq}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{q}}\left[\left(i-1\right)×{\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:  $\mathbf{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:  $\mathbf{p}\left[{\mathbf{maxip}}+1\right]$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:  $\mathbf{fail}$NagError *Input/Output
The NAG error argument (see Section 2.7 in How to Use the NAG Library and its Documentation).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_DENOM_ZERO
Denominator of f statistic is $\text{}\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.
An unexpected error has been triggered by this function. Please contact NAG.
See Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.
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 $\text{}\ge {\mathbf{n}}$, i.e., idf would be zero.
NE_ZERO_VARS
Maximum number of variables to be included is $0$.

## 7  Accuracy

As nag_step_regsn (g02eec) uses a $QR$ transformation the results will often be more accurate than traditional algorithms using methods based on the cross-products of the dependent and independent variables.

## 8  Parallelism and Performance

nag_step_regsn (g02eec) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
nag_step_regsn (g02eec) makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the x06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

None.

## 10  Example

The data, from an oxygen uptake experiment, is given by Weisberg (1985). The names of the variables are as given in Weisberg (1985). The independent and dependent variables are read and nag_step_regsn (g02eec) is repeatedly called until ${\mathbf{addvar}}=\mathrm{Nag_FALSE}$. At each step the $F$ statistic, the free variables and their extra sum of squares are printed; also, except for when ${\mathbf{addvar}}=\mathrm{Nag_FALSE}$, the new variable, the change in the residual sum of squares and the terms in the model are printed.

### 10.1  Program Text

Program Text (g02eece.c)

### 10.2  Program Data

Program Data (g02eece.d)

### 10.3  Program Results

Program Results (g02eece.r)