% File src/library/stats/man/HoltWinters.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2018 R Core Team
% Distributed under GPL 2 or later

\name{HoltWinters}
\alias{HoltWinters}
\alias{print.HoltWinters}
\alias{residuals.HoltWinters}
\title{Holt-Winters Filtering}
\description{
  Computes Holt-Winters Filtering of a given time series.
  Unknown parameters are determined by minimizing the squared
  prediction error.
}
\usage{
HoltWinters(x, alpha = NULL, beta = NULL, gamma = NULL,
            seasonal = c("additive", "multiplicative"),
            start.periods = 2, l.start = NULL, b.start = NULL,
            s.start = NULL,
            optim.start = c(alpha = 0.3, beta = 0.1, gamma = 0.1),
            optim.control = list())
}
\arguments{
  \item{x}{An object of class \code{ts}}
  \item{alpha}{\eqn{alpha} parameter of Holt-Winters Filter.}
  \item{beta}{\eqn{beta} parameter of Holt-Winters Filter. If set to
    \code{FALSE}, the function will do exponential smoothing.}
  \item{gamma}{\eqn{gamma} parameter used for the seasonal component.
    If set to \code{FALSE}, an non-seasonal model is fitted.}
  \item{seasonal}{Character string to select an \code{"additive"}
    (the default) or \code{"multiplicative"} seasonal model. The first
    few characters are sufficient. (Only takes effect if
    \code{gamma} is non-zero).}
  \item{start.periods}{Start periods used in the autodetection of start
    values. Must be at least 2.}
  \item{l.start}{Start value for level (a[0]).}
  \item{b.start}{Start value for trend (b[0]).}
  \item{s.start}{Vector of start values for the seasonal component
    (\eqn{s_1[0] \ldots s_p[0]}{s_1[0] \dots s_p[0]})}
  \item{optim.start}{Vector with named components \code{alpha},
    \code{beta}, and \code{gamma} containing the starting values for the
    optimizer. Only the values needed must be specified.  Ignored in the
    one-parameter case.}
  \item{optim.control}{Optional list with additional control parameters
    passed to \code{optim} if this is used.  Ignored in the
    one-parameter case.}
}
\details{
  The additive Holt-Winters prediction function (for time series with
  period length p) is
  \deqn{\hat Y[t+h] = a[t] + h b[t] + s[t - p + 1 + (h - 1) \bmod p],}{
    Yhat[t+h] = a[t] + h * b[t] + s[t - p + 1 + (h - 1) mod p],}
  where \eqn{a[t]}, \eqn{b[t]} and \eqn{s[t]} are given by
  \deqn{a[t] = \alpha (Y[t] - s[t-p])  + (1-\alpha) (a[t-1] + b[t-1])}{
  a[t] = \alpha (Y[t] - s[t-p])  + (1-\alpha) (a[t-1] + b[t-1])}
  \deqn{b[t] = \beta (a[t] -a[t-1]) + (1-\beta)  b[t-1]}{
  b[t] = \beta (a[t] - a[t-1]) + (1-\beta) b[t-1]}
  \deqn{s[t] = \gamma (Y[t] - a[t])   + (1-\gamma) s[t-p]}{
  s[t] = \gamma (Y[t] - a[t]) + (1-\gamma) s[t-p]}

  The multiplicative Holt-Winters prediction function (for time series
  with period length p) is
  \deqn{\hat Y[t+h] = (a[t] + h b[t]) \times s[t - p + 1 + (h - 1) \bmod p].}{
    Yhat[t+h] = (a[t] + h * b[t]) * s[t - p + 1 + (h - 1) mod p],}
  where \eqn{a[t]}, \eqn{b[t]} and \eqn{s[t]} are given by
  \deqn{a[t] = \alpha (Y[t] / s[t-p])  + (1-\alpha) (a[t-1] + b[t-1])}{
  a[t] = \alpha (Y[t] / s[t-p])  + (1-\alpha) (a[t-1] + b[t-1])}
  \deqn{b[t] = \beta (a[t] - a[t-1]) + (1-\beta) b[t-1]}{
  b[t] = \beta (a[t] - a[t-1]) + (1-\beta) b[t-1]}
  \deqn{s[t] = \gamma (Y[t] / a[t])   + (1-\gamma) s[t-p]}{
  s[t] = \gamma  (Y[t] / a[t])  + (1-\gamma) s[t-p]}
  The data in \code{x} are required to be non-zero for a multiplicative
  model, but it makes most sense if they are all positive.

  The function tries to find the optimal values of \eqn{\alpha} and/or
  \eqn{\beta} and/or \eqn{\gamma} by minimizing the squared one-step
  prediction error if they are \code{NULL} (the default). \code{optimize}
  will be used for the single-parameter case, and \code{optim} otherwise.

  For seasonal models, start values for \code{a}, \code{b} and \code{s}
  are inferred by performing a simple decomposition in trend and
  seasonal component using moving averages (see function
  \code{\link{decompose}}) on the \code{start.periods} first periods (a simple
  linear regression on the trend component is used for starting level
  and trend). For level/trend-models (no seasonal component), start
  values for \code{a} and \code{b} are \code{x[2]} and \code{x[2] -
  x[1]}, respectively. For level-only models (ordinary exponential
  smoothing), the start value for \code{a} is \code{x[1]}.
}
\value{
  An object of class \code{"HoltWinters"}, a list with components:
  \item{fitted}{A multiple time series with one column for the
    filtered series as well as for the level, trend and seasonal
    components, estimated contemporaneously (that is at time t and not
    at the end of the series).}
  \item{x}{The original series}
  \item{alpha}{alpha used for filtering}
  \item{beta}{beta used for filtering}
  \item{gamma}{gamma used for filtering}
  \item{coefficients}{A vector with named components \code{a, b, s1, ..., sp}
    containing the estimated values for the level, trend and seasonal
    components}
  \item{seasonal}{The specified \code{seasonal} parameter}
  \item{SSE}{The final sum of squared errors achieved in optimizing}
  \item{call}{The call used}
}
\references{
  C. C. Holt (1957)
  Forecasting seasonals and trends by exponentially weighted moving averages,
  \emph{ONR Research Memorandum, Carnegie Institute of Technology} \bold{52}.
  (reprint at \url{https://doi.org/10.1016/j.ijforecast.2003.09.015}).

  P. R. Winters (1960).
  Forecasting sales by exponentially weighted moving averages.
  \emph{Management Science}, \bold{6}, 324--342.
  \doi{10.1287/mnsc.6.3.324}.
}
\author{
  David Meyer \email{David.Meyer@wu.ac.at}
}
\seealso{
  \code{\link{predict.HoltWinters}}, \code{\link{optim}}.
}

% Differences seen on 32-bit Linux at -O3
\examples{
\dontshow{od <- options(digits = 5)}
require(graphics)

## Seasonal Holt-Winters
(m <- HoltWinters(co2))
plot(m)
plot(fitted(m))

(m <- HoltWinters(AirPassengers, seasonal = "mult"))
plot(m)

## Non-Seasonal Holt-Winters
x <- uspop + rnorm(uspop, sd = 5)
m <- HoltWinters(x, gamma = FALSE)
plot(m)

## Exponential Smoothing
m2 <- HoltWinters(x, gamma = FALSE, beta = FALSE)
lines(fitted(m2)[,1], col = 3)
\dontshow{options(od)}
}
\keyword{ts}