FB_CMA_Correlation

Calculation of the correlation function for single and multi-channel real-valued time series.

The FB_CMA_Correlation function block calculates the correlation function of real-valued time series.

The correlation function of two signals describes their similarity at different temporal shifts in relation to each other. The time-discrete displacement is designated m in the following.

The input data consist of a tuple of one (or more) test signals x[n] and one (or more) reference signals y[n]. The input data are introduced into the analysis chain via the function block FB_CMA_SourcePaired. Please note that when specifying a single reference signal, all channels of the test signals are correlated with the same reference signal. Conversely, when specifying several reference signals in pairs, the reference signal of channel i is correlated with the test signal of channel i. The number of channels nChannels must match accordingly.

There are many possible applications for the correlation function. For example, it is possible to record a signal reference of a process step and then continuously compare it with repetitions of this process step. The measure of similarity (value of the maximum of the correlation function) can then be used to monitor the process step. Likewise, the correlation function is a good tool for determining temporal shifts. We aren't looking here for the value of the maximum, but rather its position on the displacement axis m. This can be used, for example, to determine runtime differences of signals, for example, when locating leaks by means of several microphones. In general, autocorrelation, i.e. the correlation of a signal with itself, can be used for signal recognition in highly noisy signals. If the noise is random and the wanted signal is a deterministic signal, the result of the autocorrelation contains the noise component only at m=0 and the deterministic signal becomes visible.

Sampling theorem: Like the discrete Fourier transform, the sampling theorem is valid in the same way. The temporally continuous curve of an autocorrelation function can be reconstructed in discrete time series if the sampling rate is at least twice as large as the highest frequency occurring in the signal.

The calculation of the correlation function is based on one of the following configurable definitions:

Base
Normed
Covariance
Covariance (Bessel correction)
Pearson

The above definitions are selected via the initial parameter eCorrelationMode of type E_CM_CorrelationMode. When quantitatively assessing the similarity of signals, "Pearson" is recommended. Conversely, the standardization is irrelevant when looking for a shift time.

The calculation is done via a selected timeframe, which is set by eWindowMode of the type E_CM_WindowMode. There is a choice of three variants: a sliding window, a fixed window and a calculation based on all data collected since the last ResetData().

Configuration

The initialization parameters are used to define the calculation variant and the window. They can be individually adjusted for each channel with the Configure() method.

NaN occurrence

If the input vector contains one or more NaN (Not a Number) values, the entire output sector is filled with NaN. See separate section for further information on NaN values.

	Handling of NaN values If the situations described above, which lead to NaN values, cannot be ruled out or safely neglected, the application program must be able to handle these error values.

Behavior when processing multi-channel input data

When processing several channels (nChannels > 1), there is a possibility of each channel having different return values. In this case, return values can be queried separately on the function block. If the results from one or more channels are impermissible, but not all channels, the value on the function block corresponds to eCM_InfRTime_AmbiguousChannelResults. If the results of all channels are impermissible, then the value on the function block corresponds to eCM_ErrRTime_ErrornousChannelResults.

A list of return values of all channels can be queried using the method GetChannelErrors().

Sample implementation

A sample implementation is available under the following link: Correlation function

Inputs and outputs

The input and output buffers correspond to one of the following definitions (input / output shape). The variable parameters are part of the function block input stInitPars. The rule for the processing of a single channel (nChannels = 1) is:

MultiArray in the	Element type	Dimensions	Dimensional variables
input stream A	LREAL	1	not specified*
input stream B	LREAL	1	not specified*
output stream	LREAL	1	`1+(nPositiveShift+nNegativeShift)/nStepsize`

The rule for the processing of multiple channels (nChannels > 1) is:

MultiArray in the	Element type	Dimensions	Dimensional variables
input stream A	LREAL	2	`nChannels x` not specified*
input stream B	LREAL	1	not specified*
output stream	LREAL	2	`nChannels x (1+(nPositiveShift+nNegativeShift)/nStepsize)`

or for the pairwise calculation of the correlation coefficients:

