NAG Toolbox: nag_correg_linregm_obs_edit (g02dc)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{update}$ – string (length ≥ 1)

Indicates if an observation is to be added or deleted.

$\mathbf{update}=\text{'A'}$

The observation is added.

$\mathbf{update}=\text{'D'}$

The observation is deleted.

Constraint: $\mathbf{update}=\text{'A'}$ or $\text{'D'}$.

2:     $\mathrm{mean\_p}$ – string (length ≥ 1)

Indicates if a mean has been used in the model.

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

A mean term or intercept will have been included in the model by nag_correg_linregm_fit (g02da).

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

A model with no mean term or intercept will have been fitted by nag_correg_linregm_fit (g02da).

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

3:     $\mathrm{isx}\left(\mathbf{m}\right)$ – int64int32nag_int array

If $\mathbf{isx}\left(\mathit{j}\right)$ is greater than $0$, the value contained in $\mathbf{x}\left(\left(\mathit{j}-1\right)\times \mathbf{ix}+1\right)$ is to be included as a value of $x^{\mathrm{T}}$, for $\mathit{j}=1,2,\dots ,\mathbf{m}$.

Constraint: if $\mathbf{mean\_p}=\text{'M'}$, exactly $\mathbf{ip}-1$ elements of isx must be $>0$ and if $\mathbf{mean\_p}=\text{'Z'}$, exactly ip elements of isx must be $>0$.

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

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

Must be array q as output by nag_correg_linregm_fit (g02da), nag_correg_linregm_var_add (g02de), nag_correg_linregm_var_del (g02df) or nag_correg_linregm_fit_onestep (g02ee), or a previous call to nag_correg_linregm_obs_edit (g02dc).

5:     $\mathrm{x}\left(:\right)$ – double array

The dimension of the array x must be at least $\left(\mathbf{m}-1\right)\times \mathbf{ix}+1$

The ip values for the dependent variables of the new observation, $x^{\mathrm{T}}$. The positions will depend on the value of ix.

6:     $\mathrm{ix}$ – int64int32nag_int scalar

The increment for elements of x. Two situations are common:

$\mathbf{ix}=1$

The values of $x$ are to be chosen from consecutive locations in x, i.e., $\mathbf{x}\left(1\right),\mathbf{x}\left(2\right),\dots ,\mathbf{x}\left(\mathbf{m}\right)$.

$\mathbf{ix}=\mathbf{ldx}$

The values of $x$ are to be chosen from a row of a two-dimensional array with first dimension ldx, i.e., $\mathbf{x}\left(1\right),\mathbf{x}\left(\mathbf{ldx}+1\right),\dots ,\mathbf{x}\left(\left(\mathbf{m}-1\right)\mathbf{ldx}+1\right)$.

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

7:     $\mathrm{y}$ – double scalar

The value of the dependent variable for the new observation, $y_{\text{new}}$.

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

The value of the residual sums of squares for the original set of observations.

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

Optional Input Parameters

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

Default: the dimension of the array isx.

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

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

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

Default: the first dimension of the array q.

The number of linear terms in general linear regression model (including mean if there is one).

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

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

Default: $0$

If provided, wt must contain the weight to be used with the new observation.

If $\mathbf{wt}=0.0$, the observation is not included in the model.

Constraint: if $\mathbf{wt}\ge 0.0$, $\mathit{weight}=\text{'W'}$.

Output Parameters

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

The first ip elements of the first column of q will contain $c_1^{*}$ the upper triangular part of columns $2$ to $\mathbf{ip}+1$ will contain $R^{*}$ the remainder is unchanged.

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

The updated values of the residual sums of squares.

Note:  this will only be valid if the model is of full rank.

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

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

Error Indicators and Warnings

   $\mathbf{ifail}=1$

On entry,	$\mathbf{ip}<1$,
or	$\mathit{ldq}<\mathbf{ip}$,
or	$\mathbf{m}<1$,
or	$\mathbf{ix}<1$,
or	$\mathbf{rss}<0.0$,
or	$\mathbf{update}\ne \text{'A'}$ or $\text{'D'}$,
or	$\mathbf{mean\_p}\ne \text{'M'}$ or $\text{'Z'}$,
or	$\mathit{weight}\ne \text{'U'}$ or $\text{'W'}$,
or	$\mathbf{mean\_p}=\text{'M'}$ and there are not exactly $\mathbf{ip}-1$ nonzero values of isx,
or	$\mathbf{mean\_p}=\text{'Z'}$ and there are not exactly ip nonzero values of isx,

   $\mathbf{ifail}=2$

