IBM Streams 4.2.1

Operator HoltWinters2

SPL standard and specialized toolkits > com.ibm.streams.timeseries 4.0.1 > com.ibm.streams.timeseries.modeling > HoltWinters2

Primitive operator image not displayed. Problem loading file: ../../image/tk$com.ibm.streams.timeseries/op$com.ibm.streams.timeseries.modeling$HoltWinters2.svg

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

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

  • A univariate time series as a tuple<float64>.
  • A vector time series as a tuple<list<float64>>.

The HoltWinters2 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 HoltWinters2 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 operator cannot be the start of a consistent region. An error occurs when you compile your streams processing application.

Exceptions

The HoltWinters2 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 HoltWinters2 operator requires that the boost library is installed in your operating system.

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, samplesPerSeason

Optional: algorithm, controlPartitionBy, controlSignal, dimension, initSeasons, inputTimestamp, partitionBy, stepAhead, updateParams

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

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.

Properties

Output Ports

Assignments
This operator allows any SPL expression of the correct type to be assigned to output attributes.
Output Functions
HWOutput
<any T> T forecastedTimeSeriesStep()

This function returns the forecasted time series value at step n, where n is the same as the stepAhead parameter value. The return type for this function can be either float64 or list<float64>, depending on the type of the attribute specified by the inputTimeSeries parameter. For example, if the inputTimeSeries parameter specifies an attribute whose type is float64, the return type is float64. Likewise, if the inputTimeSeries parameter specifies an attribute whose type is list<float64>, the return type is list<float64>.

<any T> list<T> forecastedAllTimeSeriesSteps()

This function returns a list of forecasted time series values from step 1 to step n, where n is the same as the stepAhead parameter. The return type for this function can be either list<float64> or list<list<float64>>, depending on the type of the attribute specified by the inputTimeSeries parameter. For example, if the inputTimeSeries parameter specifies an attribute whose type is float64, the return type is list<float64>. Likewise, if the inputTimeSeries parameter specifies an attribute whose type is list<float64>, the return type is list<list<float64>>.

<any T> T forecastedTimestamp()

This function returns the forecasted timestamp value at step n, where n is the same as the stepAhead parameter value. The return type for this function can be either SPL::timestamp or uint64, depending on the type of the attribute that is specified by the inputTimestamp parameter.

<any T> list<T> forecastedAllTimestamps()

This function returns a list of forecasted timestamp values from step 1 to step n, where n is the same as the stepAhead parameter. The return type for this function can be either list<timestamp> or list<uint64>, depending on the type of the attribute specified by the inputTimestamp parameter.

<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.

MonitorOutputFunctions
map<int32, list<float64> > getSmoothingParams()

Returns a map containing the alpha, beta, gamma parameters for each dimension. The map key represents the index of the dimension. The map value returns a list containing 3 values: [alpha, beta, gamma]. If partitioning is being used, the returned map will be based on the partition specified by the controlPartitionBy parameter.

<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

Ports (1)

This port submits a tuple that contains the smoothing parameters of the HoltWinters algorithm. This port submits a tuple each time a Monitor signal is consumed on the input control port. The getSmoothingParams() output function is used to assign the values of the smoothing parameters to an attribute. The expected type of the attribute is map<int32, list<float64> >.

Properties

Parameters

Required: inputTimeSeries, samplesPerSeason

Optional: algorithm, controlPartitionBy, controlSignal, dimension, initSeasons, inputTimestamp, partitionBy, stepAhead, updateParams

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

controlPartitionBy
Properties

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.RetrainAll, TSSignal.UpdateParamsAll, TSSignal.Monitor.

Properties

dimension

Specifies the dimension of the incoming time series. If this parameter is omitted, the dimension is set to the length of the first tuple. If a tuple is submitted that does not have the correct dimension, an error will be logged and the tuple will be dropped.

Properties

initSeasons

Specifies the number of seasons that are used for initialization, which builds the model. If this parameter is not specified, a default value of 2 will be used.

Properties

inputTimeSeries

Specifies the name of the attribute that contains the time series data in the input stream. The supported data types are float64 and list<float64>.

Properties

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

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

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

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

updateParams

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

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/
No description for library.
Library Name: tstimelag
Library Path: ../../../impl/lib/
Include Path: ../../../impl/include/