IBM Streams 4.2.1

Operator STD

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

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

DEPRECATED: The com.ibm.streams.timeseries.analysis.STD operator is deprecated and is replaced by the com.ibm.streams.timeseries.analysis.STD2 operator. The deprecated operator might be removed in a future release.

The seasonal trend decomposition (STD) operator transforms an input time series into three time series that represent the season, the trend, and the residuals.

The STD operator transforms the time series by using the Loess algorithm. If the input is a time series of list<float64> values, the STD algorithm can be applied directly based on the value of samplesPerSeason parameter. In this case, the entire list is split into seasons and processed. If the input time series is a single float64 value, then tumbling window configurations must be provided; otherwise a compile-time error occurs. This decomposition algorithm requires at least eight time series elements to operate, otherwise an exception occurs.

The STD operator is a multivariate operator.

Behavior in a consistent region

  • The STD 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 STD operator supports the following window configurations:

  • Tumbling, with a count-based, time-based, punctuation-based, or delta-based eviction policy

The size of the window is considered to be a season for decomposing. Tuples are windowed when the window gets full (and flushes). The decomposition operation is applied on the window and it is output immediately, followed by a window marker punctuation.

When a time-based window or punctuation-based window with no tuples in it fires, only a window marker punctuation is output. Similarly, if the window has less than four tuples, then only a window marker punctuation is output. The STD operator requires at least eight tuples to decompose the input time series. Otherwise, the window is dropped and a message is logged.

If the flushOnFinal parameter is set to true, the final punctuation flushes the pending windows.

Exceptions

The STD operator throws an exception and terminates the operator in the following cases:

  • The samplesPerSeason parameter value is 0.
  • The input time series list has less than eight elements.
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 5 parameters.

Required: inputTimeSeries, samplesPerSeason

Optional: algorithm, flushOnFinal, partitionBy

Metrics
This operator reports 1 metric.

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 types are float64 and list<float64>.

Properties

Output Ports

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

Returns a list<float64> value that holds the input time series values representing a season. The size of the list that is returned is the same as the value specified for the samplesPerSeason parameter.

list<float64> trend()

Returns a list<float64> value that holds the calculated trend for the season.

list<float64> residuals()

Returns a list<float64> value that holds the residuals after the trend is calculated.

<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

This operator supports 5 parameters.

Required: inputTimeSeries, samplesPerSeason

Optional: algorithm, flushOnFinal, partitionBy

algorithm
Specifies the type of season model. The supported values are:
  • Additive
  • Multiplicative

The default is set to Additive.

Properties

flushOnFinal

Specifies whether the pending tuples in the window are flushed when a final punctuation is received. If set to true, the window is flushed and the window is processed. If set to false, the window is dropped and no processing occurs. The default value is false. If windowing is not enabled, this parameter is ignored.

Properties

inputTimeSeries

Specifies the name of the attribute that contains the time series data in the input tuple. Supported types are list<float64> and float64. If the input is a single float64 value, you must supply window configurations.

Properties

partitionBy

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

For example, the following tuple with time series data (in KW units) lists the electricity consumption for the past six months in a city called Atlantis: 

{123.4,441.1,234.1,212.1,313.2},"Atlantis"

The key value indicates that it is the data for Atlantis.

Properties

samplesPerSeason

Specifies the number of time series values that are considered as a season. To successfully decompose the input, there must be at least two seasons of time series values (for example, 2*samplesPerSeason time series values).

Properties

Code Templates

STD
stream<${schema}> ${outputStream} = STD(${inputStream}) 
	{
	param
		samplesPerSeason: ${initSeasonExpression};
		inputTimeSeries: ${timeSeriesAttributeExpression};
	

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

Metrics

numWindowsDropped - Counter

The number of times windows are dropped because they have less than eight time series tuples.

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