Operator CrossCorrelate2
SPL standard and specialized toolkits > com.ibm.streams.timeseries 3.1.0 > com.ibm.streams.timeseries.analysis > CrossCorrelate2
In signal processing, cross-correlation is a measure of similarity of two time series as a function of a time-lag applied to one of them. Cross-correlation is also known as a sliding dot product or sliding inner-product, which is defined by the following formula: (f*g)[n]=Σ f*[m] g[n+m]
In this formula, f and g are two input time series. Cross-correlation is often used in pattern recognition. Output of cross-correlation indicates the amount of overlap or similarities between two input time series.
The operator is capable of calculating the cross correlation using either the FFT, Pearson or standard algorithm. The standard algorithm formula used for cross correlation is (f*g)[n]=Σ f*[m] g[n+m].
Behavior in a consistent region
- The CrossCorrelate2 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 CrossCorrelate operator throws exception and terminates when a count-based window configuration of 0 is specified.
Windowing
The CrossCorrelate operator supports a tumbling window with count-based, delta-based, time-based, or punctuation-based eviction policy.
The tuples from each input port are stored in the corresponding window. When both the windows are full, the cross-correlation is calculated for tuples in both the windows and the windows are flushed. The cross-correlated time series is output followed by a window marker punctuation.
When a time-based window or a punctuation-based window with no tuples tumbles, only a window marker punctuation is output.
When one of the input ports receives the final punctuation marker, the CrossCorrelate operator stores the tuples in memory. When the window corresponding to the other input port tumbles, the CrossCorrelate operator calculates the cross-correlation between these tuples and the tuples that are stored in memory. When both the input ports receive the final punctuation marker, the CrossCorrelate operator calculates the cross-correlation for the tuples in both these windows and outputs the cross-correlated times series to the output port.
Summary
- Ports
- This operator has 2 input ports and 1 output port.
- Windowing
- This operator requires a windowing configuration.
- Parameters
- This operator supports 4 parameters.
Required: inputTimeSeries
- Metrics
- This operator does not report any metrics.
Properties
- Implementation
- C++
- Threading
- Never - Operator never provides a single threaded execution context.
- Ports (0)
This port consumes the values of the first timeseries to be cross correlated. 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
-
- Optional: false
- ControlPort: false
- TupleMutationAllowed: false
- WindowingMode: Windowed
- WindowPunctuationInputMode: WindowBound
- Ports (1)
This port consumes the values of the second timeseries to be cross correlated. 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
-
- Optional: false
- ControlPort: false
- TupleMutationAllowed: false
- WindowingMode: Windowed
- WindowPunctuationInputMode: WindowBound
- Assignments
- This operator allows any SPL expression of the correct type to be assigned to output attributes.
- Output Functions
-
- CrossCorrelatefunctions
-
- <any T> T AsIs(T v)
-
Default function
- <any T> T crossCorrelateTimeSeries()
-
This function returns a list<float64> value that holds the cross-correlated time series data. If the input time series in port 0 is of size n and input time series in port 1 is of size m, the size of the cross-correlated time series is calculated by using the formula max(m,n)-min(m,n).
- Ports (0)
-
This port submits a tuple that contains the result of the cross correlation. This port submits a tuple each time the two timeseries are cross correlated, which occurs when both input port windows are full. 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
-
- Optional: false
- TupleMutationAllowed: false
- WindowPunctuationOutputMode: Generating
- inputTimeSeries
Specifies the name(s) of the input timeseries attribute(s). When using a single input port, the expected type is list<float64>. When using two input ports, the name of the input time series attribute from each port must be specified. In the case where two input ports are being used, the expected type for each attribute is float64.
- Properties
-
- Optional: false
- ExpressionMode: Attribute
- algorithm
Specifies the algorithm that the operator uses to calculate cross correlation. The support values are FFT, standard and pearson. The default value is FFT.
- Properties
-
- Type: algoType (FFT, standard, pearson)
- Cardinality: 1
- Optional: true
- ExpressionMode: CustomLiteral
- normalize
Specifies whether the operator calculates raw or normalized cross correlation. The operator normalizes the output time series by using the following formula: ncorr(x,y)= corr(x,y)/sqrt(corr(x,x)*corr(y,y)), where x and y represent the input time series. The default value is set to false.
- Properties
-
- Type: boolean
- Cardinality: 1
- Optional: true
- ExpressionMode: AttributeFree
- lag
Specifies the maximum lag of the correlation process. The cross correlation results are over the range [-lag:lag]. The length of the returned results is a list of length 2*lag+1. When not specified, the lag value is equal to the length of the longest time series.
- Properties
-
- Type: int32
- Cardinality: 1
- Optional: true
- ExpressionMode: AttributeFree
- Cross correlate library
- Library Name: tsatapi
- Library Path: ../../../impl/lib
- Include Path: ../../../impl/include