net.sourceforge.openforecast.models
Class AbstractTimeBasedModel

java.lang.Object
  net.sourceforge.openforecast.models.AbstractForecastingModel
      net.sourceforge.openforecast.models.AbstractTimeBasedModel

All Implemented Interfaces:

ForecastingModel

Direct Known Subclasses:

DoubleExponentialSmoothingModel, SimpleExponentialSmoothingModel, TripleExponentialSmoothingModel, WeightedMovingAverageModel

public abstract class AbstractTimeBasedModel
extends AbstractForecastingModel

A time based forecasting model is the base class that implements much of the common code for models based on a time series. In particular, it was designed to support the needs of the Weighted Moving Average, as well as the Single, Double and Triple Exponential Smoothing models.

These models have an advantage over other forecasting models in that they smooth out peaks and troughs (or valleys) in a set of observations. However, they also have several disadvantages. In particular these models do not produce an actual equation. Therefore, they often are not all that useful as medium-long range forecasting tools. They can only reliably be used to forecast a few periods into the future.

Since:

0.4

Author:

Steven R. Gould

Field Summary

Fields inherited from class net.sourceforge.openforecast.models.AbstractForecastingModel

accuracyIndicators, initialized

Constructor Summary

AbstractTimeBasedModel()
Constructs a new time based forecasting model.

AbstractTimeBasedModel(String timeVariable)
Deprecated. As of 0.4, replaced by AbstractTimeBasedModel(java.lang.String).

Method Summary

double	forecast(DataPoint dataPoint) Using the current model parameters (initialized in init), apply the forecast model to the given data point.
protected abstract double	forecast(double timeValue) Returns the forecast value of the dependent variable for the given value of the independent time variable.
String	getForecastType() Returns a one or two word name of this type of forecasting model.
protected double	getForecastValue(double timeValue) Returns the forecast value for the dependent variable for the given value of the independent time variable.
String	getIndependentVariable() Returns the independent variable - or the time variable - used in this model.
double	getMaximumTimeValue() Returns the maximum value of the independent time variable currently forecast by this model.
double	getMinimumTimeValue() Returns the minimum value of the independent time variable currently forecast by this model.
protected abstract int	getNumberOfPeriods() Returns the current number of periods used in this model.
protected double	getObservedValue(double timeValue) Returns the observed value of the dependent variable for the given value of the independent time variable.
protected double	getTimeInterval() Returns the current time interval between observations.
String	getTimeVariable() Returns the name of the independent variable representing the time value used by this model.
void	init(DataSet dataSet) Used to initialize the time based model.
protected void	initTimeVariable(DataSet dataSet) Initializes the time variable from the given data set.
String	toString() This should be overridden to provide a textual description of the current forecasting model including, where possible, any derived parameters used.

Methods inherited from class net.sourceforge.openforecast.models.AbstractForecastingModel

calculateAccuracyIndicators, forecast, getAIC, getBias, getMAD, getMAPE, getMSE, getSAE

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface net.sourceforge.openforecast.ForecastingModel

getNumberOfPredictors

Constructor Detail

AbstractTimeBasedModel

public AbstractTimeBasedModel()

Constructs a new time based forecasting model. For a valid model to be constructed, you should call init and pass in a data set containing a series of data points. The data set should also have the time variable initialized to the independent time variable name.

AbstractTimeBasedModel

public AbstractTimeBasedModel(String timeVariable)

Deprecated. As of 0.4, replaced by AbstractTimeBasedModel(java.lang.String).

Constructs a new time based forecasting model, using the named variable as the independent (time) variable.

Parameters:

timeVariable - the name of the independent variable to use as the time variable in this model.

Method Detail

getNumberOfPeriods

protected abstract int getNumberOfPeriods()

Returns the current number of periods used in this model. This is also the minimum number of periods required in order to produce a valid forecast. Since this varies depending on the details of the model, any subclass must override this to provide the correct information.

Returns:

the minimum number of periods used in this model.

init

public void init(DataSet dataSet)

Used to initialize the time based model. This method must be called before any other method in the class. Since the time based model does not derive any equation for forecasting, this method uses the input DataSet to calculate forecast values for all values of the independent time variable within the initial data set.

Parameters:

