NAG C Library Function Document

nag_tsa_exp_smooth (g13amc)

1
Purpose

nag_tsa_exp_smooth (g13amc) performs exponential smoothing using either single exponential, double exponential or a Holt–Winters method.

2
Specification

#include <nag.h>
#include <nagg13.h>
void  nag_tsa_exp_smooth (Nag_InitialValues mode, Nag_ExpSmoothType itype, Integer p, const double param[], Integer n, const double y[], Integer k, double init[], Integer nf, double fv[], double fse[], double yhat[], double res[], double *dv, double *ad, double r[], NagError *fail)

3
Description

Exponential smoothing is a relatively simple method of short term forecasting for a time series. nag_tsa_exp_smooth (g13amc) provides five types of exponential smoothing; single exponential, Brown's double exponential, linear Holt (also called double exponential smoothing in some references), additive Holt–Winters and multiplicative Holt–Winters. The choice of smoothing method used depends on the characteristics of the time series. If the mean of the series is only slowly changing then single exponential smoothing may be suitable. If there is a trend in the time series, which itself may be slowly changing, then double exponential smoothing may be suitable. If there is a seasonal component to the time series, e.g., daily or monthly data, then one of the two Holt–Winters methods may be suitable.
For a time series yt, for t=1,2,,n, the five smoothing functions are defined by the following: where mt is the mean, rt is the trend and st is the seasonal component at time t with p being the seasonal order. The f-step ahead forecasts are given by y^t+f and their variances by var y^ t+f . The term var εt  is estimated as the mean deviation.
The parameters, α, β and γ control the amount of smoothing. The nearer these parameters are to one, the greater the emphasis on the current data point. Generally these parameters take values in the range 0.1 to 0.3. The linear Holt and two Holt–Winters smoothers include an additional parameter, ϕ, which acts as a trend dampener. For 0.0<ϕ<1.0 the trend is dampened and for ϕ>1.0 the forecast function has an exponential trend, ϕ=0.0 removes the trend term from the forecast function and ϕ=1.0 does not dampen the trend.
For all methods, values for α, β, γ and ψ can be chosen by trying different values and then visually comparing the results by plotting the fitted values along side the original data. Alternatively, for single exponential smoothing a suitable value for α can be obtained by fitting an ARIMA0,1,1 model (see nag_tsa_multi_inp_model_estim (g13bec)). For Brown's double exponential smoothing and linear Holt smoothing with no dampening, (i.e., ϕ=1.0), suitable values for α and γ can be obtained by fitting an ARIMA0,2,2 model. Similarly, the linear Holt method, with ϕ1.0, can be expressed as an ARIMA1,2,2 model and the additive Holt–Winters, with no dampening, (ϕ=1.0), can be expressed as a seasonal ARIMA model with order p of the form ARIMA0,1,p+10,1,0. There is no similar procedure for obtaining parameter values for the multiplicative Holt–Winters method, or the additive Holt–Winters method with ϕ1.0. In these cases parameters could be selected by minimizing a measure of fit using one of the nonlinear optimization functions in Chapter e04.
In addition to values for α, β, γ and ψ, initial values, m0, r0 and s-j, for j=0,1,,p-1, are required to start the smoothing process. You can either supply these or they can be calculated by nag_tsa_exp_smooth (g13amc) from the first k observations. For single exponential smoothing the mean of the observations is used to estimate m0. For Brown double exponential smoothing and linear Holt smoothing, a simple linear regression is carried out with the series as the dependent variable and the sequence 1,2,,k as the independent variable. The intercept is then used to estimate m0 and the slope to estimate r0. In the case of the additive Holt–Winters method, the same regression is carried out, but a separate intercept is used for each of the p seasonal groupings. The slope gives an estimate for r0 and the mean of the p intercepts is used as the estimate of m0. The seasonal parameters s-j, for j=0,1,,p-1, are estimated as the p intercepts – m0. A similar approach is adopted for the multiplicative Holt–Winter's method.
One step ahead forecasts, y^ t+1  are supplied along with the residuals computed as yt+1 - y^ t+1 . In addition, two measures of fit are provided. The mean absolute deviation,
1 n t=1 n yt - y^ t  
and the square root of the mean deviation
1 n t=1 n yt - y^ t 2 .  

4
References

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

5
Arguments