On entry,

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

   $\mathbf{ifail}=3$

The $R$ matrix could not be updated. This may occur if an attempt is made to delete an observation which was not in the original dataset or to add an observation to a $R$ matrix with a zero diagonal element. This error is also possible when removing an observation which reduces the rank of design matrix. In such cases the model should be recomputed using nag_correg_linregm_fit (g02da).

   $\mathbf{ifail}=4$

The residual sums of squares cannot be updated. This will occur if the input residual sum of squares is less than the calculated decrease in residual sum of squares when the new observation is deleted.

   $\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: g02dc_example

function g02dc_example


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

x = [1, 0, 0, 0;
     0, 0, 0, 1;
     0, 1, 0, 0;
     0, 0, 1, 0;
     0, 0, 0, 1;
     0, 1, 0, 0;
     0, 0, 0, 1;
     1, 0, 0, 0;
     0, 0, 1, 0;
     1, 0, 0, 0;
     0, 0, 1, 0;
     1, 1, 1, 1];
y = [33.63;     39.62;     38.18;     41.46;     38.02;     35.83;
     35.99;     36.58;     42.92;     37.80;     40.43;     37.89];

[n,m]  = size(x);
isx    = ones(m,1,'int64');
mean_p = 'Z';
ip     = int64(m);

% Fit initial general linear regression model
[rss, idf, b, se, covar, res, h, q, svd, irank, p, wk, ifail] = ...
  g02da(mean_p, x, isx, ip, y);

% Display initial results
fprintf('Results from initial model fit using g02da\n\n');
if svd
  fprintf('Model not of full rank, rank = %4d\n\n', irank);
end
fprintf('Residual sum of squares = %12.4e\n', rss);
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]');

% Add or delete observations one at a time
action = {'dropping'; 'adding'};
xobs = [1   1   1   1;
        0   1   0   0];
yobs = [37.89;
        37.89];
nobs = numel(yobs);
ix = int64(1);

for j = 1:nobs
  % update regression
  [q, rss, ifail] = g02dc( ...
                           action{j}, mean_p, isx, q, xobs(j,:), ix, ...
                           yobs(j), rss, 'ip', ip);
  % Parameter estmate update
  
  if strcmp(action{j},'adding')
    n = n + 1;
  else
    n = n - 1;
  end
  [rss, idf, b, se, covar, svd, irank, p, ifail] = ...
  g02dd(int64(n), ip, q, rss);
  
  fprintf('\nResults from %s an observation\n',action{j});
  fprintf('Residual sum of squares = %12.4e\n', rss);
  fprintf('Degrees of freedom      = %4d\n', idf);
  fprintf('\nVariable   Parameter estimate   Standard error\n\n');
  fprintf('%6d%20.4e%20.4e\n',[ivar b se]');

end

g02dc example results

Results from initial model fit using g02da

Residual sum of squares =   5.2748e+03
Degrees of freedom      =    8

Variable   Parameter estimate   Standard error

     1          2.0724e+01          1.3801e+01
     2          1.4085e+01          1.6240e+01
     3          2.6324e+01          1.3801e+01
     4          2.2597e+01          1.3801e+01

Results from dropping an observation
Residual sum of squares =   2.1705e+01
Degrees of freedom      =    7

Variable   Parameter estimate   Standard error

     1          3.6003e+01          1.0166e+00
     2          3.7005e+01          1.2451e+00
     3          4.1603e+01          1.0166e+00
     4          3.7877e+01          1.0166e+00

Results from adding an observation
Residual sum of squares =   2.2227e+01
Degrees of freedom      =    8

Variable   Parameter estimate   Standard error

     1          3.6003e+01          9.6235e-01
     2          3.7300e+01          9.6235e-01
     3          4.1603e+01          9.6235e-01
     4          3.7877e+01          9.6235e-01