hwTimeSeries¶

Calculates parameters and forecasts using the Holt-Winters Multiplicative or Additive forecasting method for seasonal data.

Synopsis¶

hwTimeSeries (nseason, y)

Required Arguments¶

int nseason (Input): The number of time points in a season, or the length of the season. The function requires that 2 ≤ nseason ≤ nObs unless one of the non‑seasonal options is specified, in which case nseason is ignored. See the optional arguments for details.
float y[] (Input): An array of length nObs containing the values of the time series.

Return Value¶

An array of length (nObs + 1)3 containing the values of the smoothing parameters followed by the level, trend, and seasonal component sequences. Note that if nonseasonalTrend is specified, the array is of length (nObs + 1)2 and if nonseasonalConstant is specified, it is of length (nObs + 1).

Optional Arguments¶

additive, int (Input)

Specifies the use of the Multiplicative or Additive time series model. additive must be 1 or 0. If additive = 1 the Additive model is used.

Default: additive = 0. The Multiplicative model is the default.

seriesIncrement, int (Input)

The constant stride through the series data y. The length of y must be at least (nObs‑1)×|seriesIncrement|+1. When seriesIncrement < 0, the series is incremented in reverse order beginning at index nObs(‑seriesIncrement)‑1.

Default: seriesIncrement = 1.

nonseasonalTrend, (Input)

Remove the seasonal component and fit only the level and trend. If present, the models involve only the level (α) and trend (β) parameters. The method is equivalent to double exponential smoothing.

Default: The method includes all three components

nonseasonalConstant, (Input)

Remove the trend and the seasonal components and fit only the level. If present, the models involve only the level (α) parameter. The method is simple exponential smoothing.

Default: The method includes all three components.

useParams, float[] (Input)

An array containing the values of the smoothing parameters for the level (α), the trend (β), and the seasonal (γ) component sequences. The array should be length 3 unless nonseasonalTrend is specified, in which case it is of length 2 containing values for level (α) and the trend (β). Likewise, if nonseasonalConstant is specified, useParams is of length 1 and contains the value for the level parameter (α) only.

Default: Parameter values are selected by minimizing the mean squared one step ahead forecast error.

nSamples, int (Input)

Number of evaluations of the residual norm that are sampled to obtain starting values for the smoothing parameters, (α, β, γ).

Default: nsamples = nObs.

bounds, float[] (Input)

An array of length 6 that contains the lower and upper bounds for each of the smoothing parameters, (α, β, γ). The three lower bounds are followed by the 3 upper bounds. Note that the lower and upper bounds must be in the interval [0,1], inclusive. The array is ignored if useParams is used.

Default: Lower bounds are all 0 and upper bounds are all 1.

initInput, int (Input)

initInput must be 1 or 0. If initInput = 1, the initial values for the level, trend, and seasonal component sequences are provided in the user array, sequences. The values must be stored in rows 1, 2, …, nseason of the return array.

Default: initInput = 0. Initial values are computed by the function.

forecastConfidence, float (Input)

This value provides the confidence level to use in the calculation of the prediction intervals. If this argument is present and valid (0.0 < forecastConfidence < 100.0), prediction intervals are provided for each forecast.

Default: Prediction intervals are not provided.

forecasts, nforecasts, forecasts (Input/Output)

int nforecasts (Input): The number of forecasts desired past the series data.
float forecasts (Output): An array of length nforecasts. The value of the i-th row is the forecast (i + 1) steps past the series data. If the option forecastConfidence is used, the array will be of length nforecasts×3 and the value of the i‑th row is the forecast (i+1) steps ahead followed by the prediction interval lower and upper bounds.
seriesSmoothed (Output): The array of length nObs containing the fitted series values.
cov (Output): An array containing the variance-covariance matrix of the smoothing parameters estimated by minimizing the mean squared forecast error. The length of the array is 3 × 3 unless nonseasonalTrend is specified, in which case it is 2 × 2, or unless nonseasonalConstant is specified, in which case it is 1 × 1. cov is ignored when the option useParams is present.
ssResidual (Output): The sum of squares of the one step ahead forecast errors.

Description¶

Function hwTimeSeries performs the Holt-Winters forecasting method to an equally spaced time series, \(\{y_t\}\) where N = nObs and \(t =1,\ldots,N\) (or \(t=0,1\cdot\mathtt{incy},2\cdot\mathtt{incy}, \ldots,K\cdot\mathtt{incy}\) where \(K\cdot\mathtt{incy}\leq N\) and \(\mathtt{incy}\geq 1\) ). The Holt-Winters procedure fits three component sequences known as the level, the trend, and the seasonal sequence. There are two formulations, depending on whether the seasonal component of the time series is thought to be additive or multiplicative. The seasonal component depends on the length of the season, nseason = s, where \(s=2,\ldots,N\).

