0

Available Functions of the Calculation Server (version 23)

  • updated 7 mths ago

The functions available within the Calculation Server can be categorized in three different ways:

  1. Standard OPC Foundation aggregates
  2. NCALC functions and operators
  3. Custom functions developed by Canary

An example of each of these functions are included at the top of this page if the user wishes to import them into their Calculation Server. Note, these examples are taken from v21.4 which also includes Events. It is recommended to upgrade to 21.4 prior to importing these calculations.

OPC Foundation Aggregates

For most aggregates, the expression syntax is simply:

FunctionName('[TagPath]','Duration')

Whenever the calculation is triggered (whether it be 'Value Change' or 'Periodic'), the interval over which the aggregate is calculated is Now - Duration.

Starting in v21.4, a new optional parameter has been added to include a start time:

FunctionName('[TagPath]','Duration', 'startTime')

In this case, the interval used is startTime + Duration.

Duration can be expressed using a relative or actual time. For example,

  • 1second = 1s = 00:00:01
  • 1minute = 1m = 00:01:00
  • 1hour = 1h = 1:00:00
  • 1day = 1d = 1.00:00:00
  • 1week = 1w = 7.00:00:00
  • 1month
  • 1year = 1y

StartTimes can also use the same syntax. For example,

Maximum2('[TagName]', '1d', 'd-7d')

finds the max daily value from 7 days ago. We use 'd' to normalize to the beginning of the day, then subtract '7d' or seven days.

 

Function

Description

Syntax

Average

Retrieve the average value of the data over the interval.

Average('[TagName]','Duration') Average('[TagName]','Duration','startTime')

Count

Retrieve the number of raw values over the interval.

Count('[TagName]','Duration') Count('[TagName]','Duration','startTime')

CountInStateNonZero/Zero

Retrieve the number of times a Boolean or numeric was in a non-zero/zero state using Simple Bounding Values.

CountInStateNonZero('[TagName]','Duration') CountInStateZero('[TagName]','Duration','startTime')

Delta

Retrieve the difference between the Start and End value in the interval.

Delta('[TagName]','Duration') Delta('[TagName]','Duration','startTime')

DeltaBounds

Retrieve the difference between the StartBound and EndBound value in the interval.

DeltaBounds('[TagName]','Duration') DeltaBounds('[TagName]','Duration','startTime')

DurationBad/Good

Retrieve the total duration of time in the interval during which the data is Bad/Good.

DurationBad('[TagName]','Duration') DurationGood('[TagName]','Duration','startTime')

DurationInStateNonZero/Zero

Retrieve the time a Boolean or numeric was in a non-zero/zero state using Simple Bounding Values.

DurationInStateNonZero('[TagName]','Duration') DurationInStateZero('[TagName]','Duration','startTime')

EndBound

Retrieve the value at the end of the interval using Simple Bounding Values.

EndBound('[TagName]','Duration') EndBound('[TagName]','Duration','startTime')

Interpolative

At the beginning of each interval, retrieve the calculated value from the data points on either side of the requested timestamp.

Interpolative('[TagName]','Duration') Interpolative('[TagName]','Duration','startTime')

Maximum

Retrieve the maximum raw value in the interval with the timestamp of the start of the interval.

Maximum('[TagName]','Duration') Maximum('[TagName]','Duration','startTime')

Maximum2

Retrieve the maximum value in the interval including the Simple Bounding Values.

Maximum2('[TagName]','Duration') Maximum2('[TagName]','Duration','startTime')

Minimum

Retrieve the minimum raw value in the interval with the timestamp of the start of the interval.

Minimum('[TagName]','Duration') Minimum('[TagName]','Duration','startTime')

Minimum2

Retrieve the minimum value in the interval including the Simple Bounding Values.

Minimum2('[TagName]','Duration') Minimum2('[TagName]','Duration','startTime')

NumberOfTransitions

Retrieve the number of changes between zero and non-zero that a Boolean or numeric value experienced in the interval.

NumberOfTransitions('[TagName]','Duration') NumberOfTransitions('[TagName]','Duration','startTime')

PercentBad/Good

 Retrieve the percentage of data (0 to 100) in the interval which has Bad/Good StatusCode.

PercentBad('[TagName]','Duration') PercentGood('[TagName]','Duration','startTime')

Range

 Retrieve the difference between the minimum and maximum value over the interval.

Range('[TagName]','Duration') Range('[TagName]','Duration','startTime')

Range2

Retrieve the difference between the Minimum2 and Maximum2 value over the interval.

Range2('[TagName]','Duration') Range2('[TagName]','Duration','startTime')

StandardDeviationPopulation

Retrieve the standard deviation for the interval for a complete population (n) which includes Simple Bounding Values.

