holt_winters 0.0.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NWE3MWEzMWQ1MDFiOTRkYmMzMDM5ZWMzMjZiYTZlODMyYjI5NDdlNw==
+  data.tar.gz: !binary |-
+    ZmU3OWMxNWIwNTI4OWFmZTc5MzllZTBlODU3YTI4NzMwNzA0NWI3MQ==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    NzRlNjA0MmE4MjEzZjI0ZDg1ZTUyYTk0OTEzNTllODJmYzBlODY2NTE1OTlk
+    ZTgxY2JmNjQ5MjYzMWIyMmJkZDg3ZWE1MzkwOWE1NGM0M2E2MmNmZWMxZTk0
+    MmM2NWRjOWZhNGQyOGFjYmYxNjMxYTM5NjM0YWRjMGI4ZGI3MmY=
+  data.tar.gz: !binary |-
+    MjE2MzYwNGQxZjI4MTMxNDk4NDg0NTExMjg2ZDVmZTYyNmEzOGVjZTRmODcz
+    YmQzZmZmYjJjNWI2NzA0NmM2NDFkYTFiZjMyNmM5OTg5YzQ3YzY3MDJjNGVm
+    YWE0N2IxZjNjODc4ZjQzNmY1ZGExYjg0MzFkNzYxNDM1NjE4ZDI=

data/Gemfile

