NAG Toolbox: nag_rand_times_smooth_exp (g05pm)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

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

Indicates if nag_rand_times_smooth_exp (g05pm) is continuing from a previous call or, if not, how the initial values are computed.

$\mathbf{mode}=0$

Values for $m_0$, $r_0$ and $s_{-\mathit{j}}$, for $\mathit{j}=0,1,\dots ,p-1$, are supplied in init.

$\mathbf{mode}=1$

nag_rand_times_smooth_exp (g05pm) continues from a previous call using values that are supplied in r. r is not updated.

$\mathbf{mode}=2$

nag_rand_times_smooth_exp (g05pm) continues from a previous call using values that are supplied in r. r is updated.

Constraint: $\mathbf{mode}=0$, $1$ or $2$.

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

The number of terms of the time series being generated.

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

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

The smoothing function.

$\mathbf{itype}=1$

Single exponential.

$\mathbf{itype}=2$

Brown's double exponential.

$\mathbf{itype}=3$

Linear Holt.

$\mathbf{itype}=4$

Additive Holt–Winters.

$\mathbf{itype}=5$

Multiplicative Holt–Winters.

Constraint: $\mathbf{itype}=1$, $2$, $3$, $4$ or $5$.

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

If $\mathbf{itype}=4$ or $5$, the seasonal order, $p$, otherwise p is not referenced.

Constraint: if $\mathbf{itype}=4$ or $5$, $\mathbf{p}>1$.

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

The dimension of the array param must be at least $1$ if $\mathbf{itype}=1$ or $2$, $3$ if $\mathbf{itype}=3$ and at least $4$ if $\mathbf{itype}=4$ or $5$

The smoothing parameters.

If $\mathbf{itype}=1$ or $2$, $\mathbf{param}\left(1\right)=\alpha$ and any remaining elements of param are not referenced.

If $\mathbf{itype}=3$, $\mathbf{param}\left(1\right)=\alpha$, $\mathbf{param}\left(2\right)=\gamma$, $\mathbf{param}\left(3\right)=\varphi$ and any remaining elements of param are not referenced.

If $\mathbf{itype}=4$ or $5$, $\mathbf{param}\left(1\right)=\alpha$, $\mathbf{param}\left(2\right)=\gamma$, $\mathbf{param}\left(3\right)=\beta$ and $\mathbf{param}\left(4\right)=\varphi$ and any remaining elements of param are not referenced.

Constraints:

• if $\mathbf{itype}=1$, $0.0\le \alpha \le 1.0$;
• if $\mathbf{itype}=2$, $0.0<\alpha \le 1.0$;
• if $\mathbf{itype}=3$, $0.0\le \alpha \le 1.0$ and $0.0\le \gamma \le 1.0$ and $\varphi \ge 0.0$;
• if $\mathbf{itype}=4$ or $5$, $0.0\le \alpha \le 1.0$ and $0.0\le \gamma \le 1.0$ and $0.0\le \beta \le 1.0$ and $\varphi \ge 0.0$.

6:     $\mathrm{init}\left(:\right)$ – double array

The dimension of the array init must be at least $1$ if $\mathbf{itype}=1$, $2$ if $\mathbf{itype}=2$ or $3$ and at least $2+\mathbf{p}$ if $\mathbf{itype}=4$ or $5$

If $\mathbf{mode}=0$, the initial values for $m_0$, $r_0$ and $s_{-\mathit{j}}$, for $\mathit{j}=0,1,\dots ,p-1$, used to initialize the smoothing.

If $\mathbf{itype}=1$, $\mathbf{init}\left(1\right)=m_0$ and any remaining elements of init are not referenced.

If $\mathbf{itype}=2$ or $3$, $\mathbf{init}\left(1\right)=m_0$ and $\mathbf{init}\left(2\right)=r_0$ and any remaining elements of init are not referenced.

If $\mathbf{itype}=4$ or $5$, $\mathbf{init}\left(1\right)=m_0$, $\mathbf{init}\left(2\right)=r_0$ and $\mathbf{init}\left(3\right)$ to $\mathbf{init}\left(2+p\right)$ hold the values for $s_{-\mathit{j}}$, for $\mathit{j}=0,1,\dots ,p-1$. Any remaining elements of init are not referenced.

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

