Permalink
Switch branches/tags
Nothing to show
Find file Copy path
be5a9b5 Dec 28, 2017
1 contributor

Users who have contributed to this file

480 lines (347 sloc) 26.9 KB

GSF Grafana Functions

The Grafana interfaces defined in the Grid Solutions Framework allow for aggregation and operational functions on a per-series and per-group basis. The following defines the available functions and group operations that are available for a data source implementing the GSF Grafana interface, e.g., openHistorian. Note that any data source that implements the GrafanaDataSourceBase class will automatically inherit this functionality.

Series Functions

Various functions are available that can be applied to each series that come from a specified expression, see full list of available functions below. Series expressions can be an individual listing of point tag names, Guids or measurement keys separated by semi-colons - or - a filter expression that will select several series at once. Filter expressions and individual points, with or without functions, may be selected simultaneously when separated with semi-colons:

  • Example: PPA:15; STAT:20; SetSum(Count(PPA:8; PPA:9; PPA:10)); FILTER ActiveMeasurements WHERE SignalType IN ('IPHA', 'VPHA'); Range(PPA:99; Sum(FILTER ActiveMeasurements WHERE SignalType = 'FREQ'; STAT:12))

Many series functions have parameters that can be required or optional – optional values will always define a default state. Parameter values must be a constant value or, where applicable, a named target available from the expression. Named targets are intended to work with group operations, i.e., Set or Slice, since group operations provide access to multiple series values from within a single series. The actual value used for a named target parameter will be the first encountered value for the target series – in the case of slice group operations, this will be the first value encountered in each slice. Named target parameters can optionally specify multiple fall-back series and one final default constant value each separated by a semi-colon to use when the named target series is not available, e.g.: SliceSubtract(1, T1;T2;5.5, T1;T2;T3)

To better understand named targets, follow these example steps:

  1. The following expression produces two unwrapped voltage phase angle series:

    UnwrapAngle(DOM_GPLAINS-BUS1:VH; TVA_SHELBY-BUS1:VH)

  2. Values from one of the series can now be substracted from values in both of the series at every 1/30 of a second slice:

    SliceSubtract(0.0333, TVA_SHELBY-BUS1:VH, UnwrapAngle(DOM_GPLAINS-BUS1:VH; TVA_SHELBY-BUS1:VH))

  3. Using a Slice operation on functions that return multiple series can produce multiple values at the same timestamp, however, since values produced by one of the series will now always be zero, the zero values can be excluded:

    ExcludeRange(0, 0, SliceSubtract(0.0333, TVA_SHELBY-BUS1:VH, UnwrapAngle(DOM_GPLAINS-BUS1:VH; TVA_SHELBY-BUS1:VH)))

Execution Modes

Each of the series functions include documentation for the mode of execution required by the function. These modes determine the level of processing expense and memory burden incurred by the function. The impacts of the execution modes increase as the time-range or resolution of the series data increases.

Execution Mode Description Impact
Deferred enumeration Series data will be processed serially outside of function Minimal processing and memory impact
Immediate enumeration Series data will be processed serially inside the function Increased processing impact, minimal memory impact
Immediate in-memory array load Series data will be loaded into an array and processed inside the function Higher processing and memory impact

Group Operations

Each Grafana series function can be operated on in aggregate using a group operator prefix:

Set

Series functions can operate over the set of defined series, producing a single result series, where the target function is executed over each series, horizontally, end-to-end by prefixing the function name with Set.

  • Example: SetAverage(FILTER ActiveMeasurements WHERE SignalType='FREQ')

Slice

Series functions can operate over the set of defined series, producing a single result series, where the target function is executed over each series as a group, vertically, per time-slice by prefixing the function name with Slice. When operating on a set of series data with a slice function, a new required parameter for time tolerance will be introduced as the first parameter to the function. The parameter is a floating-point value that must be greater than or equal to zero that represents the desired time tolerance, in seconds, for the time slice.

  • Example: SliceSum(0.0333, FILTER ActiveMeasurements WHERE SignalType='IPHM')

Available Functions

Average

Returns a single value that represents the mean of the values in the source series.

  • Signature: Average(expression)
  • Returns: Single value
  • Example: Average(FILTER ActiveMeasurements WHERE SignalType='FREQ')
  • Variants: Average, Avg, Mean
  • Execution: Immediate enumeration

Minimum

Returns a single value that is the minimum of the values in the source series.

  • Signature: Minimum(expression)
  • Returns: Single value
  • Example: Minimum(FILTER ActiveMeasurements WHERE SignalType='FREQ')
  • Variants: Minimum, Min
  • Execution: Immediate enumeration

