UpperEnvelope (FPScript)
Determines an upper envelope for a signal or the indices of points in a signal that belong to its upper envelope curve.
Syntax
UpperEnvelope(Signal [ , Parameter = 0 ])
or
UpperEnvelope(Amplitude, Time, Parameter)
The syntax of the UpperEnvelope function consists of the following parts:
Part |
Description |
|---|---|
Signal |
The data set whose upper envelope is determined. If you specify a data series, then the X component will be generated automatically. Permitted data structures are data series und signal. All numeric data types are permitted. If the argument is a list, then the function is executed for each element of the list and the result is also a list. |
Amplitude |
A data series with the Y component of the signal. If you specify a signal, then its Y component is used. Permitted data structures are data series und signal. All numeric data types are permitted. If the argument is a list, then the first element in the list is taken. If this is also a list, then the process is repeated. |
Time |
A data series with the X component of the signal. If you specify a signal, then its Y component is used. Permitted data structures are data series und signal. All numeric data types are permitted. If the argument is a list, then the first element in the list is taken. If this is also a list, then the process is repeated. |
Parameter |
If this value is positive and specified without a unit, then it specifies the number of neighbors to be taken into consideration when determining the next respective sampling point. If it has the unit "%" or is specified as a negative value, it determines the hysteresis as a percentage of the range of the data set for the search for local maxima in the signal, which are then used to determine the number of neighbors. This argument is optional for the syntax variant with two arguments. If you omit the argument or pass 0, this corresponds to an hysteresis of 5%. Permitted data structures are scalar value. All numeric data types are permitted. For complex data types the absolute value is formed. If the argument is a list, then the first element in the list is taken. If this is also a list, then the process is repeated. If this argument is omitted, it will be set to the default value 0. |
Remarks
The result has the same unit as the argument Signal.
The envelope consists of a subset of values of the data set to be analyzed, which are searched for using the following algorithm. Starting with the first point, straight-line connections are calculated for a specified number of neighbors and their gradients are determined. The neighbor with the highest gradient becomes the next envelope sampling point and the algorithm is continued with this value.
You can explicitly specify the number of neighbors by specifying a positive value without a unit for Parameter. This value should then be selected in such a way that for periodic signals it spans at least one period. If you specify a value with the unit "%", then its amount is used as the argument for the Extrema function to search for all local maxima in the data set. As the number of neighbors, the greatest distance that occurs for these local maxima is then used.
If you specify a signal, the result is a signal of the same data type that contains the points belonging to the envelope. If amplitude and time are specified, then the result is a data series with 64-bit integer values that represent indices for the envelope sampling points found.
The following illustration shows a transient signal and its upper envelope:
Available in
FlexPro Basic, Professional, Developer Suite
Examples
UpperEnvelope(Signal, 10%) |
Calculates the upper envelope of the signal. An hysteresis of 10% will be used for the algorithm. |