StandardDeviationPopulation('[TagName]','Duration') StandardDeviationPopulation('[TagName]','Duration','startTime')

StandardDeviationSample

Retrieve the standard deviation for the interval for a sample of the population (n-1).

StandardDeviationSample('[TagName]','Duration') StandardDeviationSample('[TagName]','Duration','startTime')

StartBound

Retrieve the value at the beginning of the interval using Simple Bounding Values.

StartBound('[TagName]','Duration') StartBound('[TagName]','Duration','startTime')

TimeAverage

Retrieve the time weighted average data over the interval using Interpolated Bounding Values.

TimeAverage('[TagName]','Duration') TimeAverage('[TagName]','Duration','startTime')

TimeAverage2

Retrieve the time weighted average data over the interval using Simple Bounding Values.

TimeAverage2('[TagName]','Duration') TimeAverage2('[TagName]','Duration','startTime')

Total

Retrieve the total (time integral) of the data over the interval using Interpolated Bounding Values.

Total('[TagName]','Duration') Total('[TagName]','Duration','startTime')

Total2

Retrieve the total (time integral in seconds) of the data over the interval using Simple Bounding Values.

Total2('[TagName]','Duration') Total2('[TagName]','Duration','startTime')

TotalPer24Hours

Retrieve the total (time integral in 24 hours) of the data over the interval using Simple Bounding Values.

TotalPer24Hours('[TagName]','Duration') TotalPer24Hours('[TagName]','Duration','startTime')

TotalPerHour

Retrieve the total (time integral in hours) of the data over the interval using Simple Bounding Values.

TotalPerHour('[TagName]','Duration') TotalPerHour('[TagName]','Duration','startTime')

TotalPerMinute

Retrieve the total (time integral in minutes) of the data over the interval using Simple Bounding Values.

TotalPerMinute('[TagName]','Duration') TotalPerMinute('[TagName]','Duration','startTime')

VariancePopulation

Retrieve the variance for the interval as calculated by the StandardDeviationPopulation which includes Simple Bounding Values.

VariancePopulation('[TagName]','Duration') VariancePopulation('[TagName]','Duration','startTime')

VarianceSample

Retrieve the variance for the interval as calculated by the StandardDeviationSample.

VarianceSample('[TagName]','Duration') VarianceSample('[TagName]','Duration','startTime')

WorstQuality

Retrieve the worst StatusCode of data in the interval.

WorstQuality('[TagName]','Duration') WorstQuality('[TagName]','Duration','startTime')

WorstQuality2

Retrieve the worst StatusCode of data in the interval including the Simple Bounding Values.

WorstQuality2('[TagName]','Duration') WorstQuality2('[TagName]','Duration','startTime')

NCalc Functions

Functions

Definition

Syntax

Absolute Value

Returns the absolute value of a specified number.

Abs(-1)
Abs([TagName])

CanaryAnd

Evaluates an array of expressions and returns true if all expressions are true.

CanaryAnd([tag1] = 1, [tag2] < 10, [tagN] >= 1)

CanaryOr

Evaluates an Array of values and returns true if at least one is true.

CanaryOr([tag1] = 1, [tag2] = 1, [tagN] = 1)

Ceiling

Retrieves the smallest integer greater than or equal to the specified number.

Ceiling([TagName])

Floor

Retrieves the largest integer less than or equal to the specified number.

Floor([TagName])

Functions of Trigonometry

Returns the sin, cos, tan, arcsin, arccos, and arctan of the specified number.

Sin([TagName])
Atan([TagName])

if

Returns a value based on a condition.

if([TagName]>0, [TagName], False)

in

Returns True/False whether an element is in a set of values where the first element in the array is the value to be compared.

in(1+1, 1, 2, 3)

Log

Returns the logarithm of a specified number.

Log(1,10)

Log10

Returns the base 10 logarithm of a specified number.

Log10(1)

Pow

Returns a number raised to the specified power.

Pow(3,2)

Round

Rounds a value to the nearest integer or specified number of decimal places.

Round('3.222','2')

Sqrt

Returns the square root of a specified number.

Sqrt(4)

Switch

Select an output value based on which match contains the same value as the compare key.

Switch(compareKey, match1, value1, match2, value2...,defaultValue)

Any number of matches and values are allowed, but each match needs a value and vice-versa. For each of the parameters in the function, any expression is allowed. You can use constant values, aggregates, variables, tag values, etc.

Example: "Switch ([localhost.Testing.Tag1], 1,[localhost.Testing.Tag2], var1 + 2, [localhost.Testing.Tag3], [localhost.Testing.Tag4])"

