Operator HoltWinters

SPL standard and specialized toolkits > com.ibm.streams.timeseries 3.1.0 > com.ibm.streams.timeseries.modeling > HoltWinters

DEPRECATED: The com.ibm.streams.timeseries.modeling.HoltWinters operator is deprecated and is replaced by the com.ibm.streams.timeseries.modeling.HoltWinters2 operator. The deprecated operator might be removed in a future release.

The HoltWinters operator is a forecasting operator, which uses the Holt-Winters algorithm to do long-term forecasting.

The HoltWinters operator is a univariate operator. The operator accepts time series in the following format.

A univariate time series as a tuple<float64> or tuple<timestamp timestamp, float64 value>.
A vector time series as a tuple<list<float64>> or tuple<list<timestamp> timestamps, list<float64 values>.

The HoltWinters operator provides two ways of getting the forecasted time series values and timestamp values. It can forecast a value at a single point in a future or it can provide a range of forecasts up to a point in time in the future.

The stepAhead parameter controls the point in time in the future.

The HoltWinters operator supports an optional control port that you can use to retrain the model so that the model predicts time series data more accurately.

Behavior in a consistent region

The HoltWinters operator is not supported in a consistent region. A warning occurs when you compile your streams processing application.
The operator cannot be the start of a consistent region. An error occurs when you compile your streams processing application.

Exceptions

The HoltWinters operator throws an exception and terminates in the following case.

The value that is specified by the stepAhead, initSeason, or samplesPerSeason parameter is 0.

Dependencies

The HoltWinters operator requires that the boost library is installed in your operating system.

Examples: These examples demonstrate how to use the HoltWinters operator.

Summary

Ports

This operator has 2 input ports and 2 output ports.

Windowing

This operator does not accept any windowing configurations.

Parameters

This operator supports 11 parameters.

Required: inputTimeSeries, initSeason, stepAhead

Optional: inputTimestamp, samplesPerSeason, dimension, partitionBy, algorithm, controlSignal, inputCoefficient, retrainingConfig

Metrics

This operator does not report any metrics.

Properties

Implementation: C++
Threading: Never - Operator never provides a single threaded execution context.

Input Ports

Ports (0)

This port consumes data for training and scoring against the model. The inputTimeSeries parameter specifies the name of the attribute on this port that contains the time series data. The accepted data types are float64 and list<float64>.

Properties

Optional: false

Ports (1)

This port accepts control signals to control the behavior of the operator. The controlSignal parameter specifies the name of the attribute on this port that contains the control signal type. The inputCoefficient parameter specifies the attribute name on this port that contains the new input coefficents. The retrainingConfig parameter specifies the attribute name on this port that contains the configuration values that are used for retraining the model.

Properties

Optional: true

Output Ports

Assignments: This operator allows any SPL expression of the correct type to be assigned to output attributes.

Output Functions

HWOutput

list<float64> forecastedTimeSeriesStep()

This function returns the forecasted time series values. The function returns the forecasted value at step n (a future time series value), where n is the same as the stepAhead parameter value.

list<list<float64> > forecastedAllTimeSeriesSteps()

This function returns a two-dimensional list of forecasted values. For each index value in the input time series, a list of forecasted values is returned. That is, values from step 1 to n.

<any T> list<T> forecastedTimestamps()

This function returns a timestamp object, which holds the value of forecasted timestamp values. If an input timestamp is irregular, then it returns a zero timestamp value and a warning is logged. The supported data types are uint64 or timestamp.

<any T> T AsIs(T v)

The default function for output attributes. By default, this function assigns the output attribute to the value of the input attribute with the same name.

Getcoeff

map<rstring,map<uint32,float64> > coefficients()

Returns the list of smoothing parameters.

<any T> T AsIs(T v)

The default function for output attributes. By default, this function assigns the output attribute to the value of the input attribute with the same name.

Ports (0)

This port submits a tuple that contains the forecasted value for the timeseries. This port submits a tuple each time a forecast is calculated. Custom output functions are used to specify the value of the output tuple attributes. The output tuple attributes whose assignments are not specified are assigned from input attributes.

Properties

Optional: false

TupleMutationAllowed: true
WindowPunctuationOutputMode: Preserving

Ports (1)

This port submits a tuple that contains the coefficients used by the filter. This port submits a tuple each time a Monitor signal is consumed on the input control port. The coefficients() output function is used to assign the value of the coefficients to an attribute. The expected type of the attribute is map<rstring,map<uint32,float64> >.

