Historical Functions

Historical functions retrieve and analyze historical data for a specified variable and time range. Because these functions access historical storage, they can take longer to execute than non-historical functions.

Function Reference:

Function

Name

Description

Format

Returned Value

tagfind

Find Timestamp

Returns the first timestamp matching the specified criteria.

tagfind(variable,startTime,endTime,comparisonType,comparisonValue)

variable: Specifies the internal data variable to evaluate.
startTime: Specifies the beginning of the time range.
endTime: Specifies the end of the time range.
comparisonType: Specifies the comparison operator.
comparisonValue: Specifies the value to compare against.

DateTime

tagfindstate

Find Timestamp for State

Returns the first timestamp matching a specified Boolean state.

tagfindstate(variable,startTime,endTime,boolState)
variable: Specifies the internal data variable to evaluate.
startTime:: Specifies the beginning of the time range.
endTime: Specifies the end of the time range.
boolState: Specifies the state to search for.

DateTime

tagavg

Average

Returns the average value.

tagavg(variable,startTime,endTime,percentGood)
variable: Specifies the internal data variable to evaluate.
startTime: Specifies the beginning of the time range.
endTime: Specifies the end of the time range.
percentGood: Specifies the required percentage of good samples.

DataValue

tagtavg

Time Weighted Average

Returns the time-weighted average value.

tagtavg
Same parameters as tagavg.

DataValue

tagtotalize

Totalize

Returns the time-weighted total. Learn more.

tagtotalize
Same parameters as tagavg.

DataValue

tagtotal

Total

Returns the simple sum of the sample values. Learn more.

tagtotal
Same parameters as tagavg.

DataValue

tagmin

Minimum

Returns the minimum value.

tagmin
Same parameters as tagavg.

DataValue

tagmax

Maximum

Returns the maximum value.

tagmax
Same parameters as tagavg.

DataValue

tagdelta

Delta

Returns the difference between the first and last good values.

tagdelta
Same parameters as tagavg.

DataValue

tagrange

Range

Returns the difference between the maximum and minimum values.

tagrange
Same parameters as tagavg.

DataValue

tagcount

Samples Count

Returns the number of samples.

tagcount
Same parameters as tagavg.

DataValue

tagtimestate0

Time Duration in State 0

Returns the duration spent in state 0.

tagtimestate0
Same parameters as tagavg.

DataValue

tagtimestate1

Time Duration in State 1

Returns the duration spent in a nonzero state.

tagtimestate1
Same parameters as tagavg.

DataValue

tagntrans

Number of Transitions

Returns the number of state transitions.

tagntrans
Same parameters as tagavg.

DataValue

tagpctgood

Percent Good

Returns the percentage of time with good quality.

tagpctgood(variable,startTime,endTime)
Parameters described in tagtime.

DataValue

tagpctbad

Percent Bad

Returns the percentage of time with bad quality.

tagpctbad(variable,startTime,endTime)
Parameters described in tagtime.

DataValue

tagtimegood

Good Quality Duration

Returns the duration with good quality.

tagtimegood(variable,startTime,endTime)
Parameters described in tagtime.

DataValue

tagtimebad

Bad Quality Duration

Returns the duration with bad quality.

tagtimebad(variable,startTime,endTime)
Parameters described in tagtime.

DataValue

tagworstqual

Worst Quality

Returns the worst quality value.

tagworstqual(variable,startTime,endTime)
Parameters described in tagtime.

DataValue

tagtime

Value-Based Time Duration

Returns the time values match specified criteria.

tagtime(variable,startTime,endTime,comparisonType,comparisonValue,percentGood)
variable: Specifies the internal data variable to evaluate.
startTime: Specifies the beginning of the time range.
endTime: Specifies the end of the time range.
comparisonType: Specifies the comparison operator.
comparisonValue: Specifies the value to compare against.
percentGood: Specifies the required percentage of good samples.

DataValue

tagstddev

Standard Deviation (N−1)

Returns standard deviation using Bessel's correction.

tagstddev(variable,startTime,endTime)
Parameters described in tagtime.

DataValue

tagstddev2

Standard Deviation (N)

Returns standard deviation using N.

tagstddev2(variable,startTime,endTime)
Parameters described in tagtime.

DataValue

tagvariance

Variance (N−1)

Returns variance using Bessel's correction.

tagvariance(variable,startTime,endTime)
Parameters described in tagtime.

DataValue

tagvariance2

Variance (N)

Returns variance using N.

tagvariance2(variable,startTime,endTime)
Parameters described in tagtime.

DataValue

Total and Totalized Values

The tagtotal and tagtotalize functions both return a total for the specified time range, but they calculate it differently.

  • tagtotal returns the simple sum of every sample in the time range. It does not account for the time between samples.

  • tagtotalize returns a time-weighted total. It accounts for the duration that each sample value is in effect within the time range.

For example, if three samples in the time range have the values a, b, and c and are in effect for the durations x, y, and z respectively, the two functions calculate the following:

Function

Calculation

tagtotal

a + b + c

tagtotalize

((a × x) + (b × y) + (c × z)) / (x + y + z)