Where Tag2 is the output when Tag1 is equal to 1, Tag 3 is the output when Tag1 is equal to var1 + 2, and Tag4 is the default value that is output when none of the other conditions are met.

Truncate

Calculates the integral part of a number.

Truncate(1.234)

Custom Functions

The following have been built by Canary to address typical historian based analytics.

Functions

Definition

Syntax

AssetInstanceCount

Returns the total number of asset instances of the specified type under a source path.

AssetInstanceCount('sourcePath', 'assetType')

DeltaTotalCount

Retrieves the total delta (change) of values for an accumulation tag that resets periodically.

DeltaTotalCount('[TagName','Duration') DeltaTotalCount('[TagName','Duration','startTime')

DurationSinceDateTime

Retrieves the time in milliseconds since the date and/or time specified by the dateTimeString.

DurationSinceDateTime('dateTimeString')

Note: Datetimes can be relative (d+6h) or actual (6:00). TagNames can also be passed in if they have a valid string type that can be parsed. For example,

DurationSinceDateTime('d +'+[StringTag])

where [StringTag] = '6h'

DurationSinceLastHistorianUpdate

Retrieve the time in milliseconds since a tag received an update, regardless of whether the value or quality changed.

DurationSinceLastHistorianUpdate('[TagName]')

Note: The next 'DurationSinceLastTVQ' function should be used instead of this function in most situations.

DurationSinceLastTVQ

Retrieve the time in milliseconds since a tag's value or quality changed.

DurationSinceLastTVQ ('[TagName]', optional bool ignoreBadValueChanges)

If ignoreBadValueChanges is set to true, it changes the behavior of the function so that bad or NoData quality TVQs do not reset the duration and instead only set the output quality to uncertain. Additionally, it keeps the function from resetting the duration because of an uncertain quality.

IsQualityBad/Good/Uncertain

Returns True if the quality is Bad/Good/Uncertain, otherwise returns False. Typically used in conjunction with the 'Quality' function.

IsQualityBad(Quality([TagName]))

NoOutput

Does not output tag values. Typically used within an 'if' statement.

if([Tagname]>0, [TagName],NoOutput())

Starting in 21.4, the 'NoOutput' function can be utilized within the 'Quality Override' parameters of the expression. Both the 'If True' and 'If False' parameters will accept NoOutput as an input.

Property

Retrieves the value of a tag property.

Property('[TagName]', 'PropertyName')

Quality

Retrieves the latest quality for a tag.

Quality('[TagName]')

Common quality codes include 192 (Good), 0 (Bad), 64 (Uncertain), 32768 (NoData).

ResettingAnchoredInterval

Calculates an aggregate with an interval that continues to grow over a length of time, and then resets after a certain duration.

ResettingAnchoredInterval('aggregateName', '[TagName]', 'resetInterval', 'optional resetOffset')

Example: ResettingAnchoredInterval('Maximum2', '[TagName]', '1d', '9h')

This finds the maximum value as it evaluates, periodically or by value change, throughout a 1 day interval from 9am to 9am. At 9am, it resets and starts a new interval.

Rollup

Calculates a sum, count, average, or min/max of a specified tag for all child assets of the specified parent asset type. This function can ony be used as an asset-based calculation and must run Periodically.

Rollup('sourcePath', 'operation', 'child assetType', 'child assetTag', 'optional assetFilterExpression')

Operations include: SUM, COUNT, AVERAGE, MINIMUM, MAXIMUM.

Example: Rollup('VirtualView.%Asset%','SUM','Pump','Pressure') where 'Pump' is a child asset of the configured 'Well' parent asset and 'Pressure' is a pump tag.

The assetFilterExpression may be any valid calculation expression and will be applied to the rollup assets to determine which to use and which to skip. If the expression returns false for a particular asset, that asset will not be included in the rollup. Use %RollupAsset% to target tags relative to the asset being rolled up.

Example: Rollup('VirtualView.%Asset%','SUM','Pump','Pressure',[%RollupAsset%.Running]=True)

In this example, only pumps that have the Running tag equal True will be rolled up.

SetOutputQuality

Sets the output tag value quality.

SetOutputQuality(quality)

Quality can be represented in its string format or decimal equivalent. Common qualities include: Good(192), Bad(0), Uncertain(64), and NoData(32768). Starting in 21.4, the 'Quality Override' parameters of the expression can be used in place of this function. Both the 'If True' and 'If False' parameters will accept the string and decimal quality format.

TagIfExists

Returns the value of the tag if it exists, otherwise returns the fallback value.

TagIfExists ('[TagName]', fallbackValue)

fallbackValue can be a number or a string but can't be a tag, an aggregate, or a variable.

Reply Oldest first
  • Oldest first
  • Newest first
  • Active threads
  • Popular