Maximum

Returns a single value that is the maximum of the values in the source series.

  • Signature: Maximum(expression)
  • Returns: Single value
  • Example: Maximum(FILTER ActiveMeasurements WHERE SignalType='FREQ')
  • Variants: Maximum, Max
  • Execution: Immediate enumeration

Total

Returns a single value that represents the sum of the values in the source series.

  • Signature: Total(expression)
  • Returns: Single value
  • Example: Total(FILTER ActiveMeasurements WHERE SignalType='IPHM')
  • Variants: Total, Sum
  • Execution: Immediate enumeration

Range

Returns a single value that represents the range, i.e., maximum - minimum, of the values in the source series.

  • Signature: Range(expression)
  • Returns: Single value
  • Example: Range(FILTER ActiveMeasurements WHERE SignalType='FREQ')
  • Variants: Range
  • Execution: Immediate enumeration

Count

Returns a single value that is the count of the values in the source series.

  • Signature: Count(expression)
  • Returns: Single value
  • Example: Count(PPA:1; PPA:2; PPA:3)
  • Variants: Count
  • Execution:Immediate enumeration

Distinct

Returns a series of values that represent the unique set of values in the source series.

  • Signature: Distinct(expression)
  • Returns: Series of values
  • Example: Distinct(FILTER ActiveMeasurements WHERE SignalType='FREQ')
  • Variants: Distinct, Unique
  • Execution: Deferred enumeration

AbsoluteValue

Returns a series of values that represent the absolute value each of the values in the source series.

  • Signature: AbsoluteValue(expression)
  • Returns: Series of values
  • Example: AbsoluteValue(FILTER ActiveMeasurements WHERE SignalType='CALC')
  • Variants: AbsoluteValue, Abs
  • Execution: Deferred enumeration

Add

Returns a series of values that represent each of the values in the source series added with N. N is a floating point value representing an additive offset to be applied to each value the source series. N can either be a constant value or a named target available from the expression.

  • Signature: Add(N, expression)
  • Returns: Series of values
  • Example: Add(1.5, FILTER ActiveMeasurements WHERE SignalType='CALC')
  • Variants: Add
  • Execution: Deferred enumeration

Subtract

Returns a series of values that represent each of the values in the source series subtracted by N. N is a floating point value representing an subtractive offset to be applied to each value the source series. N can either be a constant value or a named target available from the expression.

  • Signature: Subtract(N, expression)
  • Returns: Series of values
  • Example: Subtract(2.2, FILTER ActiveMeasurements WHERE SignalType='CALC')
  • Variants: Subtract
  • Execution: Deferred enumeration

Multiply

Returns a series of values that represent each of the values in the source series multiplied by N. N is a floating point value representing a multiplicative factor to be applied to each value the source series. N can either be a constant value or a named target available from the expression.

  • Signature: Multiply(N, expression)
  • Returns: Series of values
  • Example: Multiply(1.5, FILTER ActiveMeasurements WHERE SignalType='CALC')
  • Variants: Multiply
  • Execution: Deferred enumeration

Divide

Returns a series of values that represent each of the values in the source series divided by N. N is a floating point value representing a divisive factor to be applied to each value the source series. N can either be a constant value or a named target available from the expression.

  • Signature: Divide(N, expression)
  • Returns: Series of values
  • Example: Divide(1.732, FILTER ActiveMeasurements WHERE SignalType='CALC')
  • Variants: Divide
  • Execution: Deferred enumeration

Round

Returns a series of values that represent the rounded value, with N fractional digits, of each of the values in the source series. N, optional, is a positive integer value representing the number of decimal places in the return value - defaults to 0. N can either be a constant value or a named target available from the expression. Any target values that fall between 0 and 1 will be treated as a percentage.

  • Signature: Round([N = 0], expression)
  • Returns: Series of values
  • Example: Round(3, FILTER ActiveMeasurements WHERE SignalType='FREQ')
  • Variants: Round
  • Execution: Deferred enumeration

Floor

Returns a series of values that represent the smallest integral value that is less than or equal to each of the values in the source series.

  • Signature: Floor(expression)
  • Returns: Series of values
  • Example: Floor(FILTER ActiveMeasurements WHERE SignalType='IPHM')
  • Variants: Floor
  • Execution: Deferred enumeration

Ceiling

Returns a series of values that represent the smallest integral value that is greater than or equal to each of the values in the source series.

  • Signature: Ceiling(expression)
  • Returns: Series of values
  • Example: Ceiling(FILTER ActiveMeasurements WHERE SignalType='IPHM')
  • Variants: Ceiling, Ceil
  • Execution: Deferred enumeration

