NAG Toolbox: nag_correg_linregm_var_add (g02de)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{ip}$ – int64int32nag_int scalar

$p$, the number of independent variables already in the model.

Constraint: $\mathbf{ip}\ge 0$ and $\mathbf{ip}<\mathbf{n}$.

2:     $\mathrm{q}\left(\mathit{ldq},\mathbf{ip}+2\right)$ – double array

ldq, the first dimension of the array, must satisfy the constraint $\mathit{ldq}\ge \mathbf{n}$.

If $\mathbf{ip}\ne 0$, q must contain the results of the $QR$ decomposition for the model with $p$ arguments as returned by nag_correg_linregm_fit (g02da) or a previous call to nag_correg_linregm_var_add (g02de).

If $\mathbf{ip}=0$, the first column of q should contain the $n$ values of the dependent variable, $y$.

3:     $\mathrm{p}\left(\mathbf{ip}+1\right)$ – double array

Contains further details of the $QR$ decomposition used. The first ip elements of p must contain the zeta values for the $QR$ decomposition (see nag_lapack_dgeqrf (f08ae) for details).

The first ip elements of array p are provided by nag_correg_linregm_fit (g02da) or by previous calls to nag_correg_linregm_var_add (g02de).

4:     $\mathrm{x}\left(\mathbf{n}\right)$ – double array

$x$, the new independent variable.

Optional Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

Default: the dimension of the array x and the first dimension of the array q. (An error is raised if these dimensions are not equal.)

$n$, the number of observations.

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

2:     $\mathrm{wt}\left(:\right)$ – double array

The dimension of the array wt must be at least $\mathbf{n}$ if $\mathit{weight}=\text{'W'}$, and at least $1$ otherwise

If provided, wt must contain the weights to be used.

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 wt is not provided the effective number of observations is $n$.

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

3:     $\mathrm{tol}$ – double scalar

Default: $0.000001$

The value of tol is used to decide if the new independent variable is linearly related to independent variables already included in the model. If the new variable is linearly related then $c$ is not updated. The smaller the value of tol the stricter the criterion for deciding if there is a linear relationship.

Constraint: $\mathbf{tol}>0.0$.

Output Parameters

1:     $\mathrm{q}\left(\mathit{ldq},\mathbf{ip}+2\right)$ – double array

The results of the $QR$ decomposition for the model with $p+1$ arguments:

• the first column of q contains the updated value of $c$;
• the columns $2$ to $\mathbf{ip}+1$ are unchanged;
• the first $\mathbf{ip}+1$ elements of column $\mathbf{ip}+2$ contain the new column of $R$, while the remaining $\mathbf{n}-\mathbf{ip}-1$ elements contain details of the matrix $Q_{p+1}$.

2:     $\mathrm{p}\left(\mathbf{ip}+1\right)$ – double array

The first ip elements of p are unchanged and the $\left(\mathbf{ip}+1\right)$th element contains the zeta value for $Q_{p+1}$.

3:     $\mathrm{rss}$ – double scalar

The residual sum of squares for the new fitted model.

Note:  this will only be valid if the model is of full rank, see Further Comments.

4:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

   $\mathbf{ifail}=1$

On entry,	$\mathbf{n}<1$,
or	$\mathbf{ip}<0$,
or	$\mathbf{ip}\ge \mathbf{n}$,
or	$\mathit{ldq}<\mathbf{n}$,
or	$\mathbf{tol}\le 0.0$,
or	$\mathit{weight}\ne \text{'U'}$ or $\text{'W'}$.

   $\mathbf{ifail}=2$

On entry,

$\mathit{weight}=\text{'W'}$ and a value of $\mathbf{wt}<0.0$.

W  $\mathbf{ifail}=3$

The new independent variable is a linear combination of existing variables. The $\left(\mathbf{ip}+2\right)$th column of q will therefore be null.

   $\mathbf{ifail}=-99$

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

   $\mathbf{ifail}=-399$

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

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: g02de_example

function g02de_example


fprintf('g02de example results\n\n');

x = [1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0  1.0;
     1.0  1.5  2.0  2.5  3.0  3.5  4.0  4.5  5.0  5.5  6.0  6.5;
     0.0  0.0  0.0  0.0  0.0  0.0  1.0  1.0  1.0  1.0  1.0  1.0;
     0.0  0.0  0.0  0.0  0.0  0.0  4.0  4.5  5.0  5.5  6.0  6.5;
     1.4  2.2  4.5  6.1  7.1  7.7  8.3  8.6  8.8  9.0  9.3  9.2];
[m,n] = size(x);
y = [4.32; 5.21; 6.49; 7.10; 7.94; 8.53;
     8.84; 9.02; 9.27; 9.43; 9.68; 9.83]; 

q = zeros(n,m+1);
q(:,1) = y;
p = zeros(m*(m+2),1);;
ip = int64(0);

% Add variables to model one at a time
for j = 1:m
  [q, p, rss, ifail] = g02de( ...
                              ip, q, p, x(j,1:n));
  ip = ip + 1;
  fprintf('\nVariable %4d added\n',ip);

  % Calculate parameter estimates
  rsst = 0;
  [rsst, idf, b, se, covar, svd, irank, p2, ifail] = ...
  g02dd(int64(n), ip, q, rsst);

  if svd
    fprintf('Model not of full rank\n\n');
  end
  fprintf('Residual sum of squares = %12.4e\n', rsst);
  fprintf('Degrees of freedom      = %4d\n', idf);
  fprintf('\nVariable   Parameter estimate   Standard error\n\n');
  ivar = double([1:ip]');
  fprintf('%6d%20.4e%20.4e\n',[ivar b se]');
end

g02de example results


Variable    1 added
Residual sum of squares =   3.6267e+01
Degrees of freedom      =   11

Variable   Parameter estimate   Standard error

     1          7.9717e+00          5.2416e-01

Variable    2 added
Residual sum of squares =   4.0164e+00
Degrees of freedom      =   10

Variable   Parameter estimate   Standard error

     1          4.4100e+00          4.3756e-01
     2          9.4979e-01          1.0599e-01

Variable    3 added
Residual sum of squares =   3.8872e+00
Degrees of freedom      =    9

Variable   Parameter estimate   Standard error

     1          4.2236e+00          5.6734e-01
     2          1.0554e+00          2.2217e-01
     3         -4.1962e-01          7.6695e-01

Variable    4 added
Residual sum of squares =   1.8702e-01
Degrees of freedom      =    8

Variable   Parameter estimate   Standard error

     1          2.7605e+00          1.7592e-01
     2          1.7057e+00          7.3100e-02
     3          4.4575e+00          4.2676e-01
     4         -1.3006e+00          1.0338e-01

Variable    5 added
Residual sum of squares =   8.4066e-02
Degrees of freedom      =    7

Variable   Parameter estimate   Standard error

     1          3.1440e+00          1.8181e-01
     2          9.0748e-01          2.7761e-01
     3          2.0790e+00          8.6804e-01
     4         -6.1589e-01          2.4530e-01
     5          2.9224e-01          9.9810e-02