The variance, ${\sigma }^2$ of the Normal distribution used to generate the errors ${\epsilon }_i$. If $\mathbf{var}\le 0.0$ then Normally distributed errors are not used.

8:     $\mathrm{r}\left(:\right)$ – double array

The dimension of the array r must be at least $13$ if $\mathbf{itype}=1$, $2$ or $3$ and at least $13+\mathbf{p}$ if $\mathbf{itype}=4$ or $5$

If $\mathbf{mode}=1$ or $2$, r must contain the values as returned by a previous call to nag_rand_times_smooth_exp (g05pm), r need not be set otherwise.

Constraint: if $\mathbf{mode}=1$ or $2$, r must have been initialized by at least one call to nag_rand_times_smooth_exp (g05pm) or nag_tsa_uni_smooth_exp (g13am) with $\mathbf{mode}\ne 1$, and r must not have been changed since that call.

9:     $\mathrm{state}\left(:\right)$ – int64int32nag_int array

Note: the actual argument supplied must be the array state supplied to the initialization routines nag_rand_init_repeat (g05kf) or nag_rand_init_nonrepeat (g05kg).

Contains information on the selected base generator and its current state.

10:   $\mathrm{e}\left(\mathbf{en}\right)$ – double array

If $\mathbf{en}>0$ and $\mathbf{var}\le 0.0$, a vector from which the errors, ${\epsilon }_t$ are randomly drawn, with replacement.

If $\mathbf{en}\le 0$, e is not referenced.

Optional Input Parameters

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

Default: the dimension of the array e.

If $\mathbf{en}>0$, then the length of the vector e.

If both $\mathbf{var}\le 0.0$ and $\mathbf{en}\le 0$ then ${\epsilon }_{\mathit{t}}=0.0$, for $\mathit{t}=1,2,\dots ,n$.

Output Parameters

1:     $\mathrm{r}\left(:\right)$ – double array

The dimension of the array r will be $13$ if $\mathbf{itype}=1$, $2$ or $3$ and at least $13+\mathbf{p}$ if $\mathbf{itype}=4$ or $5$

If $\mathbf{mode}=1$, r is unchanged. Otherwise, r contains the information on the current state of smoothing.

2:     $\mathrm{state}\left(:\right)$ – int64int32nag_int array

Contains updated information on the state of the generator.

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

The generated time series, $x_{\mathit{t}}$, for $\mathit{t}=1,2,\dots ,n$.

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

   $\mathbf{ifail}=1$

Constraint: $\mathbf{mode}=0$, $1$ or $2$.

   $\mathbf{ifail}=2$

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

   $\mathbf{ifail}=3$

Constraint: $\mathbf{itype}=1$, $2$, $3$, $4$ or $5$.

   $\mathbf{ifail}=4$

Constraint: if $\mathbf{itype}=4$ or $5$, $\mathbf{p}\ge 2$.

   $\mathbf{ifail}=5$

Constraint: $0\le \mathbf{param}\left(i\right)\le 1$.

Constraint: if $\mathbf{itype}=2$, $0<\mathbf{param}\left(i\right)\le 1$.

Constraint: $\mathbf{param}\left(i\right)\ge 0$.

   $\mathbf{ifail}=8$

On entry, some of the elements of the array r have been corrupted or have not been initialized.

   $\mathbf{ifail}=9$

On entry, state vector has been corrupted or not initialized.

   $\mathbf{ifail}=12$

Model unsuitable for multiplicative Holt–Winter, try a different set of parameters.

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

function g05pm_example


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

% Initialize the generator to a repeatable sequence
seed  = [int64(1762543)];
genid = int64(1);
subid =  int64(1);
[state, ifail] = g05kf( ...
                        genid, subid, seed);

mode  = int64(2);
n     = 11;
k     = int64(11);
nf    = int64(20);
nsim  = 100;
alpha = 0.05;
y     = [180; 135; 213; 181; 148; 204; 228; 225; 198; 200; 187];
itype = int64(3);
inits = [0; 0];
p     = int64(0);
r     = zeros(p+13,1);
param = [0.01; 1; 1];
e     = [];
gsim = zeros(nsim, nf);
bsim = zeros(nsim, nf);

