Operator ReSample

Primitive operator image not displayed. Problem loading file: ../../image/tk$com.teracloud.streams.timeseries/op$com.teracloud.streams.timeseries.preprocessing$ReSample.svg

The ReSample operator changes the sampling rate of a time series.

The ReSample operator can change the sampling rate by upsampling or downsampling the time series.

For example, if the sampling rate of an input signal is 16 samples per second, then it can be upsampled to 32 samples per second or downsampled to eight samples per second by applying a polynomial algorithm.

If an input timestamp is provided and it is a regular time series, the ReSample operator calculates the output timestamp for the resampled time series values.

The polynomial function adds the missing values when upsampling occurs and it merges two samples into an approximate value when downsampling occurs.

Behavior in a consistent region

  • The ReSample 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.

Exceptions

The ReSample operator throws an exception in the following cases:

  • The newSamplingRate or samplingRate parameter value is 0.

Windowing

The ReSample operator supports the following window configurations: 


tumbling: (count|time|punctuation|delta)-based eviction

Tuples are windowed when the window gets full and flushes. The resampling 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, just a window marker punctuation is output. Similarly, if the window has less than four tuples, just a window marker punctuation is output. This behavior occurs because the ReSample operator requires at least five tuples to apply the polynomial algorithm.

The final punctuation flushes the pending windows if the flushOnFinal parameter value is true.

Windowing is only required when the inputTimeSeries parameter refers to an attribute of type float64.

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, newSamplingRate, samplingRate

Optional: flushOnFinal, inputTimestamp

Metrics
This operator reports 1 metric.

Properties

Implementation
C++
Threading
Always - Operator always provides a single threaded execution context.

Input Ports

Ports (0)

Consumes the timeseries data to be resampled. 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
ReSampleFunctions
<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.

<any T> T reSampledTimeSeries()

Returns resampled timeseries values. If the assigned attribute is of type list<float64>, the resampled timeseries is returned as a list. If the assigned attribute is of type float64, a separate tuple is submitted for each element in the list of resampled timeseries.

<any T> T reSampledTimestamps()

Returns resampled timestamp values whenever the input timestamp was provided. The data type of the return value is the same as the data type of the input timestamp attribute. Supported types are uint64, SPL::timestamp, list<uint64> and list<SPL::timestamp>. If the data type is uint64 or list<uint64>, it represents the nanoseconds since UNIX epoch. If this output function is assigned to an attribute but the inputTimestamp attribute was not specified, a compile-time error occurs.

Ports (0)

This port submits a tuple that contains the resampled timeseries. This port submits a tuple each time a timeseries is resampled. If using windowing, the timeseries is resampled each time the window is evicted. When not using windowing, the timeseries is resampled each time an input tuple is consumed. 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, newSamplingRate, samplingRate

Optional: flushOnFinal, inputTimestamp

flushOnFinal

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

Properties

inputTimeSeries

Specifies the name of the attribute that contains the time series data in the input tuple. 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 timestamp attribute value indicates the number of nanoseconds since UNIX Epoch. The supported types are uint64, SPL::timestamp, list<uint64> and list<SPL::timestamp>.

Properties

newSamplingRate

Specifies the new sampling rate of the transformed timeseries in Hertz.

Properties

samplingRate

Specifies the sampling rate of an incoming time series in Hertz.

Properties

Code Templates

ReSample

stream<${schema}> ${outputStream} = ReSample(${inputStream}) 
{
	param
		samplingRate:		${samplingRateExpression};
		newSamplingRate:		${newSamplingRateExpression};
		inputTimeSeries: ${timeSeriesAttributeExpression};
		inputTimeStamp: ${timeStampAttributeExpression};

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

Metrics

numWindowsDropped - Counter

Counts the number of windows that dropped because they had less than four timeseries tuples.

Libraries

No description for library.
Library Name: tsatapi
Library Path: ../../../impl/lib
Include Path: ../../../impl/include
No description for library.
Library Name: tstimelag
Library Path: ../../../impl/lib
Include Path: ../../../impl/include