1:     mode Nag_InitialValuesInput
On entry: indicates if nag_tsa_exp_smooth (g13amc) is continuing from a previous call or, if not, how the initial values are computed.
mode=Nag_InitialValuesSupplied
Required values for m0, r0 and s-j, for j=0,1,,p-1, are supplied in init.
mode=Nag_ContinueAndUpdate
nag_tsa_exp_smooth (g13amc) continues from a previous call using values that are supplied in r.
mode=Nag_EstimateInitialValues
Required values for m0, r0 and s-j, for j=0,1,,p-1, are estimated using the first k observations.
Constraint: mode=Nag_InitialValuesSupplied, Nag_ContinueAndUpdate or Nag_EstimateInitialValues.
2:     itype Nag_ExpSmoothTypeInput
On entry: the smoothing function.
itype=Nag_SingleExponential
Single exponential.
itype=Nag_BrownsExponential
Brown double exponential.
itype=Nag_LinearHolt
Linear Holt.
itype=Nag_AdditiveHoltWinters
Additive Holt–Winters.
itype=Nag_MultiplicativeHoltWinters
Multiplicative Holt–Winters.
Constraint: itype=Nag_SingleExponential, Nag_BrownsExponential, Nag_LinearHolt, Nag_AdditiveHoltWinters or Nag_MultiplicativeHoltWinters.
3:     p IntegerInput
On entry: if itype=Nag_AdditiveHoltWinters or Nag_MultiplicativeHoltWinters, the seasonal order, p, otherwise p is not referenced.
Constraint: if itype=Nag_AdditiveHoltWinters or Nag_MultiplicativeHoltWinters, p>1.
4:     param[dim] const doubleInput
Note: the dimension, dim, of the array param must be at least
  • 1, when itype=Nag_SingleExponential or Nag_BrownsExponential;
  • 3, when itype=Nag_LinearHolt;
  • 4, when itype=Nag_AdditiveHoltWinters or Nag_MultiplicativeHoltWinters.
On entry: the smoothing parameters.
If itype=Nag_SingleExponential or Nag_BrownsExponential, param[0]=α and any remaining elements of param are not referenced.
If itype=Nag_LinearHolt, param[0]=α, param[1]=γ, param[2]=ϕ and any remaining elements of param are not referenced.
If itype=Nag_AdditiveHoltWinters or Nag_MultiplicativeHoltWinters, param[0]=α, param[1]=γ, param[2]=β and param[3]=ϕ.
Constraints:
  • if itype=Nag_SingleExponential, 0.0α1.0;
  • if itype=Nag_BrownsExponential, 0.0<α1.0;
  • if itype=Nag_LinearHolt, 0.0α1.0 and 0.0γ1.0 and ϕ0.0;
  • if itype=Nag_AdditiveHoltWinters or Nag_MultiplicativeHoltWinters, 0.0α1.0 and 0.0γ1.0 and 0.0β1.0 and ϕ0.0.
5:     n IntegerInput
On entry: the number of observations in the series.
Constraint: n0.
6:     y[n] const doubleInput
On entry: the time series.
7:     k IntegerInput
On entry: if mode=Nag_EstimateInitialValues, the number of observations used to initialize the smoothing.
If modeNag_EstimateInitialValues, k is not referenced.
Constraints:
  • if mode=Nag_EstimateInitialValues and itype=Nag_AdditiveHoltWinters or Nag_MultiplicativeHoltWinters, 2×pkn;
  • if mode=Nag_EstimateInitialValues and itype=Nag_SingleExponential, Nag_BrownsExponential or Nag_LinearHolt, 1kn.
8:     init[dim] doubleInput/Output
Note: the dimension, dim, of the array init must be at least
  • 1, when itype=Nag_SingleExponential;
  • 2, when itype=Nag_BrownsExponential or Nag_LinearHolt;
  • 2+p, when itype=Nag_AdditiveHoltWinters or Nag_MultiplicativeHoltWinters.