Truncate

Returns a series of values that represent the integral part of each of the values in the source series.

  • Signature: Truncate(expression)
  • Returns: Series of values
  • Example: Truncate(FILTER ActiveMeasurements WHERE SignalType='IPHM')
  • Variants: Truncate, Trunc
  • Execution: Deferred enumeration

StandardDeviation

Returns a single value that represents the standard deviation of the values in the source series. First parameter, optional, is a boolean flag representing if the sample based calculation should be used - defaults to false, which means the population based calculation should be used.

  • Signature: StandardDeviation([useSampleCalc = false], expression)
  • Returns: Single value
  • Example: StandardDeviation(FILTER ActiveMeasurements WHERE SignalType='VPHM')
  • Variants: StandardDeviation, StdDev
  • Execution: Immediate in-memory array load

Median

Returns a single value that represents the median of the values in the source series.

  • Signature: Median(expression)
  • Returns: Single value
  • Example: Median(FILTER ActiveMeasurements WHERE SignalType='ALOG')
  • Variants: Median, Med, Mid
  • Execution: Immediate in-memory array load

Mode

Returns a single value that represents the mode of the values in the source series.

  • Signature: Mode(expression)
  • Returns: Single value
  • Example: Mode(FILTER TOP 5 ActiveMeasurements WHERE SignalType='DIGI')
  • Variants: Mode
  • Execution: Immediate in-memory array load

Top

Returns a series of N, or N% of total, values that are the largest in the source series. N is either a positive integer value, representing a total, that is greater than zero - or - a floating point value, suffixed with '%' representing a percentage, that must range from greater than 0 to less than or equal to 100. Second parameter, optional, is a boolean flag representing if time in dataset should be normalized - defaults to true. N can either be a constant value or a named target available from the expression. Any target values that fall between 0 and 1 will be treated as a percentage.

  • Signature: Top(N|N%, [normalizeTime = true], expression)
  • Returns: Series of values
  • Example: Top(50%, FILTER ActiveMeasurements WHERE SignalType='FREQ')
  • Variants: Top, Largest
  • Execution: Immediate in-memory array load

Bottom

Returns a series of N, or N% of total, values that are the smallest in the source series. N is either a positive integer value, representing a total, that is greater than zero - or - a floating point value, suffixed with '%' representing a percentage, that must range from greater than 0 to less than or equal to 100. Second parameter, optional, is a boolean flag representing if time in dataset should be normalized - defaults to true. N can either be a constant value or a named target available from the expression. Any target values that fall between 0 and 1 will be treated as a percentage.

  • Signature: Bottom(N|N%, [normalizeTime = true], expression)
  • Returns: Series of values
  • Example: Bottom(100, false, FILTER ActiveMeasurements WHERE SignalType='FREQ')
  • Variants: Bottom, Bot, Smallest
  • Execution: Immediate in-memory array load

Random

Returns a series of N, or N% of total, values that are a random sample of the values in the source series. N is either a positive integer value, representing a total, that is greater than zero - or - a floating point value, suffixed with '%' representing a percentage, that must range from greater than 0 to less than or equal to 100. Second parameter, optional, is a boolean flag representing if time in dataset should be normalized - defaults to true. N can either be a constant value or a named target available from the expression. Any target values that fall between 0 and 1 will be treated as a percentage.

  • Signature: Random(N|N%, [normalizeTime = true], expression)
  • Returns: Series of values
  • Example: Random(25%, FILTER ActiveMeasurements WHERE SignalType='VPHM')
  • Variants: Random, Rand, Sample
  • Execution: Immediate in-memory array load

First

Returns a series of N, or N% of total, values from the start of the source series. N, optional, is either a positive integer value, representing a total, that is greater than zero - or - a floating point value, suffixed with '%' representing a percentage, that must range from greater than 0 to less than or equal to 100 - defaults to 1. N can either be a constant value or a named target available from the expression. Any target values that fall between 0 and 1 will be treated as a percentage.

  • Signature: First([N|N% = 1], expression)
  • Returns: Series of values
  • Example: First(5%, FILTER ActiveMeasurements WHERE SignalType='FREQ')
  • Variants: First
  • Execution: Immediate in-memory array load

Last

Returns a series of N, or N% of total, values from the end of the source series. N, optional, is either a positive integer value, representing a total, that is greater than zero - or - a floating point value, suffixed with '%' representing a percentage, that must range from greater than 0 to less than or equal to 100 - defaults to 1. N can either be a constant value or a named target available from the expression. Any target values that fall between 0 and 1 will be treated as a percentage.

  • Signature: Last([N|N% = 1], expression)
  • Returns: Series of values
  • Example: Last(150, FILTER ActiveMeasurements WHERE SignalType='FREQ')
  • Variants: Last
  • Execution: Immediate in-memory array load