Properties

Optional: true

TupleMutationAllowed: false
WindowPunctuationOutputMode: Preserving

Parameters

This operator supports 11 parameters.

inputTimeSeries

An attribute expression, which specifies the name of the attribute that contains the time series data in the input stream.

Properties

Type
Cardinality: 1
Optional: false
ExpressionMode: Attribute

inputTimestamp

Specifies the name of the attribute in the input stream that contains the timestamp values. The supported data types are uint64 and timestamp. If the data type is uint64, then the parameter value represents the number of nanoseconds since UNIX epoch.

Properties

Type
Cardinality: 1
Optional: true
ExpressionMode: Attribute

samplesPerSeason

Specifies the number of samples in a season. For example, if a season is considered to be a year, then you have 12 samples in the season; each sample represents a value for the month.

Properties

Type: uint32
Cardinality: 1
Optional: true
ExpressionMode: Expression

initSeason

Specifies the number of seasons that are used for initialization, which builds the model.

Properties

Type: uint32
Cardinality: 1
Optional: false
ExpressionMode: Expression

stepAhead

Specifies the forecast horizon in the sample. The default value is 1u. The parameter value specifies the future time series value to be predicted. If the value is 1u, then the algorithm predicts the next time series value. If the value is 2u, then the algorithm predicts the time series value two steps ahead.

Properties

Type: uint32
Cardinality: 1
Optional: false
ExpressionMode: AttributeFree

dimension

Properties

Type: uint32
Cardinality: 1
Optional: true
ExpressionMode: Constant

partitionBy

Specifies the name of the attribute that contains the key values that are associated with the time series values in the input tuple.

Properties

Type: rstring
Optional: true
ExpressionMode: Attribute

algorithm

Specifies the type of Holt-Winters algorithm to use. It is a custom literal. The supported values are Additive and Multiplicative. The default value is Additive.

Properties

Type: HWAlgorithm (Additive, Multiplicative)
Cardinality: 1
Optional: true
ExpressionMode: CustomLiteral

controlSignal

Specifies an attribute expression that specifies the name of the attribute in the control port, which holds the control signal. The supported control signals are: TSSignal.Retrain, TSSignal.Monitor, TSSignal.Load, TSSignal.Suspend, TSSignal.Resume.

Properties

Type: enum{Monitor,Load,Retrain,RetrainAll,Suspend,Resume,UpdateParamsAll}
Cardinality: 1
Optional: true
ExpressionMode: Expression
PortScope: 1

inputCoefficient

Specifies the name of the attribute in the control port, which ingests the coefficients that are used for loading the model. If this parameter is not specified, by default, the inputCoefficient attribute is used. If the default attribute or the inputCoefficient parameter is not provided, the operator throws an exception. If the attribute or the parameter value does not contain valid coefficients, the load operation fails and the operator logs a warning message for each failed operation. The operator continues to predict values by using the older coefficients. The supported type is map<rstring,map<uint32,float64>>.

Properties

Type: map<rstring,map<uint32,float64>>
Cardinality: 1
Optional: true
ExpressionMode: Expression
PortScope: 1

retrainingConfig

Specifies the name of the attribute in the control port, which ingests the configurations that are used for retraining the model. If this parameter is not specified, by default, the retrainingConfig attribute is used. If the default attribute or the retrainingConfig parameter is not provided, the operator throws an exception. If the attribute or the parameter does not contain valid configurations, the retrain operation fails and the operator logs a warning message for each failed operation. The operator continues to predict values by using the older configuration. The supported type is map<rstring,uint32>.

Properties

Type: map<rstring,uint32>
Cardinality: 1
Optional: true
ExpressionMode: Expression
PortScope: 1

Code Templates

HoltWinters

stream<${schema}> ${outputStream} = HoltWinters(${inputStream}) 
{
	param
		inputTimeSeries:		${timeSeriesExpression};
		samplesPerSeason:		${samplesPerSeasonExpression};
		initSeason: 		${initSeasonExpression};
		stepAhead: 		${stepAheadExpression};

	output
		${outputStream}: ${outputExpression};
}

Libraries

No description for library.: Library Name: watfore; Library Path: ../../../impl/lib/; Include Path: ../../../impl/include/
No description for library.: Library Name: utils; Library Path: ../../../impl/lib/; Include Path: ../../../impl/include/