Operator AutoForecaster2

Specialized toolkits - release 4.3.1.0-prod20190605 > com.ibm.streams.timeseries 5.0.1 > com.ibm.streams.timeseries.modeling > AutoForecaster2

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

The AutoForecaster2 operator is a forecasting operator, which detects the algorithm that best suits the input time series data in real time and forecasts future time series.

If you use the ARIMA or the HoltWinters operator to do forecasting, you must have prior understanding of which operator is more suitable for the input timeseries data. The AutoForecaster2 operator makes it easier to forecast future time series data by automatically selecting an algorithm that is based on input time series data and applying it in real time for forecasting. The AutoForecaster2 operator uses the Holt-Winters additive, Holt-Winters multiplicative, autoregressive integrated moving average (ARIMA), and Linear Regression algorithms to do forecasting.

The 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 AutoForecaster2 operator supports an optional control port that you can use to retrain the model so that the model adapts to changing trends in the data and 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 AutoForecaster2 operator throws an exception when the value that is specified by the stepAhead parameter is 0.

Dependencies

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

Examples 


use com.ibm.streams.timeseries.modeling::AutoForecaster2;

composite Main {
      stream<float64 ts > data = FileSource() {
            param
               file : "ForecasterTest.dat"; // get data
               format:csv;

       }
	
        stream <list<float64> ForecastedTs> forecastedData = AutoForecaster2(data){
              param
                    inputTimeSeries: ts; // data to be forecasted
                    stepAhead: 1u;    // one step ahead forecasting (horizon)
              output
                forecastedData: ForecastedTs = forecastedAllTimeSeriesSteps (); // get all forecasted values up to the horizon
                }


           
                () as out1Sink = FileSink(forecastedData) {
                        param
                                file: "ForecastedOutput.dat";
                                format: csv;
                } 
}

Summary

Ports
This operator has 2 input ports and 1 output port.
Windowing
This operator does not accept any windowing configurations.
Parameters
This operator supports 11 parameters.

Required: initSamples, inputTimeSeries

Optional: algorithm, controlPartitionBy, controlSignal, inputTimestamp, maxHistoryBufferSize, maxTrainingCount, 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. The retrainingConfig parameter specifies the attribute name on this port that contains the configuration values used for retraining the model.

Properties

Output Ports

Assignments
This operator allows any SPL expression of the correct type to be assigned to output attributes.
Output Functions
AFOutput
<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.

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

Parameters

This operator supports 11 parameters.

Required: initSamples, inputTimeSeries

Optional: algorithm, controlPartitionBy, controlSignal, inputTimestamp, maxHistoryBufferSize, maxTrainingCount, partitionBy, stepAhead, updateParams

algorithm

Specifies how frequently the operator selects an algorithm that best suits the input time series data before forecasting future time series. The supported values are Static and Dynamic. If this parameter is set to Static, the AutoForecaster2 operator trains the model by using the number of samples specified by the initSamples parameter, and then selects the most suitable algorithm for forecasting future time series. If this parameter is set to Dynamic, the operator trains the model by using the number of samples specified by the initSamples parameter, and then selects the best algorithm for every input time series. This option is computationally more expensive than the Static option. The default value is set to Static.

Properties

controlPartitionBy

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

Properties

controlSignal

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.

Properties

initSamples

Specifies the number of input time series values that are used to initialize the model. If the value specified by the initSamples parameter is zero, the compiler generates an error.

Properties

inputTimeSeries

Specifies the name of the attribute that contains the time series data in the input tuple. The supported 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 types are uint64 and timestamp..

Properties

maxHistoryBufferSize

Specifies the size of the historical tuple buffer used to reset the models when the operator is in a consistent region. This parameter is only used when the operator is in a consistent region. When not specified, the operator will determine the size of the buffer based on the number of tuples that were needed to initialize the model.

Properties

maxTrainingCount

Specifies the maximum number of iterations to attempt in order to initialize all of the forecasting algorithms. This parameter is only used when the algorithm parameter is set to Static. When the algorithm parameter is set to Static, all of the forecasting algorithms must first be initialized before the best algorithm is selected. In certain cases, depending on the data, some forecasting algorithms may never initialize. This parameter prevents the operator from waiting indefinitely for all of the forecasting algorithms to be initialized. The default value is -1, meaning all forecasting algorithms must be initialized before forecasting begins.

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

stepAhead

Specifies the forecast horizon in the sample. For example, a value of 5u means the operator forecasts the next 5 values. The default value for this parameter for 1u.

Properties

updateParams

Specifies the name of the attribute in the control port, which ingests the new parameter values. If this parameter is not specified, by default, the updateParams attribute is used. If the default attribute or the updateParams parameter is not provided, parameter values are not updated. If valid parameter values are not provided, an error message is logged and no parameter values are updated. The valid key values for the map are "initSamples" and "stepAhead".

Properties

Code Templates

AutoForecaster2

stream<${schema}> ${outputStream} = AutoForecaster2(${inputStream}) 
{
	param
		inputTimeSeries:		${timeSeriesExpression};
		initSamples: ${initSamplesExpression};
		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/