IBM Streams 4.2.1

Operator STD2

SPL standard and specialized toolkits > com.ibm.streams.timeseries 4.0.1 > com.ibm.streams.timeseries.analysis > STD2

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

The Seasonal Trend Decomposition (STD) operator uses the Loess algorithm to decompose an input time series into three components: the season, the trend and the residuals. The

This operator ingests a time series as a series of float64 values. By default, the operator uses a sliding window with length equal to the value of (numSeasons x seasonLength). The window will trigger every ((numSeasons - 1) x seasonLength). Using this window configuration, the operator is able to ensure that results are returned for every data point in the streaming time series, with the exception of the first and last half-season. The reason that the first and last half-season do not return points is due to the underlying algorithm used to decompose the time series. In order to decompose the time series, the STD algorithm must first smooth the time series. To accomplish this, a Centered Moving Average is used. The cost of this algorithm is that smoothing values cannot be calculated for the first and last half-season.

The operator is also able to accept a user-defined window configuration. Both sliding and tumbling windows are supported. When using a custom window configuration, the values for the first and last half-season of the analyzed window are NaN. By default, the operator will not return these NaN values. If you wish receive all of the data points including the NaN values, the trimNaNs parameter can be set to false.

The operator contains three output functions for returning the season, trend and residual components of the analyze time series. These output functions all return float64 values.

Behavior in a consistent region

  • The STD2 operator can be an operator within the reachability graph of a consistent region.
  • The operator cannot be the start of a consistent region. An error occurs when you compile your streams processing application.

Windowing

The STD2 operator supports both sliding and tumbling window configurations. All eviction and trigger policies are supported. Windows are only processed once they are full.

The length of a window is used to calculate the number of seasons in the time series. For example, if the seasonLength parameter value is 10 and the window has a length of 50, the operator will calculate the number of seasons as being 5.

If the window length is not an integer multiple of seasonLength, the number of seasons calculated will be the next, lowest integer multiple. For example, if the seasonLength is 10 and the window length is 45, the operator will calculate the number of seasons as being 4. The additional 5 tuples will be trimmed from the window prior to be analyzed.

Exceptions

The STD2 operator will throw a compile-time exception in the following case:

  • No window configuration is specified and the numSeasons parameter is not specified

The STD2 operator will throw a runtime exception in the following case:

  • The numSeasons parameter value is less than 2.
Examples

Summary

Ports
This operator has 1 input port and 1 output port.
Windowing
This operator optionally accepts a windowing configuration.
Parameters
This operator supports 6 parameters.

Required: inputTimeSeries, seasonLength

Optional: algorithm, numSeasons, partitionBy, trimNaNs

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 time series data to be decomposed. The inputTimeSeries parameter specifies the name of the attribute on this port that contains the time series data. The accepted data type is float64.

Properties

Output Ports

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

Returns a float64 value representing the season component of the time series.

<any T> T trend()

Return a float64 value representing the trend component of the time series.

<any T> T residuals()

Returns a float64 value representing the residual component of the time series.

<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 decomposed time series data. This port submits a tuple each time a time series is decomposed. 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

Required: inputTimeSeries, seasonLength

Optional: algorithm, numSeasons, partitionBy, trimNaNs

algorithm
Specifies the algorithm that should be used to decompose the time series. The supported values are:
  • Additive
  • Multiplicative

The default is set to Additive.

Properties

inputTimeSeries

Specifies the name of the attribute that contains the time series data in the input tuple. The support attribute data type if float64.

Properties

numSeasons
Specifies that number of seasons the operator should use when decomposing the time series. 
    This parameter is only used when no window configuration is specified. Specifying a value less than 2 will 
    result in a run-time error.
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

seasonLength

Specifies the number of time series values that are considered as a season.

Properties

trimNaNs
In the case that a window-configuration is provided, this parameter determines whether the NaN values in the 
    first and last half-seasons should be returned. By default, this parameter value is set to `false`.
Properties

Code Templates

STD2
stream<${schema}> ${outputStream} = STD(${inputStream}) 
	{
	param
		inputTimeSeries: ${inputTimeSeries};
		seasonLength: ${seasonLength};
		numSeasons: ${numSeasons};
	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: watfore
Library Path: ../../../impl/lib
Include Path: ../../../impl/include
No description for library.
Library Name: utils
Library Path: ../../../impl/lib
Include Path: ../../../impl/include