Holt-Winters Additive Model

\(L_t=\alpha\left( y_t-S_{t-s} \right)+(1-\alpha) \left( L_{t-1}+b_{t-1} \right)\)	the level sequence
\(b_t=\beta\left( L_t-L_{t-1} \right)+(1-\beta) b_{t-1}\)	the trend sequence
\(S_t=\gamma\left(y_t-L_t\right)+(1-\gamma)S_{t-s}\)	the seasonal sequence
\(F_{t+k}=L_t+kb_t+S_{t+k-s}\)	the forecast sequence

Holt-Winters Multiplicative Model

\(L_t=\alpha\left(y_t/S_{t-s}\right)+(1-\alpha) \left(L_{t-1}+b_{t-1}\right)\)	the level sequence
\(b_t=\beta\left( L_t-L_{t-1} \right)+(1-\beta) b_{t-1}\)	the trend sequence
\(S_t=\gamma\left(y_t/L_t\right)+(1-\gamma) S_{t-s}\)	the seasonal sequence
\(F_{t+k}=\left(L_t+kb_t\right)S_{t+k-s}\)	the forecast sequence

Note that without a seasonal component, both the additive and multiplicative formulations reduce to the same methods. (The seasonal sequence is set to 1 for the multiplicative model, and identically 0 for the additive model.)

Default Starting Values

Initial values are required for these sequences. The software allows the user code to define these initial values (see optional argument initInput). If they are not provided, then the first two seasons of data are used:

\(L_s=\tfrac{1}{s} \sum_{i=1}^{s} y_i,s>1\)
\(b_s=\tfrac{1}{s} \sum_{i=1}^{s} \tfrac{\left(y_{i+s}-y_i\right)}{s},s>1\)
\(S_i=y_i/L_s \text{ or } y_i-L_s,i=1,\ldots,s\)	(Multiplicative or Additive)

The smoothing parameters (α, β, γ) are each in the interval [0,1] and can be specified by the user (see optional argument useParams), or automatically set by minimizing the within sample one-step ahead mean squared forecast error. Note that this objective function is not necessarily convex and solutions will depend on starting values. See Chatfield and Yar (1988) for further discussion. Starting values for (α, β, γ) are obtained by minimizing the mean squared error over nsamples bootstrap samples of the time series. Experiments suggest that this approach helps prevent poor starting values. Note, that solutions may vary for different settings of the number of random samples, nsamples.

The return value of the hwTimeSeries is the array of length 3(N + 1) = 3(nObs + 1) containing the smoothing parameter values on the first row, followed by the calculated level, trend, and seasonal sequences. When N = nObs and s = nseason, the format of the return value is as follows:

Series Storage
Row	Value
0	\[\hat{\alpha}\]	\[\hat{\beta}\]	\[\hat{y}\]
1	0	0	\(S_1\)
2	0	0	\(S_2\)
⋮	⋮	⋮	⋮
s	\(L_s\)	\(b_s\)	\(S_s\)
s+1	\(L_{s+1}\)	\(b_{s+1}\)	\(S_{s+1}\)
⋮	⋮	⋮	⋮
N	\(L_N\)	\(b_N\)	\(S_N\)

If one of the nonseasonal options is specified, the return value will be of length 2(nObs + 1) or (nObs + 1) accordingly.

The variance-covariance matrix for the parameters (α, β, γ) is

\[\mathrm{cov} = \frac{\Sigma e_i^2}{n-2s-3}\left(J^T J\right)^{-1}\]

where \(e_i\) is the one-step-ahead forecast error, and \(J\) is the Jacobian matrix of the series using the forecast model and calculating forecasts one step ahead of each datum. Prediction intervals are calculated following Chatfield and Yar (1991).

Example¶

A series of nObs = 12 seasonal data values are analysed using the Multiplicative and the Additive Holt-Winters method. The season size is nseason = 4. The objective is to predict one season ahead, nforecasts = 4 using each method. The forecasts and prediction interval lower and upper bounds are returned. The mean sum of squares of the one-step ahead forecast errors is shown to be smallest using the Multiplicative model.

from __future__ import print_function
from numpy import *
from pyimsl.stat.hwTimeSeries import hwTimeSeries
from pyimsl.stat.writeMatrix import writeMatrix
from pyimsl.stat.free import free

NOBS = 12
NSEASON = 4