% Fit a smoothing model (parameter r in g05pm and state in g13am
% are in the same format)
[inits, fv, fse, yhat, res, dv, ad, r, ifail] =  ...
  g13am( ...
         mode, itype, p, param, y, k, inits, nf, r);

% Simulate forecast values from the model, and no update of r
smode = int64(2);
var   = dv*dv;
% Simulate nsim forecasts
for i = 1:nsim
  % Simulations assuming gaussian errors
  [r, state, gsim(i, :), ifail] = ...
    g05pm( ...
           smode, nf, itype, p, param, inits, var, r, state, e);
  % Bootstrapping errors
  [r, state, bsim(i, :), ifail] = ...
    g05pm( ...
           smode, nf, itype, p, param, inits, 0, r, state, res);
end

% Calculate CI based on the quantiles for each simulated forecast
q = [alpha/2; 1-alpha/2];
glim = zeros(2, nf);
blim = zeros(2, nf);
for i = 1:nf
  [glim(:, i), ifail] = g01am(gsim(:,i), q);
  [blim(:, i), ifail] = g01am(bsim(:,i), q);
end

% Display the forecast values and associated prediction intervals
fprintf('\n Initial values used:\n');
for i = 1:numel(inits);
  fprintf(' %d %12.3f\n', i, inits(i));
end
fprintf('\nMean Deviation     = %12.4e\n', dv);
fprintf('Absolute Deviation = %12.4e\n\n', ad);
fprintf('         Observed      1-Step\n');
fprintf(' Period   Values      Forecast      Residual\n');
for i=1:n
  fprintf('%4d %12.3f %12.3f %12.3f\n', i, y(i,1), yhat(i,1), res(i,1));
end
fprintf('\n%52s%20s\n','Simulated CI','Simulated CI');
fprintf('%14s%17s%22s%21s\n', 'Obs.  Forecast', 'Estimated CI', ...
        '(Gaussian Errors)', '(Bootstrap Errors)');

[z, ifail] = g01fa(q(2));

for i = 1:5
  tmp = z*fse(i);
  fprintf('%3d', n+i);
  fprintf('%10.3f', fv(i), fv(i)-tmp, fv(i)+tmp, glim(1:2, i), blim(1:2, i));
  fprintf('\n');
end
fprintf('\n %5.1f%% CIs were produced\n', 100*(1-alpha));

fig1 = figure;
hold on;
plot([1:n], y, 'x-r');
plot([1:n], yhat,'-g');
plot([n+1:n+20], fv,'-b');
plot([n+1:n+20], fv-z*fse,'-c');
plot([n+1:n+20], fv+z*fse,'-c');
plot([n+1:n+20], glim(1,:),'-m');
plot([n+1:n+20], glim(2,:),'-m');
plot([n+1:n+20], blim(1,:),'-k');
plot([n+1:n+20], blim(2,:),'-k');
hold off
legend('observed', 'smoothed', 'forecast', 'estimated CI', ...
       'simulated CI', 'bootsrtapped CI', 'Location', 'SouthEast');
xlabel('Time');
ylabel('Data');
title({'Exponential smoothing', ...
       '95%% confidence intervals (CIs) are shown'});

g05pm example results


 Initial values used:
 1      168.018
 2        3.800

Mean Deviation     =   2.5473e+01
Absolute Deviation =   2.1233e+01

         Observed      1-Step
 Period   Values      Forecast      Residual
   1      180.000      171.818        8.182
   2      135.000      175.782      -40.782
   3      213.000      178.848       34.152
   4      181.000      183.005       -2.005
   5      148.000      186.780      -38.780
   6      204.000      189.800       14.200
   7      228.000      193.492       34.508
   8      225.000      197.732       27.268
   9      198.000      202.172       -4.172
  10      200.000      206.256       -6.256
  11      187.000      210.256      -23.256

                                        Simulated CI        Simulated CI
Obs.  Forecast     Estimated CI     (Gaussian Errors)   (Bootstrap Errors)
 12   213.854   163.928   263.781   157.822   261.312   173.073   248.363
 13   217.685   167.748   267.622   171.006   258.662   176.994   252.738
 14   221.516   171.556   271.475   183.687   262.402   179.870   256.473
 15   225.346   175.347   275.345   176.347   275.832   183.923   261.128
 16   229.177   179.115   279.238   179.421   280.585   187.008   266.360

  95.0% CIs were produced