FB_CMA_MomentCoefficients
Calculates the average value, the empirical standard deviation, the skew and the excess for single- and multi-channel real-valued time series.
The function block treats the input signal as a time series, if necessary with several independent channels. For each channel the moment coefficients are calculated, optionally up to the fourth order. The maximum order of the moments to be calculated can be configured via the parameter nOrder. A specific enumeration for application of the moment coefficients is also available: E_CM_MCoefOrder. The result is forwarded as an array of these coefficients with corresponding indices.
By default no Bessel's correction is applied for the calculation of the empirical standard deviation, the skew and the excess. In the initialization parameters the correction can optionally be switched on, see bPopulationEstimates. The parameter should be set to TRUE, in order to obtain results that meet expectations. The influence of Bessel's correction becomes smaller with increasing sample size. The relative deviation between the corrected and the non-corrected empirical standard deviation can be determined unambiguously. The following table provides clues:
Sample size N | Relative deviation / % |
10 | -5.13 |
100 | -0.501 |
1000 | -0,05001 |
10000 | -0,0050001 |
Output from the function block: The random sample scope N (for all nOrder), the arithmetical mean value (nOrder = 1), the empirical standard deviation (nOrder = 2), the skew (nOrder = 3), the excess (nOrder = 4).
Definition of empirically calculated moments
The arithmetic mean value
The empirical standard deviation, without Bessel's correction
The empirical standard deviation, with Bessel's correction
The empirical skew (without Bessel's correction v‘ and with correction v))
The empirical excess (without Bessel's correction E‘ and with correction E)
The excess E is therefore the difference between the kurtosis K and the value 3; this corresponds to the kurtosis of the normal distribution. It describes the evaluation of the calculated kurtosis in terms of a normal distribution.
A single sample per channel (see Inputs and Outputs, first table) can be added in each cycle, and several samples per channel can be added to the sample quantity in one cycle (see Inputs and Outputs, second table).
Further comments
The calculation of the standard deviation and higher moments requires a minimum number of sample values. If Bessel's correction is inactive, the mean value and the standard deviation are calculated for a sample size of 1. Two values are required for calculating the skew and the excess. If Bessel's correction is active, the minimum sample size required corresponds to the order (mean value - 1, standard deviation - 2, skew - 3, excess - 4). In addition, for calculating skew and excess the variance cannot be null.
Results for higher moments may become imprecise, if the input values differ by many orders of magnitude.
Memory properties
The sample quantity N, which is used to calculate the current result, automatically increases with each new incoming data set, i.e. the function block uses all input values since its instantiation. Resetting of the sample quantity to zero (deleting the internal memory of the FB) is provided by a ResetData() method or, if the CallEx() method is used, by the variable bResetData.
NaN occurrence
If the number of input values is insufficient for calculating a result for a particular channel or the variance is zero, the value NaN (not a number) according to IEEE 754 is returned for this channel. The presence of this error value can be checked with the function LrealIsNaN(). The reason may be that so far not enough input data were transferred or that only NaNs were transferred as input values for individual channels. A variance of zero may occur if the time series of the values is constant, for example if no sensor data were transferred due to a broken wire or switching errors.
If a set of input values contains the special constant NaN, no value is added to the statistics for this channel for this time step, i.e. it is treated as indicator for missing 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().
When processing several subchannels (nSubChannels > 0), particular attention must be paid to the formatting of the input and output data. If the input data consist of a multi-channel result of an upstream function block, the value of nChannels must be adopted; further configuration takes place in this case via the parameter nSubChannels.
Sample: In the statistical consideration (e.g. by FB_CMA_Quantiles) of the frequency channels of a multi-channel spectrum (e.g. FB_CMA_MagnitudeSpectrum), the value of nChannels must be identical to the number of input signals; the number of subchannels nSubChannels corresponds to the length of the spectrum.
Inputs and outputs
The input and output buffers correspond to the following definition (Shape). The variable parameters are part of the function block input stInitPars.
Versions | Input buffer (MultiArray input stream) | Output buffer (MultiArray output stream) |
|---|---|---|
Standard version |
|
|
Standard version for several data sets |
|
|
Multi-channel version |
|
|
Multi-channel version for several data sets |
|
|
*: The length of this dimension can be selected as desired and can thus adapt itself to the application or to the output buffer of the preceding algorithm.
VAR_INPUT
stInitPars : ST_CM_MomentCoefficients_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_MomentCoefficients_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 isTRUEif an error occurs. -
hrErrorCode: If an error occurs, a corresponding error code of the typeHRESULTis 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
METHOD Init : HRESULT
VAR_INPUT
stInitPars : ST_CM_MomentCoefficients_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
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
HRESULTis 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 isTRUEif an error occurs.hrErrorCode: If an error occurs, a corresponding error code of the typeHRESULTis 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. |
CallEx():
The method is called in each cycle in order to update the internal memory from the input signal. A result is output only every nAppendData cycles. An alternative method is Call().
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
HRESULTis output. Possible values are described in the List of error codes.
METHOD CallEx : HRESULT
VAR_INPUT
nAppendData : UDINT; // count of data buffers which are appended until calculation (1= calculate always)
bResetData : BOOL; // automatic reset of dataset buffer after each calculation
END_VAR
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
nAppendData: Defines how many input data buffers are to be collected before a calculation is carried out, because several data blocks are preferably added in order to achieve a precise result.bResetData: If set, the internal data buffer is completely deleted after calculation.bError: The output isTRUEif an error occurs.hrErrorCode: If an error occurs, a corresponding error code of the typeHRESULTis 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. |
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
HRESULTis output. Possible values are described in the List of error codes.
stInitPars: Function-block-specific structure with initialization parameters of the type ST_CM_MomentCoefficients_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
HRESULTis output. Possible values are described in the List of error codes.
METHOD ResetData : HRESULT
VAR_INPUT
END_VAR
Alternatively the automatic reset in the method CallEx() can be used.
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
HRESULTis 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
TRUEif the query was successful, otherwise toFALSE.
METHOD GetChannelErrors : BOOL
VAR_IN_OUT
aChannelErrors : ARRAY[*] OF HRESULT;
END_VAR
-
aChannelErrors: Error list of the typeHRESULTof the lengthnChannels.
Similar function blocks
The function block FB_CMA_EmpiricalMean calculates the empirical average of input values.
The function block FB_CMA_EmpiricalStandardDeviation calculates the empirical standard deviation of input values.
The function block FB_CMA_EmpiricalSkew calculates the empirical skew of input values.
The function block FB_CMA_EmpiricalExcess calculates the empirical excess of input values.
The FB_CMA_HistArray function block calculates the histograms of input value distributions.
The FB_CMA_Quantiles function block calculates the quantiles of an empirical distribution, which enable the frequency of outliers to be assessed.
As an alternative to the kurtosis the FB_CMA_CrestFactor function block calculates a different measure for peakiness (Crest Factor) of a signal, although this is more sensitive to outliers.
Requirements
Development environment | Target platform | PLC libraries to include |
|---|---|---|
TwinCAT v3.1.4022.25 | PC or CX (x86, x64) | Tc3_CM, Tc3_CM_Base |
| Limited functional scope already available with CM 3.1. See section Compatibility. |