y = [23, 25, 36, 31, 26, 28, 48, 36, 31, 42, 53, 43]
nforecasts = NSEASON
nvars = 3
forecasts = {'nforecasts': nforecasts}
ysmoothed = []
ss = []
# Compute the time series and forecasts
# using the Multiplicative model.
confidence = 95.0
seriesm = hwTimeSeries(NSEASON, y,
                       forecastConfidence=confidence,
                       forecasts=forecasts,
                       seriesSmoothed=ysmoothed,
                       ssResidual=ss)


writeMatrix(" Input time series ", y)
writeMatrix(" Smoothed Multiplicative series ", ysmoothed)
writeMatrix(" Parameters and internal sequences ", seriesm.reshape(13, 3))
writeMatrix("Multiplicative forecasts with"
            " 95% prediction interval", forecasts['forecasts'])
print("MSS - Multiplicative %3.2f " % (ss[0] / (NOBS - NSEASON)))
free(seriesm)

# Compute the time series and forecasts
# using the Additive model.

forecasts1 = {'nforecasts': nforecasts}
ysmoothed1 = []
ss1 = []
seriesa = hwTimeSeries(NSEASON, y,
                       forecasts=forecasts1,
                       seriesSmoothed=ysmoothed1,
                       ssResidual=ss1,
                       forecastConfidence=confidence,
                       additive=True)

writeMatrix(" Smoothed Additive series ", ysmoothed1)
writeMatrix(" Parameters and internal sequences ", seriesa.reshape(13, 3))
writeMatrix("Additive forecasts with 95% prediction interval",
            forecasts1['forecasts'])
print("MSS - Additive %3.2f " % (ss1[0] / (float)(NOBS - NSEASON)))

Output¶

MSS - Multiplicative 15.35 
MSS - Additive 21.18 
 
                              Input time series 
          1            2            3            4            5            6
         23           25           36           31           26           28
 
          7            8            9           10           11           12
         48           36           31           42           53           43
 
                       Smoothed Multiplicative series 
          1            2            3            4            5            6
      23.00        25.00        36.00        31.00        24.15        27.65
 
          7            8            9           10           11           12
      41.77        38.03        30.43        33.72        54.50        45.24
 
    Parameters and internal sequences 
              1            2            3
 1         0.04         1.00         0.44
 2         0.00         0.00         0.80
 3         0.00         0.00         0.87
 4         0.00         0.00         1.25
 5        28.75         1.44         1.08
 6        30.28         1.53         0.83
 7        31.82         1.54         0.87
 8        33.54         1.73         1.33
 9        35.20         1.66         1.05
10        36.89         1.68         0.83
11        38.93         2.04         0.96
12        40.93         2.00         1.31
13        42.85         1.92         1.03
 
Multiplicative forecasts with 95% prediction interval
                   1            2            3
      1        37.25        27.54        46.96
      2        44.99        35.24        54.74
      3        63.91        53.99        73.83
      4        52.14        42.17        62.11
 
                          Smoothed Additive series 
          1            2            3            4            5            6
      23.00        25.00        36.00        31.00        23.00        26.32
 
          7            8            9           10           11           12
      38.58        38.54        34.05        35.73        56.63        43.83
 
    Parameters and internal sequences 
              1            2            3
 1         0.27         0.64         1.00
 2         0.00         0.00        -5.75
 3         0.00         0.00        -3.75
 4         0.00         0.00         7.25
 5        28.75         0.00         2.25
 6        29.56         0.52        -3.56
 7        30.52         0.81        -2.52
 8        33.86         2.43        14.14
 9        35.61         1.99         0.39
10        36.78         1.47        -5.78
11        39.94         2.55         2.06
12        41.51         1.92        11.49
13        43.21         1.78        -0.21
 
Additive forecasts with 95% prediction interval
                1            2            3
   1        39.21        27.80        50.62
   2        48.84        36.37        61.31
   3        60.05        45.74        74.35
   4        50.13        33.24        67.01

Warning Errors¶

IMSLS_HW_COV_NOT_EST The covariance matrix could not be estimated. The parameter estimates may be at the upper or lower bound.

Fatal Errors¶

`IMSLS_HW_SEASON_SIZE`	The number for a Holt-Winters series season length must be > = 2. Input value is =#.
`IMSLS_HW_SERIES_SIZE`	The number of observations for a Holt-Winters input series must be “`nObs`” > 2`\*`“`nseason`”+ 3. Now have “`nObs`” = # and “`nseason`”=#.
`IMSLS_HW_SERIES_SIGN`	The values of the input series, using the Holt-Winters Multiplicative method, must be positive. The series entry with index = # now has the non‑positive value #.