Percentile

Returns a single value that represents the Nth order percentile for the sorted values in the source series. N is a floating point value, representing a percentage, that must range from 0 to 100.

  • Signature: Percentile(N[%], expression)
  • Returns: Single value
  • Example: Percentile(10%, FILTER ActiveMeasurements WHERE SignalType='VPHM')
  • Variants: Percentile, Pctl
  • Execution: Immediate in-memory array load

Difference

Returns a series of values that represent the difference between consecutive values in the source series.

  • Signature: Difference(expression)
  • Returns: Series of values
  • Example: Difference(FILTER ActiveMeasurements WHERE SignalType='FREQ')
  • Variants: Difference, Diff
  • Execution: Deferred enumeration

TimeDifference

Returns a series of values that represent the time difference, in time units, between consecutive values in the source series. The units parameter, optional, specifies the type of time units and must be one of the following: Seconds, Nanoseconds, Microseconds, Milliseconds, Minutes, Hours, Days, Weeks, Ke (i.e., traditional Chinese unit of decimal time), Ticks (i.e., 100-nanosecond intervals), PlanckTime or AtomicUnitsOfTime - defaults to Seconds.

  • Signature: TimeDifference([units = Seconds], expression)
  • Returns: Series of values
  • Example: TimeDifference(FILTER ActiveMeasurements WHERE SignalType='FREQ')
  • Variants: TimeDifference, TimeDiff, Elapsed
  • Execution: Deferred enumeration

Derivative

Returns a series of values that represent the rate of change, per time units, for the difference between consecutive values in the source series. The units parameter, optional, specifies the type of time units and must be one of the following: Seconds, Nanoseconds, Microseconds, Milliseconds, Minutes, Hours, Days, Weeks, Ke (i.e., traditional Chinese unit of decimal time), Ticks (i.e., 100-nanosecond intervals), PlanckTime or AtomicUnitsOfTime - defaults to Seconds.

  • Signature: Derivative([units = Seconds], expression)
  • Returns: Series of values
  • Example: Derivative(FILTER ActiveMeasurements WHERE SignalType='FREQ')
  • Variants: Derivative, Der
  • Execution: Deferred enumeration

TimeIntegration

Returns a single value that represents the time-based integration, i.e., the sum of V(n) * (T(n) - T(n-1)) where time difference is calculated in the specified time units, of the values in the source series. The units parameter, optional, specifies the type of time units and must be one of the following: Seconds, Nanoseconds, Microseconds, Milliseconds, Minutes, Hours, Days, Weeks, Ke (i.e., traditional Chinese unit of decimal time), Ticks (i.e., 100-nanosecond intervals), PlanckTime or AtomicUnitsOfTime - defaults to Hours.

  • Signature: TimeIntegration([units = Hours], expression)
  • Returns: Single value
  • Example: TimeIntegration(FILTER ActiveMeasurements WHERE SignalType='CALC' AND PointTag LIKE '%-MW:%')
  • Variants: TimeIntegration, TimeInt
  • Execution: Immediate enumeration

Interval

Returns a series of values that represent a decimated set of the values in the source series based on the specified interval N, in time units. N is a floating-point value that must be greater than or equal to zero that represents the desired time interval, in time units, for the returned data. The units parameter, optional, specifies the type of time units and must be one of the following: Seconds, Nanoseconds, Microseconds, Milliseconds, Minutes, Hours, Days, Weeks, Ke (i.e., traditional Chinese unit of decimal time), Ticks (i.e., 100-nanosecond intervals), PlanckTime or AtomicUnitsOfTime - defaults to Seconds. Setting N value to zero will request non-decimated, full resolution data from the data source. A zero N value will always produce the most accurate aggregation calculation results but will increase query burden on data source for large time ranges. N can either be a constant value or a named target available from the expression.

  • Signature: Interval(N, [units = Seconds], expression)
  • Returns: Series of values
  • Example: Sum(Interval(0, FILTER ActiveMeasurements WHERE SignalType LIKE '%PHM'))
  • Variants: Interval
  • Execution: Deferred enumeration

IncludeRange

