Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_rand_times_smooth_exp (g05pm)

## Purpose

nag_rand_times_smooth_exp (g05pm) simulates from an exponential smoothing model, where the model uses either single exponential, double exponential or a Holt–Winters method.

## Syntax

[r, state, x, ifail] = g05pm(mode, n, itype, p, param, init, var, r, state, e, 'en', en)
[r, state, x, ifail] = nag_rand_times_smooth_exp(mode, n, itype, p, param, init, var, r, state, e, 'en', en)

## Description

nag_rand_times_smooth_exp (g05pm) returns $\left\{{x}_{t}:t=1,2,\dots ,n\right\}$, a realization of a time series from an exponential smoothing model defined by one of five smoothing functions:
• Single Exponential Smoothing
 $xt = mt-1 + εt mt = α xt + 1-α mt-1$
• Brown Double Exponential Smoothing
 $xt = mt-1 + rt-1 α + εt mt = α xt + 1-α mt-1 rt = α mt - mt-1 + 1-α rt-1$
• Linear Holt Exponential Smoothing
 $xt = mt-1 + ϕrt-1 + εt mt = α xt + 1-α mt-1 + ϕ rt-1 rt = γ mt - mt-1 + 1-γ ϕ rt-1$
 $xt = mt-1 + ϕrt-1 + st-1-p + εt mt = α xt - s t-p + 1-α m t-1 +ϕ r t-1 rt = γ mt - m t-1 + 1-γ ϕ rt-1 st = β xt - mt + 1-β s t-p$
• Multiplicative Holt–Winters Smoothing
 $xt = mt-1 + ϕrt-1 × s t-1-p + εt mt = α xt / s t-p + 1-α m t-1 +ϕ r t-1 rt = γ mt - m t-1 + 1-γ ϕ r t-1 st = β xt / mt + 1-β s t-p$
where ${m}_{t}$ is the mean, ${r}_{t}$ is the trend and ${s}_{t}$ is the seasonal component at time $t$ with $p$ being the seasonal order. The errors, ${\epsilon }_{t}$ are either drawn from a normal distribution with mean zero and variance ${\sigma }^{2}$ or randomly sampled, with replacement, from a user-supplied vector.

## References

Chatfield C (1980) The Analysis of Time Series Chapman and Hall

## 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$
${\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

Errors or warnings detected by the function:
${\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$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

Not applicable.

None.

## Example

This example reads $11$ observations from a time series relating to the rate of the earth's rotation about its polar axis and fits an exponential smoothing model using nag_tsa_uni_smooth_exp (g13am).
nag_rand_times_smooth_exp (g05pm) is then called multiple times to obtain simulated forecast confidence intervals.
```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('         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
```