On entry: if mode=Nag_InitialValuesSupplied, the initial values for m0, r0 and s-j, for j=0,1,,p-1, used to initialize the smoothing.
If itype=Nag_SingleExponential, init[0]=m0 and the remaining elements of init are not referenced.
If itype=Nag_BrownsExponential or Nag_LinearHolt, init[0]=m0 and init[1]=r0 and the remaining elements of init are not referenced.
If itype=Nag_AdditiveHoltWinters or Nag_MultiplicativeHoltWinters, init[0]=m0, init[1]=r0 and init[2] to init[p+1] hold the values for s-j, for j=0,1,,p-1. The remaining elements of init are not referenced.
On exit: if modeNag_ContinueAndUpdate, the values used to initialize the smoothing. These are in the same order as described above.
9:     nf IntegerInput
On entry: the number of forecasts required beyond the end of the series. Note, the one step ahead forecast is always produced.
Constraint: nf0.
10:   fv[nf] doubleOutput
On exit: y^t+f, for f=1,2,,nf, the next nf step forecasts. Where t=n, if modeNag_ContinueAndUpdate, else t is the total number of smoothed and forecast values already produced.
11:   fse[nf] doubleOutput
On exit: the forecast standard errors for the values given in fv.
12:   yhat[n] doubleOutput
On exit: y^t+1, for t=1,2,,n, the one step ahead forecast values, with yhat[i-1] being the one step ahead forecast of y[i-2].
13:   res[n] doubleOutput
On exit: the residuals, yt+1 - y^ t+1 , for t=1,2,,n.
14:   dv double *Output
On exit: the square root of the mean deviation.
On exit: the mean absolute deviation.
16:   r[dim] doubleInput/Output
Note: the dimension, dim, of the array r must be at least
  • 13, when itype=Nag_SingleExponential,Nag_BrownsExponential or Nag_LinearHolt;
  • 13+p, when itype=Nag_AdditiveHoltWinters or Nag_MultiplicativeHoltWinters.
On entry: if mode=Nag_ContinueAndUpdate, r must contain the values as returned by a previous call to nag_rand_exp_smooth (g05pmc) or nag_tsa_exp_smooth (g13amc), r need not be set otherwise.
If itype=Nag_SingleExponential, Nag_BrownsExponential or Nag_LinearHolt, only the first 13 elements of r are referenced, otherwise the first 13+p elements are referenced.
On exit: the information on the current state of the smoothing.
Constraint: if mode=Nag_ContinueAndUpdate, r must have been initialized by at least one previous call to nag_rand_exp_smooth (g05pmc) or nag_tsa_exp_smooth (g13amc) with modeNag_ContinueAndUpdate, and r should not have been changed since the last call to nag_rand_exp_smooth (g05pmc) or nag_tsa_exp_smooth (g13amc).
17:   fail NagError *Input/Output
The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6
Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.
NE_BAD_PARAM
On entry, argument value had an illegal value.
NE_ENUM_INT
On entry, p=value.
Constraint: if itype=Nag_AdditiveHoltWinters or Nag_MultiplicativeHoltWinters, p>1.
NE_INT
On entry, n=value.
Constraint: n0.
On entry, nf=value.
Constraint: nf0.
NE_INT_2
On entry, k=value and n=value.
Constraint: if mode=Nag_EstimateInitialValues and itype=Nag_AdditiveHoltWinters or Nag_MultiplicativeHoltWinters, 1kn.
NE_INT_3
On entry, k=value, 2×p=value.
Constraint: if mode=Nag_EstimateInitialValues and itype=Nag_AdditiveHoltWinters or Nag_MultiplicativeHoltWinters, 2×pk.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.
NE_MODEL_PARAMS
A multiplicative Holt–Winters model cannot be used with the supplied data.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.
NE_REAL_ARRAY
On entry, param[value]=value.
Constraint: 0.0param[value]1.0.
On entry, param[value]=value.
Constraint: if itype=Nag_BrownsExponential, 0.0<param[value]1.0.
On entry, param[value]=value.
Constraint: param[value]0.0.
On entry, the array r has not been initialized correctly.

7
Accuracy

Not applicable.

8
Parallelism and Performance

nag_tsa_exp_smooth (g13amc) is not threaded in any implementation.

9
Further Comments

Single exponential, Brown's double exponential and linear Holt smoothing methods are stable, whereas the two Holt–Winters methods can be affected by poor initial values for the seasonal components.
See also the function document for nag_rand_exp_smooth (g05pmc).

10
Example

This example smooths a time series relating to the rate of the earth's rotation about its polar axis.

10.1
Program Text

Program Text (g13amce.c)

10.2
Program Data

Program Data (g13amce.d)

10.3
Program Results

Program Results (g13amce.r)