MultiArray in the	Element type	Dimensions	Dimensional variables
input stream A	LREAL	2	`nChannels x` not specified*
input stream B	LREAL	2	`nChannels x` not specified*
output stream	LREAL	2	`nChannels x (1+(nPositiveShift+nNegativeShift)/nStepsize)`

VAR_INPUT
    stInitPars       : ST_CM_Correlation_InitPars;         // init parameter
    nOwnID           : UDINT;                              // ID for this FB instance
    aDestIDs         : ARRAY[1..cCMA_MaxDest] OF UDINT;    // IDs of destinations for output
    nResultBuffers   : UDINT := 4;                         // number of MultiArrays which should be initialized for results (0 for no initialization)
    tTransferTimeout : LTIME := LTIME#500US;               // timeout checking off during access to inter-task FIFOs
END_VAR

Input parameters

The input parameters of this function block represent initialization parameters and must already be assigned in the declaration of the FB instance! (Alternatively: Init() method). They may only be assigned once. A change at runtime is not possible.

stInitPars: Function block-specific structure with initialization parameters of the type ST_CM_Correlation_InitPars. The parameters must correlate to the above definition of the input and output buffers.
nOwnID: Identifies the function block instance with a unique ID. This must always be greater than zero. A proven approach is to define an enumeration for this purpose.
aDestIDs: Defines the destinations to which the results are to be forwarded by specifying the IDs of the destinations. The definition of the output buffer (as described above) must correlate to the definition of the input buffer of each selected destination.
nResultBuffers: The function block initializes a Transfer Tray Stream with the specified number of MultiArray buffers. The default value is four.
tTransferTimeout: Setting of the synchronous timeout for internal MultiArray forwardings. See section Parallel processing.

Output parameters

VAR_OUTPUT
    bError         : BOOL;                           // TRUE if an error occurs. Reset by next method call.
    hrErrorCode    : HRESULT;                        // '< 0' = error; '> 0' = info; '0' = no error/info
    ipErrorMessage : I_TcMessage := fbErrorMessage;  // Shows detailed information about occurred errors, warnings and more.
    nCntResults    : ULINT;                          // Counts outgoing results (MultiArrays were calculated and sent to transfer tray).
END_VAR

bError: The output is TRUE if an error occurs.
hrErrorCode: If an error occurs, a corresponding error code of the type HRESULT is output. Possible values are described in the List of error codes.
ipErrorMessage: Contains more detailed information on the current return value. Refer here to the section Error description and information. This special interface pointer is internally secured so that it is always valid/assigned.

Methods

Call():

The method is called each cycle in order to apply the algorithm to the current input data. The function block waits for input data if the method indicates neither new results nor an error. This is a regular behavior in the process of the analysis chain.

Return value: If an error occurs, a corresponding error code of the type HRESULT is output. Possible values are described in the List of error codes.

METHOD Call : HRESULT
VAR_OUTPUT
    bNewResult   : BOOL;       // TRUE every time when outgoing MultiArray was calculated and sent to transfer tray.
    bError       : BOOL;       // TRUE if an error occurs.
    hrErrorCode  : HRESULT;    // '< 0' = error; '> 0' = info; '0' = no error/info
END_VAR

bError: The output is TRUE if an error occurs.
hrErrorCode: If an error occurs, a corresponding error code of the type HRESULT is output. Possible values are described in the List of error codes. This output is identical to the return value of the method.

	If a timeout occurs or no MultiArray buffer is available for the result, then neither the input data nor the result data are lost. They are forwarded on the next call.

Configure():

By calling this method, the scaling of the correlation coefficients (initial parameter eCorrelationMode) as well as the underlying calculation window (initial parameter eWindowMode) can be changed at runtime.

The corresponding PLC array must be defined as follows. The Configure() method can also be used for a new configuration with a different set of arguments.

Return value: If an error occurs, a corresponding error code of the type HRESULT is output. Possible values are described in the Error Codes Overview.