@@ -0,0 +1,3 @@
+# -*- mode: ruby; -*-
+source :rubygems
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+(The MIT-License)
+
+Copyright (c) 2011 Brandon Keene
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,76 @@
+# Holt-Winters Triple Exponential Smoothing Algorithm
+
+A Ruby port of Nishant Chandra's 
+[Java implementation](http://n-chandra.blogspot.com/2011/04/holt-winters-triple-exponential.html) 
+of the Holt-Winters smoothing algorithm.
+
+![Algorithm](http://www.itl.nist.gov/div898/handbook/pmc/section4/eqns/ts26.gif)
+
+    The equations are intended to give more weight to recent observations and less weights to observations further in the past.
+    These weights are geometrically decreasing by a constant ratio.
+    
+# Usage
+
+## forecast()
+
+It calculates the initial values and returns the forecast for __m__ periods.
+
+    # y           Time series array
+    # alpha       Level smoothing coefficient
+    # beta        Trend smoothing coefficient (increasing beta tightens fit)
+    # gamma       Seasonal smoothing coefficient
+    # period      A complete season's data consists of L periods. And we need
+    #             to estimate the trend factor from one period to the next. To
+    #             accomplish this, it is advisable to use two complete seasons;
+    #             that is, 2L periods.  
+    # m           Extrapolated future data points
+    #             - 4 quarterly
+    #             - 7 weekly
+    #             - 12 monthly
+    def forecast(y, alpha, beta, gamma, period, m)
+      # ...
+    end
+
+
+## Example
+
+This will generate a several variations of beta for a simple line:
+
+    require 'holt_winters'
+    
+    x = (0..128).to_a
+    puts x.join(',')
+    puts HoltWinters.forecast(x, 0.5, 0, 0, 12, 2).join(',')
+    puts HoltWinters.forecast(x, 0.5, 0.25, 0, 12, 2).join(',')
+    puts HoltWinters.forecast(x, 0.5, 0.5, 0, 12, 2).join(',')
+    puts HoltWinters.forecast(x, 0.5, 0.75, 0, 12, 2).join(',')
+    puts HoltWinters.forecast(x, 0.5, 1.0, 0, 12, 2).join(',')
+
+Try plotting the different lines to see how beta affects the forecast:
+
+![Chart](http://www.itl.nist.gov/div898/handbook/pmc/section4/gifs/tseries6.gif)
+
+# License
+
+(The MIT-License)
+
+Copyright (c) 2011 Brandon Keene
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/ext/holtWinters.java

@@ -0,0 +1,244 @@
+package com.fr.tsa;
+
+/**
+ * Copyright 2011 Nishant Chandra
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Given a time series, say a complete monthly data for 12 months, the Holt-Winters smoothing and forecasting 
+ * technique is built on the following formulae (multiplicative version):
+ * 
+ * St[i] = alpha * y[i] / It[i - period] + (1.0 - alpha) * (St[i - 1] + Bt[i - 1])
+ * Bt[i] = gamma * (St[i] - St[i - 1]) + (1 - gamma) * Bt[i - 1]
+ * It[i] = beta * y[i] / St[i] + (1.0 - beta) * It[i - period]
+ * Ft[i + m] = (St[i] + (m * Bt[i])) * It[i - period + m]
+ * 
+ * Note: Many authors suggest calculating initial values of St, Bt and It in a variety of ways, but
+ * some of them are incorrect e.g. determination of It parameter using regression. I have used
+ * the NIST recommended methods.
+ *   
+ * For more details, see:
+ * http://adorio-research.org/wordpress/?p=1230
+ * http://www.itl.nist.gov/div898/handbook/pmc/section4/pmc435.htm
+ * 
+ * @author Nishant Chandra
+ *
+ */
+public class HoltWintersTripleExponentialImpl {
+
+	/**
+	 * This method is the entry point. It calculates the initial values and returns the forecast
+	 * for the m periods.
+	 * 
+	 * @param y - Time series data.
+	 * @param alpha - Exponential smoothing coefficients for level, trend, seasonal components.
+	 * @param beta - Exponential smoothing coefficients for level, trend, seasonal components.
+	 * @param gamma - Exponential smoothing coefficients for level, trend, seasonal components.
+	 * @param perdiod - A complete season's data consists of L periods. And we need to estimate 
+	 * the trend factor from one period to the next. To accomplish this, it is advisable to use 
+	 * two complete seasons; that is, 2L periods. 
+	 * @param m - Extrapolated future data points.
+	 * @param debug - Print debug values. Useful for testing.
+	 * 
+     *				4 quarterly
+     *     			7 weekly.
+     *     			12 monthly
+	 */
+	public static double[] forecast(int[] y, double alpha, double beta,
+			double gamma, int period, int m, boolean debug) {
+
+		if (y == null) {
+			return null;
+		}
+
+		int seasons = y.length / period;
+		double a0 = calculateInitialLevel(y, period);
+		double b0 = calculateInitialTrend(y, period);
+		double[] initialSeasonalIndices = calculateSeasonalIndices(y, period, seasons);
+
+		if (debug) {
+			System.out.println(String.format(
+					"Total observations: %d, Seasons %d, Periods %d", y.length,
+					seasons, period));
+			System.out.println("Initial level value a0: " + a0);
+			System.out.println("Initial trend value b0: " + b0);
+			printArray("Seasonal Indices: ", initialSeasonalIndices);
+		}
+
+		double[] forecast = calculateHoltWinters(y, a0, b0, alpha, beta, gamma,
+				initialSeasonalIndices, period, m, debug);
+
+		if (debug) {
+			printArray("Forecast", forecast);
+		}
+
+		return forecast;
+	}
+	
+	/**
+	 * This method realizes the Holt-Winters equations.
+	 * 
+	 * @param y
+	 * @param a0
+	 * @param b0
+	 * @param alpha
+	 * @param beta
+	 * @param gamma
+	 * @param initialSeasonalIndices
+	 * @param period
+	 * @param m
+	 * @param debug
+	 * @return - Forecast for m periods.
+	 */
+	private static double[] calculateHoltWinters(int[] y, double a0, double b0, double alpha,
+			double beta, double gamma, double[] initialSeasonalIndices, int period, int m, boolean debug) {
+		
+		double[] St = new double[y.length];
+		double[] Bt = new double[y.length];
+		double[] It = new double[y.length];
+		double[] Ft = new double[y.length + m];
+		
+		//Initialize base values
+		St[1] = a0;
+		Bt[1] = b0;
+		   
+		for (int i = 0; i < period; i++) {
+			It[i] = initialSeasonalIndices[i];
+		}
+		
+		Ft[m] = (St[0] + (m * Bt[0])) * It[0];//This is actually 0 since Bt[0] = 0
+		Ft[m + 1] = (St[1] + (m * Bt[1])) * It[1];//Forecast starts from period + 2
+		
+		//Start calculations
+		for (int i = 2; i < y.length; i++) {
+
+			//Calculate overall smoothing
+			if((i - period) >= 0) {
+				St[i] = alpha * y[i] / It[i - period] + (1.0 - alpha) * (St[i - 1] + Bt[i - 1]);
+			} else {
+				St[i] = alpha * y[i] + (1.0 - alpha) * (St[i - 1] + Bt[i - 1]);
+			}
+			
+			//Calculate trend smoothing
+	        Bt[i] = gamma * (St[i] - St[i - 1]) + (1 - gamma) * Bt[i - 1];
+	        
+	        //Calculate seasonal smoothing
+	        if((i - period) >= 0) {
+	        	It[i] = beta * y[i] / St[i] + (1.0 - beta) * It[i - period];
+	        }
+	                                                      
+            //Calculate forecast
+	        if( ((i + m) >= period) ){
+	        	Ft[i + m] = (St[i] + (m * Bt[i])) * It[i - period + m];
+	        }
+	        
+	        if(debug){
+				System.out.println(String.format(
+						"i = %d, y = %d, S = %f, Bt = %f, It = %f, F = %f", i,
+						y[i], St[i], Bt[i], It[i], Ft[i]));
+	        }
+		}
+		
+		return Ft;
+	}
+
+	/**
+	 * See: http://robjhyndman.com/researchtips/hw-initialization/
+	 * 1st period's average can be taken. But y[0] works better.
+	 * 
+	 * @return - Initial Level value i.e. St[1]
+	 */
+	private static double calculateInitialLevel(int[] y, int period) {
+
+		/**		
+ 		double sum = 0;
+
+		for (int i = 0; i < period; i++) {
+			sum += y[i];
+		}
+		
+		return sum / period;
+		 **/
+		return y[0];
+	}
+	
+	/**
+	 * See: http://www.itl.nist.gov/div898/handbook/pmc/section4/pmc435.htm
+	 * 
+	 * @return - Initial trend - Bt[1]
+	 */
+	private static double calculateInitialTrend(int[] y, int period){
+		
+		double sum = 0;
+		
+		for (int i = 0; i < period; i++) {			
+			sum += (y[period + i] - y[i]);
+		}
+		
+		return sum / (period * period);
+	}
+	
+	/**
+	 * See: http://www.itl.nist.gov/div898/handbook/pmc/section4/pmc435.htm
+	 * 
+	 * @return - Seasonal Indices.
+	 */
+	private static double[] calculateSeasonalIndices(int[] y, int period, int seasons){
+						
+		double[] seasonalAverage = new double[seasons];
+		double[] seasonalIndices = new double[period];
+		
+		double[] averagedObservations = new double[y.length];
+		
+		for (int i = 0; i < seasons; i++) {
+			for (int j = 0; j < period; j++) {
+				seasonalAverage[i] += y[(i * period) + j];
+			}
+			seasonalAverage[i] /= period;
+		}
+		
+		for (int i = 0; i < seasons; i++) {
+			for (int j = 0; j < period; j++) {
+				averagedObservations[(i * period) + j] = y[(i * period) + j] / seasonalAverage[i];				
+			}			
+		}
+		
+		for (int i = 0; i < period; i++) {
+			for (int j = 0; j < seasons; j++) {
+				seasonalIndices[i] += averagedObservations[(j * period) + i];
+			}			
+			seasonalIndices[i] /= seasons;
+		}
+		
+		return seasonalIndices;
+	}
+	
+	/**
+	 * Utility method to pring array values.
+	 * 
+	 * @param description
+	 * @param data
+	 */
+	private static void printArray(String description, double[] data){
+		
+		System.out.println(String.format("******************* %s *********************", description));
+		
+		for (int i = 0; i < data.length; i++) {
+			System.out.println(data[i]);
+		}
+		
+		System.out.println(String.format("*****************************************************************", description));
+	}
+}

data/ext/holt_winters.c

@@ -0,0 +1,148 @@
+#include <string.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+/*
+ * Based on th R implementation
+ *
+ * a: level component
+ * b: trend component
+ * s: seasonal component
+ *
+ * Additive:
+ *
+ *   Yhat[t+h] = a[t] + h * b[t] + s[t + 1 + (h - 1) mod p],
+ *   a[t] = α (Y[t] - s[t-p]) + (1-α) (a[t-1] + b[t-1])
+ *   b[t] = β (a[t] - a[t-1]) + (1-β) b[t-1]
+ *   s[t] = γ (Y[t] - a[t]) + (1-γ) s[t-p]
+ *
+ * Multiplicative:
+ *
+ *   Yhat[t+h] = (a[t] + h * b[t]) * s[t + 1 + (h - 1) mod p],
+ *   a[t] = α (Y[t] / s[t-p]) + (1-α) (a[t-1] + b[t-1])
+ *   b[t] = β (a[t] - a[t-1]) + (1-β) b[t-1]
+ *   s[t] = γ (Y[t] / a[t]) + (1-γ) s[t-p]
+ */
+void HoltWinters (
+          double *x,
+          int    *xl,           // Time t + h
+          double *alpha,        // alpha parameter of Holt-Winters Filter.
+          double *beta,         // beta parameter of Holt-Winters Filter. If set to 0, the function will do exponential smoothing.
+          double *gamma,        // gamma parameter used for the seasonal component. If set to 0, an non-seasonal model is fitted.
+          int    *start_time,   // Time t
+          int    *seasonal,
+          int    *period,
+          double *a,            // Start value for level (a[0]).
+          double *b,            // Start value for trend (b[0]).
+          double *s,            // Vector of start values for the seasonal component (s_1[0] ... s_p[0])
+
+          /* return values */
+          double *SSE,          // The final sum of squared errors achieved in optimizing
+          double *level,        // Estimated values for the level component (size xl - t + 1)
+          double *trend,        // Estimated values for the trend component (size xl - t + 1)
+          double *season        // Estimated values for the seasonal component (size xl - t + 1)
+    )
+
+{
+    double res = 0, xhat = 0, stmp = 0;
+    int i, i0, s0;
+
+    /* copy start values to the beginning of the vectors */
+    level[0] = *a;
+    if (*beta > 0) trend[0] = *b;
+    if (*gamma > 0) memcpy(season, s, *period * sizeof(double));
+
+    for (i = *start_time - 1; i < *xl; i++) {
+        /* indices for period i */
+        i0 = i - *start_time + 2;
+        s0 = i0 + *period - 1;
+
+        /* forecast *for* period i */
+        xhat = level[i0 - 1] + (*beta > 0 ? trend[i0 - 1] : 0);
+        stmp = *gamma > 0 ? season[s0 - *period] : (*seasonal != 1);
+        if (*seasonal == 1)
+            xhat += stmp;
+        else
+            xhat *= stmp;
+
+        /* Sum of Squared Errors */
+        res   = x[i] - xhat;
+        *SSE += res * res;
+
+        /* estimate of level *in* period i */
+        if (*seasonal == 1)
+            level[i0] = *alpha       * (x[i] - stmp)
+                      + (1 - *alpha) * (level[i0 - 1] + trend[i0 - 1]);
+        else
+            level[i0] = *alpha       * (x[i] / stmp)
+                      + (1 - *alpha) * (level[i0 - 1] + trend[i0 - 1]);
+
+        /* estimate of trend *in* period i */
+        if (*beta > 0)
+            trend[i0] = *beta        * (level[i0] - level[i0 - 1])
+                      + (1 - *beta)  * trend[i0 - 1];
+
+        /* estimate of seasonal component *in* period i */
+        if (*gamma > 0) {
+            if (*seasonal == 1)
+                season[s0] = *gamma       * (x[i] - level[i0])
+                           + (1 - *gamma) * stmp;
+            else
+                season[s0] = *gamma       * (x[i] / level[i0])
+                       + (1 - *gamma) * stmp;
+        }
+    }
+}
+
+int main() {
+    // US population in millions
+    double series[] = {3.93, 5.31, 7.24, 9.64, 12.90, 17.10, 23.20, 31.40, 39.80, 50.20, 62.90, 76.00, 92.00, 105.70, 122.80, 131.70, 151.30, 179.30, 203.20};
+
+    int forecast = 19;
+    double alpha = 0.9999208;
+    double beta = 0;
+    double gamma = 0;
+    int start_time = 2;
+    int seasonal = 0;
+    int period = 0;
+    double a0 = series[0];
+    double b0 = 0;
+    double s[] = {};
+
+    double errors;
+    int nb_computations = forecast - start_time - 1;
+    double *estimated_level = malloc(nb_computations * sizeof(double));
+    double *estimated_trend = malloc(nb_computations * sizeof(double));
+    double *estimated_season = malloc(nb_computations * sizeof(double));
+
+    HoltWinters(
+        series,
+        &forecast,
+        &alpha,
+        &beta,
+        &gamma,
+        &start_time,
+        &seasonal,
+        &period,
+        &a0,
+        &b0,
+        s,
+        &errors,
+        estimated_level,
+        estimated_trend,
+        estimated_season
+    );
+
+    int i = 0;
+    int first_year = 1800;
+    printf("Estimated:\n");
+    for (i = 0; i < nb_computations; i++) {
+        printf("\tyear = %d, level: %f, trend: %f\n", first_year + i * 10, estimated_level[i], estimated_trend[i]);
+    }
+
+    free(estimated_level);
+    free(estimated_trend);
+    free(estimated_season);
+
+    return 0;
+}

data/ext/holt_winters_R_language.c

@@ -0,0 +1,93 @@
+/*  R : A Computer Language for Statistical Data Analysis
+ *
+ *  Copyright (C) 2003-7  The R Development Core Team
+ *
+ *  This program is free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation; either version 2 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program; if not, a copy is available at
+ *  http://www.r-project.org/Licenses/.
+ */
+
+#include <R.h>
+#include "ts.h"
+#include <stdlib.h>
+
+void HoltWinters (
+    double *x,
+		  int    *xl,
+		  double *alpha,
+		  double *beta,
+		  double *gamma,
+		  int    *start_time,
+		  int    *seasonal,
+		  int    *period,
+		  double *a,
+		  double *b,
+		  double *s,
+
+		  /* return values */
+		  double *SSE,
+		  double *level,
+		  double *trend,
+		  double *season
+    )
+	
+{
+    double res = 0, xhat = 0, stmp = 0;
+    int i, i0, s0;
+
+    /* copy start values to the beginning of the vectors */
+    level[0] = *a;
+    if (*beta > 0) trend[0] = *b;
+    if (*gamma > 0) memcpy(season, s, *period * sizeof(double));
+    
+    for (i = *start_time - 1; i < *xl; i++) {
+	/* indices for period i */
+	i0 = i - *start_time + 2;
+	s0 = i0 + *period - 1;
+	
+        /* forecast *for* period i */
+        xhat = level[i0 - 1] + (*beta > 0 ? trend[i0 - 1] : 0);
+	stmp = *gamma > 0 ? season[s0 - *period] : (*seasonal != 1);
+	if (*seasonal == 1)
+	    xhat += stmp;
+	else
+	    xhat *= stmp;
+
+	/* Sum of Squared Errors */
+	res   = x[i] - xhat;
+	*SSE += res * res;
+
+	/* estimate of level *in* period i */
+	if (*seasonal == 1)
+	    level[i0] = *alpha       * (x[i] - stmp)
+		      + (1 - *alpha) * (level[i0 - 1] + trend[i0 - 1]);
+	else
+	    level[i0] = *alpha       * (x[i] / stmp)
+		      + (1 - *alpha) * (level[i0 - 1] + trend[i0 - 1]);
+
+	/* estimate of trend *in* period i */
+	if (*beta > 0)
+	    trend[i0] = *beta        * (level[i0] - level[i0 - 1])
+		      + (1 - *beta)  * trend[i0 - 1];
+
+	/* estimate of seasonal component *in* period i */
+	if (*gamma > 0) {
+	    if (*seasonal == 1)
+		season[s0] = *gamma       * (x[i] - level[i0])
+ 		           + (1 - *gamma) * stmp;
+	    else
+		season[s0] = *gamma       * (x[i] / level[i0])
+			   + (1 - *gamma) * stmp;
+	}
+    }
+}

data/holt_winters.gemspec

@@ -0,0 +1,22 @@
+# -*- mode: ruby; encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "holt_winters/version"
+
+Gem::Specification.new do |s|
+  s.name        = "holt_winters"
+  s.version     = HoltWinters::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Brandon Keene"]
+  s.email       = ["bkeene@gmail.com"]
+  s.homepage    = ""
+  s.summary     = %q{Holt-Winters Triple Exponential Smoothing}
+
+  s.rubyforge_project = "holt_winters"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "rspec", "~> 2.6.0"
+end

data/lib/holt_winters.rb

@@ -0,0 +1,135 @@
+#  Given a time series, say a complete monthly data for 12 months, the Holt-Winters smoothing and forecasting
+#  technique is built on the following formulae (multiplicative version):
+#
+#  St[i] = alpha * y[i] / It[i - period] + (1.0 - alpha) * (St[i - 1] + Bt[i - 1])
+#  Bt[i] = gamma * (St[i] - St[i - 1]) + (1 - gamma) * Bt[i - 1]
+#  It[i] = beta * y[i] / St[i] + (1.0 - beta) * It[i - period]
+#  Ft[i + m] = (St[i] + (m * Bt[i])) * It[i - period + m]
+#
+#  Note: Many authors suggest calculating initial values of St, Bt and It in a variety of ways, but
+#  some of them are incorrect e.g. determination of It parameter using regression. I have used
+#  the NIST recommended methods.
+#
+#  For more details, see:
+#  http://adorio-research.org/wordpress/?p=1230
+#  http://www.itl.nist.gov/div898/handbook/pmc/section4/pmc435.htm
+#
+module HoltWinters
+  class << self
+    #  Calculate initial values and return the forecast for m periods.
+    #
+    #  y           Time series array
+    #  alpha       Level smoothing coefficient
+    #  beta        Trend smoothing coefficient (increasing beta tightens fit)
+    #  gamma       Seasonal smoothing coefficient
+    #  period      A complete season's data consists of L periods. And we need
+    #              to estimate the trend factor from one period to the next. To
+    #              accomplish this, it is advisable to use two complete seasons;
+    #              that is, 2L periods.
+    #  m           Extrapolated future data points
+    #              - 4 quarterly
+    #              - 7 weekly
+    #              - 12 monthly
+    #
+    def forecast(y, alpha, beta, gamma, period, m)
+      return nil if y.empty?
+
+      seasons = y.size / period
+      a0 = initial_level(y, period)
+      b0 = initial_trend(y, period)
+
+      seasonal = seasonal_indicies(y, period, seasons)
+
+      holt_winters(y, a0, b0, alpha, beta, gamma, seasonal, period, m);
+    end
+
+    def holt_winters(y, a0, b0, alpha, beta, gamma, seasonal, period, m)
+      st = Array.new(y.length, 0.0)
+      bt = Array.new(y.length, 0.0)
+      it = Array.new(y.length, 0.0)
+      ft = Array.new(y.length + m, 0.0)
+
+      st[1] = a0
+      bt[1] = b0
+
+      (0..period - 1).each do |i|
+        it[i] = seasonal[i]
+      end
+
+      ft[m] = (st[0] + (m * bt[0])) * it[0] # This is actually 0 since bt[0] = 0
+      ft[m + 1] = (st[1] + (m * bt[1])) * it[1] # Forecast starts from period + 2
+
+      (2..(y.size - 1)).each do |i|
+        # Calculate overall smoothing
+        if (i - period) >= 0
+         st[i] = alpha * y[i] / it[i - period] + (1.0 - alpha) * (st[i - 1] + bt[i - 1])
+        else
+          st[i] = alpha * y[i] + (1.0 - alpha) * (st[i - 1] + bt[i - 1])
+        end
+
+        # Calculate trend smoothing
+        bt[i] = gamma * (st[i] - st[i - 1]) + (1 - gamma) * bt[i - 1]
+
+        # Calculate seasonal smoothing
+        if (i - period) >= 0
+          it[i] = beta * y[i] / st[i] + (1.0 - beta) * it[i - period]
+        end
+
+        # Calculate forecast
+        if (i + m) >= period
+          ft[i + m] = (st[i] + (m * bt[i])) * it[i - period + m]
+        end
+      end
+
+      ft
+    end
+
+    # See: http://robjhyndman.com/researchtips/hw-initialization/
+    # 1st period's average can be taken. But y[0] works better.
+    def initial_level(y, period)
+      y.first
+    end
+
+
+    # See: http://www.itl.nist.gov/div898/handbook/pmc/section4/pmc435.htm
+    def initial_trend(y, period)
+      sum = 0
+
+      (0..period - 1).each do |i|
+        sum += (y[period + i] - y[i])
+      end
+
+      sum / (period * period)
+    end
+
+
+    # See: http://www.itl.nist.gov/div898/handbook/pmc/section4/pmc435.htm
+    def seasonal_indicies(y, period, seasons)
+      seasonal_average = Array.new(seasons, 0.0)
+      seasonal_indices = Array.new(period, 0.0)
+      averaged_observations = Array.new(y.size, 0.0)
+
+      (0..seasons - 1).each do |i|
+        (0..period - 1).each do |j|
+          seasonal_average[i] += y[(i * period) + j]
+        end
+        seasonal_average[i] /= period
+      end
+
+      (0..seasons - 1).each do |i|
+        (0..period - 1).each do |j|
+          averaged_observations[(i * period) + j] = y[(i * period) + j] / seasonal_average[i]
+        end
+      end
+
+      (0..period - 1).each do |i|
+        (0..seasons - 1).each do |j|
+          seasonal_indices[i] += averaged_observations[(j * period) + i]
+        end
+        seasonal_indices[i] /= seasons
+      end
+
+      seasonal_indices
+    end
+  end
+end

data/lib/holt_winters/version.rb

@@ -0,0 +1,3 @@
+module HoltWinters
+  VERSION = "0.0.0"
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: holt_winters
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Brandon Keene
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-10-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.6.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.6.0
+description: 
+email:
+- bkeene@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- README.md
+- ext/holtWinters.java
+- ext/holt_winters.c
+- ext/holt_winters_R_language.c
+- holt_winters.gemspec
+- lib/holt_winters.rb
+- lib/holt_winters/version.rb
+homepage: ''
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: holt_winters
+rubygems_version: 2.0.7
+signing_key: 
+specification_version: 4
+summary: Holt-Winters Triple Exponential Smoothing
+test_files: []