Returns a series of values that represent a filtered set of the values in the source series where each value falls between the specified low and high. The low and high parameter values are floating-point numbers that represent the range of values allowed in the return series. Third parameter, optional, is a boolean flag that determines if range values are inclusive, i.e., allowed values are >= low and <= high - defaults to false, which means values are exclusive, i.e., allowed values are > low and < high. Function allows a fourth optional parameter that is a boolean flag - when four parameters are provided, third parameter determines if low value is inclusive and forth parameter determines if high value is inclusive. The low and high parameter values can either be constant values or named targets available from the expression.

  • Signature: IncludeRange(low, high, [inclusive = false], expression) -or- IncludeRange(low, high, [lowInclusive = false], [highInclusive = false], expression)
  • Returns: Series of values
  • Example: IncludeRange(59.90, 60.10, FILTER ActiveMeasurements WHERE SignalType='FREQ')
  • Variants: IncludeRange, Include
  • Execution: Deferred enumeration

ExcludeRange

Returns a series of values that represent a filtered set of the values in the source series where each value falls outside the specified low and high. The low and high parameter values are floating-point numbers that represent the range of values excluded in the return series. Third parameter, optional, is a boolean flag that determines if range values are inclusive, i.e., excluded values are <= low or >= high - defaults to false, which means values are exclusive, i.e., excluded values are < low or > high. Function allows a fourth optional parameter that is a boolean flag - when four parameters are provided, third parameter determines if low value is inclusive and forth parameter determines if high value is inclusive. The low and high parameter values can either be constant values or named targets available from the expression.

  • Signature: ExcludeRange(low, high, [inclusive = false], expression) -or- ExcludeRange(low, high, [lowInclusive = false], [highInclusive = false], expression)
  • Returns: Series of values
  • Example: ExcludeRange(-180.0, 180.0, true, false, FILTER ActiveMeasurements WHERE SignalType LIKE '%PHA')
  • Variants: ExcludeRange, Exclude
  • Execution: Deferred enumeration

FilterNaN

Returns a series of values that represent a filtered set of the values in the source series where each value is a real number, i.e., value is not NaN. First parameter, optional, is a boolean flag that determines if infinite values should also be excluded - defaults to true.

  • Signature: FilterNaN([alsoFilterInfinity = true], expression)
  • Returns: Series of values
  • Example: FilterNaN(FILTER ActiveMeasurements WHERE SignalType='VPHM')
  • Variants: FilterNaN
  • Execution: Deferred enumeration

UnwrapAngle

Returns a series of values that represent an adjusted set of angles that are unwrapped, per specified angle units, so that a comparable mathematical operation can be executed. For example, for angles that wrap between -180 and +180 degrees, this algorithm unwraps the values to make the values mathematically comparable. The units parameter, optional, specifies the type of angle units and must be one of the following: Degrees, Radians, Grads, ArcMinutes, ArcSeconds or AngularMil - defaults to Degrees.

  • Signature: UnwrapAngle([units = Degrees], expression)
  • Returns: Series of values
  • Example: UnwrapAngle(FSX_PMU2-PA1:VH; REA_PMU3-PA2:VH)
  • Variants: UnwrapAngle, Unwrap
  • Execution: Immediate in-memory array load

WrapAngle

Returns a series of values that represent an adjusted set of angles that are wrapped, per specified angle units, so that angle values are consistently between -180 and +180 degrees. The units parameter, optional, specifies the type of angle units and must be one of the following: Degrees, Radians, Grads, ArcMinutes, ArcSeconds or AngularMil - defaults to Degrees.

  • Signature: WrapAngle([units = Degrees], expression)
  • Returns: Series of values
  • Example: WrapAngle(Radians, FILTER TOP 5 ActiveMeasurements WHERE SignalType LIKE '%PHA')
  • Variants: WrapAngle, Wrap
  • Execution: Deferred enumeration

Label

Renames a series with the specified label value. If multiple series are targeted, labels will be indexed starting at one, e.g., if there are three series in the target expression with a label value of "Max", series would be labeled as "Max 1", "Max 2" and "Max 3". Group operations on this function will be ignored. The label parameter also supports substitutions when root target metadata can be resolved. For series values that directly map to a point tag, metadata value substitutions for the tag can be used in the label value - for example: {ID}, {SignalID}, {PointTag}, {AlternateTag}, {SignalReference}, {Device}, {FramesPerSecond}, {Protocol}, {ProtocolType}, {SignalType}, {EngineeringUnits}, {PhasorType}, {Company}, {Description} - where applicable, these substitutions can be used in any combination.

  • Signature: Label(value, expression)
  • Returns: Series of values
  • Example: Label('AvgFreq', SetAvg(FILTER TOP 20 ActiveMeasurements WHERE SignalType='FREQ'))
  • Variants: Label, Name
  • Execution: Deferred enumeration