dataSet - a data set of observations that can be used to initialize the forecasting parameters of the forecasting model.

initTimeVariable

protected void initTimeVariable(DataSet dataSet)
                         throws IllegalArgumentException

Initializes the time variable from the given data set. If the data set does not have a time variable explicitly defined, then provided there is only one independent variable defined for the data set that is used as the time variable. If more than one independent variable is defined for the data set, then it is not possible to take an educated guess at which one is the time variable. In this case, an IllegalArgumentException will be thrown.

Parameters:

dataSet - the data set to use to initialize the time variable.

Throws:

IllegalArgumentException - If more than one independent variable is defined for the data set and no time variable has been specified. To correct this, be sure to explicitly specify the time variable in the data set passed to init(net.sourceforge.openforecast.DataSet).

forecast

public double forecast(DataPoint dataPoint)
                throws IllegalArgumentException

Using the current model parameters (initialized in init), apply the forecast model to the given data point. The data point must have a valid value for the independent variable. Upon return, the value of the dependent variable will be updated with the forecast value computed for that data point.

Parameters:

dataPoint - the data point for which a forecast value (for the dependent variable) is required.

Returns:

the same data point passed in but with the dependent value updated to contain the new forecast value.

Throws:

ModelNotInitializedException - if forecast is called before the model has been initialized with a call to init.

IllegalArgumentException - if the forecast period specified by the dataPoint is invalid with respect to the historical data provided.

forecast

protected abstract double forecast(double timeValue)
                            throws IllegalArgumentException

Returns the forecast value of the dependent variable for the given value of the independent time variable. Subclasses must implement this method in such a manner consistent with the forecasting model they implement. Subclasses can make use of the getForecastValue and getObservedValue methods to obtain "earlier" forecasts and observations respectively.

Parameters:

timeValue - the value of the time variable for which a forecast value is required.

Returns:

the forecast value of the dependent variable for the given time.

Throws:

IllegalArgumentException - if there is insufficient historical data - observations passed to init - to generate a forecast for the given time value.

getForecastValue

protected double getForecastValue(double timeValue)
                           throws IllegalArgumentException

Returns the forecast value for the dependent variable for the given value of the independent time variable. This method is only intended for use by models that base future forecasts, in part, on past forecasts.

Parameters:

timeValue - the value of the independent time variable for which the forecast value is required. This value must be greater than the minimum time value defined by the observations passed into the init method.

Returns:

the forecast value of the dependent variable for the given value of the independent time variable.

Throws:

IllegalArgumentException - if the given value of the time variable was not a valid value for forecasts.

getObservedValue

protected double getObservedValue(double timeValue)
                           throws IllegalArgumentException

Returns the observed value of the dependent variable for the given value of the independent time variable.

Parameters:

timeValue - the value of the independent time variable for which the observed value is required.

Returns:

the observed value of the dependent variable for the given value of the independent time variable.

Throws:

IllegalArgumentException - if the given value of the time variable was not found in the observations originally passed to init.

getTimeVariable

public String getTimeVariable()

Returns the name of the independent variable representing the time value used by this model.

Returns:

the name of the independent variable representing the time value.

getMinimumTimeValue

public double getMinimumTimeValue()

Returns the minimum value of the independent time variable currently forecast by this model.

Returns:

the minimum value of the independent time variable.

getMaximumTimeValue

public double getMaximumTimeValue()

Returns the maximum value of the independent time variable currently forecast by this model.

Returns:

the maximum value of the independent time variable.

getIndependentVariable

public String getIndependentVariable()

Returns the independent variable - or the time variable - used in this model.

Returns:

the independent variable in this model.

getTimeInterval

protected double getTimeInterval()

Returns the current time interval between observations.

Returns:

the current time interval between observations.

getForecastType

public String getForecastType()

Returns a one or two word name of this type of forecasting model. Keep this short. A longer description should be implemented in the toString method.

Returns:

a string representation of the type of forecasting model implemented.

toString

public String toString()

This should be overridden to provide a textual description of the current forecasting model including, where possible, any derived parameters used.

Specified by:

toString in interface ForecastingModel

Overrides:

toString in class Object

Returns:

a string representation of the current forecast model, and its parameters.