naginterfaces.library.correg.linregm_​fit_​onestep

naginterfaces.library.correg.linregm_fit_onestep(istep, x, vname, isx, y, model, nterm, rss, idf, ifr, free, q, p, mean='M', wt=None, fin=2.0)

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

For full information please refer to the NAG Library document for g02ee

https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/g02/g02eef.html

Parameters

istepint

Indicates which step in the forward selection process is to be carried out.

$istep=0$

The process is initialized.

xfloat, array-like, shape $(n,m)$

$x[\text{i}-1,\text{j}-1]$ must contain the $\text{i}$th observation for the $\text{j}$th independent variable, for $\text{j}=1,2,\dots ,m$, for $\text{i}=1,2,\dots ,n$.

vnamestr, array-like, shape $\left(m\right)$

$vname[\text{j}-1]$ must contain the name of the independent variable in column $\text{j}$ of $x$, for $\text{j}=1,2,\dots ,m$.

isxint, array-like, shape $\left(m\right)$

Indicates which independent variables could be considered for inclusion in the regression.

$isx[j-1]\ge 2$

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

$isx[j-1]=1$

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

$isx[j-1]=0$

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

yfloat, array-like, shape $\left(n\right)$

The dependent variable.

modelstr, array-like, shape $\left(\text{maxip}\right)$

If $istep=0$, $model$ need not be set.

If $istep\ne 0$, $model$ must contain the values returned by the previous call to linregm_fit_onestep.

ntermint

If $istep=0$, $nterm$ need not be set.

If $istep\ne 0$, $nterm$ must contain the value returned by the previous call to linregm_fit_onestep.

rssfloat

If $istep=0$, $rss$ need not be set.

If $istep\ne 0$, $rss$ must contain the value returned by the previous call to linregm_fit_onestep.

idfint

If $istep=0$, $idf$ need not be set.

If $istep\ne 0$, $idf$ must contain the value returned by the previous call to linregm_fit_onestep.

ifrint

If $istep=0$, $ifr$ need not be set.

If $istep\ne 0$, $ifr$ must contain the value returned by the previous call to linregm_fit_onestep.

freestr, array-like, shape $\left(\text{maxip}\right)$

If $istep=0$, $free$ need not be set.

If $istep\ne 0$, $free$ must contain the values returned by the previous call to linregm_fit_onestep.

qfloat, array-like, shape $(n,\text{maxip}+2)$

If $istep=0$, $q$ need not be set.

If $istep\ne 0$, $q$ must contain the values returned by the previous call to linregm_fit_onestep.

pfloat, array-like, shape $(\text{maxip}+1)$

If $istep=0$, $p$ need not be set.

If $istep\ne 0$, $p$ must contain the values returned by the previous call to linregm_fit_onestep.

meanstr, length 1, optional

Indicates if a mean term is to be included.

$mean=\text{'M'}$

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

$mean=\text{'Z'}$

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

wtNone or float, array-like, shape $\left(n\right)$, optional

If provided $wt$ must contain the weights to be used with the model.

If $wt[i-1]=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 $wt$ is not provided the effective number of observations is $n$.

finfloat, optional

The critical value of the $F$ statistic for the term to be included in the model, $F_c$.

Returns

istepint

Is incremented by $1$.

addvarbool

Indicates if a variable has been added to the model.

$addvar=True$

A variable has been added to the model.

$addvar=False$

No variable had an $F$ value greater than $F_c$ and none were added to the model.

newvarstr

If $addvar=True$, $newvar$ contains the name of the variable added to the model.

chrssfloat

If $addvar=True$, $chrss$ contains the change in the residual sum of squares due to adding variable $newvar$.

ffloat

If $addvar=True$, $f$ contains the $F$ statistic for the inclusion of the variable in $newvar$.

modelstr, ndarray, shape $\left(\text{maxip}\right)$

The names of the variables in the current model.

ntermint

The number of independent variables in the current model, not including the mean, if any.

rssfloat

The residual sums of squares for the current model.

idfint

The degrees of freedom for the residual sum of squares for the current model.

ifrint

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

freestr, ndarray, shape $\left(\text{maxip}\right)$

The first $ifr$ values of $free$ contain the names of the free variables.

exssfloat, ndarray, shape $\left(\text{maxip}\right)$

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

qfloat, ndarray, shape $(n,\text{maxip}+2)$

The results of the $QR$ decomposition for the current model:

the first column of $q$ contains $c=Q^{T}y$ (or $Q^T{W}^{\frac{1}{2}}y$ where $W$ is the vector of weights if used);

the upper triangular part of columns $2$ to $\text{p}+1$ contain the $R$ matrix;

the strictly lower triangular part of columns $2$ to $\text{p}+1$ contain details of the $Q$ matrix;

the remaining $\text{p}+1$ to $\text{p}+ifr$ columns of contain $Q^T{X}_{\text{free}}$ (or $Q^T{W}^{\frac{1}{2}}{X}_{\text{free}}$),

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

pfloat, ndarray, shape $(\text{maxip}+1)$

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

Raises

NagValueError

(errno $1$)

On entry, $fin=⟨value⟩$.

Constraint: $fin\ge 0.0$.

(errno $1$)

On entry, $rss=⟨value⟩$.

Constraint: $rss>0.0$.

(errno $1$)

On entry, $istep=⟨value⟩$ and $nterm=⟨value⟩$.

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

(errno $1$)

On entry, $istep=⟨value⟩$.

Constraint: $istep\ge 0$.

(errno $1$)

On entry, $\text{weight}=⟨value⟩$.

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

(errno $1$)

On entry, $mean=⟨value⟩$.

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

(errno $1$)

On entry, $m=⟨value⟩$.

Constraint: $m\ge 1$.

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 2$.

(errno $2$)

On entry, $wt[⟨value⟩]<0.0$.

Constraint: $wt[i-1]\ge 0.0$, for $i=1,2,\dots ,n$.

(errno $3$)

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

(errno $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.

(errno $4$)

On entry, $\text{maxip}=⟨value⟩$.

Constraint: $\text{maxip}$ must be large enough to accommodate the number of terms given by $isx$.

(errno $4$)

On entry, $isx[⟨value⟩]<0$.

Constraint: $isx[i-1]\ge 0$, for $i=1,2,\dots ,m$.

(errno $4$)

On entry, $isx[i-1]=0$, for all $i=1,2,\dots ,m$.

Constraint: at least one value of $isx$ must be nonzero.

Warns

NagAlgorithmicWarning

(errno $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.

(errno $6$)

There are no free variables, i.e., no element of $isx=0$.

(errno $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.

Notes

One method of selecting a linear regression model from a given set of independent variables is by forward selection. The following procedure is used:

1. 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_c$, then include the variable in the model, else stop.

2. Find the independent variable that leads to the greatest reduction in the residual sum of squares when added to the current model.

3. If the $F$-test for this variable is greater than a chosen critical value, $F_c$, then include the variable in the model and go to (2), otherwise stop.

At any step the variables not in the model are known as the free terms.

linregm_fit_onestep 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^T{X}_{free}$, where $X_{free}$ is the matrix of variables not included in the model, is updated.

linregm_fit_onestep 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 linregm_update(), in order to compute the regression coefficients for the model fitted at that step. Repeated calls to linregm_fit_onestep should be made until $F<F_c$ is indicated.

References

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

Weisberg, S, 1985, Applied Linear Regression, Wiley