METHOD Configure : HRESULT
VAR_INPUT
    pArg     : PVOID;    // pointer to array of arguments
    nArgSize : UDINT;    // size of arguments buffer in bytes 
END_VAR

The input buffers correspond to one of the following definitions (input shape). The variable parameters are part of the function block input stInitPars.

Versions	Input buffer (MultiArray input stream) element type, number of dimensions, dimension sizes
Identical configuration of all channels	`UDINT, 1,`2
Channel-specific configuration (`nChannels > 1`)	`UDINT, 2,`nChannels x 2

METHOD Init : HRESULT
VAR_INPUT
    stInitPars     : ST_CM_Correlation_InitPars;         // init parameter
    nOwnID         UDINT;                                // ID for this FB instance
    aDestIDs       : ARRAY[1..cCMA_MaxDest] OF UDINT;    // IDs of destinations for output
    nResultBuffers : UDINT := 4;                         // number of MultiArrays which should be initialized for results (0 for no initialization)
END_VAR

Init():

This method is not usually necessary in a Condition Monitoring application. It offers an alternative to the function block initialization. The Init() method may only be called during the initialization phase of the PLC. It cannot be used at runtime. You are referred to the use of an FB_init method or the attribute 'call_after_init' (see TwinCAT PLC reference). In addition, this facilitates the function block encapsulation.

The input parameters of the function block instance may not be assigned in the declaration if the initialization is to take place using the Init() method.

Return value: If an error occurs, a corresponding error code of the type HRESULT is output. Possible values are described in the List of error codes.

stInitPars: Function block-specific structure with initialization parameters of the type ST_CM_Correlation_InitPars. The parameters must correlate to the above definition of the input and output buffers.
nOwnID: Identifies the function block instance with a unique ID. This must always be greater than zero. A proven approach is to define an enumeration for this purpose.
aDestIDs: Defines the destinations to which the results are to be forwarded by specifying the IDs of the destinations. The definition of the output buffer (as described above) must correlate to the definition of the input buffer of each selected destination.
nResultBuffers: The function block initializes a Transfer Tray Stream with the specified number of MultiArray buffers. The default value is four.

ResetData():

The method deletes all data records that have already been added, see Memory property of the function block. If the Call() method is called again after a ResetData(), the internal memory must be replenished in order to calculate a valid result.

Return value: If an error occurs, a corresponding error code of the type HRESULT is output. Possible values are described in the List of error codes.

METHOD ResetData : HRESULT
VAR_INPUT
END_VAR

PassInputs():

As long as an FB_CMA_Source instance is called and signal data are thus transferred to a target block, all further function blocks of the analysis chain have to be called cyclically as explained in the API PLC Reference.
Sometimes it is useful not to execute an algorithm for a certain time. For example, some algorithms should be executed only after prior training or configuration. The function block must be called cyclically, but it is sufficient for the data arriving at the function block to be forwarded in the communication ring. This is done using the PassInputs() method in place of the Call() method. The algorithm itself is not called here, and accordingly no result is calculated and no output buffer generated.

Return value: If an error occurs, a corresponding error code of the type HRESULT is output. Possible values are described in the List of error codes.

METHOD PassInputs : HRESULT
VAR_INPUT
END_VAR

GetChannelErrors():

The method enables the querying of a list of the channel-specific return values when processing several channels (nChannels > 1). A call is useful in the case that the return value of the function block corresponds to one of the values eCM_InfRTime_AmbiguousChannelResults or eCM_ErrRTime_ErrornousChannelResults.

Return value: Information on the reading process of the list of error codes. The value is set to TRUE if the query was successful, otherwise to FALSE.


    METHOD GetChannelErrors : BOOL
VAR_IN_OUT
    aChannelErrors : ARRAY[*] OF HRESULT;
END_VAR

aChannelErrors: Error list of the type HRESULT of the length nChannels.

Requirements

Development environment	Target platform	PLC libraries to include
TwinCAT v3.1.4022.25	PC or CX (x86, x64)	Tc3_CM, Tc3_CM_Base