system.tag.queryTagCalculations

This function is used in Python Scripting.

Description

Queries various calculations (aggregations) for a set of tags over a specified range. Returns a dataset with a row per tag, and a column per calculation.

This is useful when you wish to aggregate tag history collected over a period of time into a single value per aggregate. If you want multiple values aggregated to a single time slice (i.e., hourly aggregates for the same tag over an 8 hour period) consider using system.tag.queryTagHistory.

note

Make sure the deadband style is set to Discrete Mode if you do not want seed values included in the raw data returned.

Client Permission Restrictions

This scripting function has no Client Permission restrictions.

Syntax

note

This function accepts keyword arguments.

system.tag.queryTagCalculations(paths, calculations, [startDate], [endDate], [rangeHours], [rangeMinutes], [aliases], [includeBoundingValues], [validatesSCExec], [noInterpolation], [ignoreBadQuality])

Parameters

Type	Parameter	Description
List[String]	paths	An array of tag paths (strings) to query calculations for. The resulting dataset will have a row for each tag, and a column for each calculation.
List[String]	calculations	An array of calculations (aggregation functions) to execute for each tag. Valid values are: "Average" (time-weighted), "MinMax", "LastValue", "SimpleAverage", "Sum", "Minimum", "Maximum", "DurationOn", "DurationOff", "CountOn", "CountOff", "Count", "Range", "Variance", "StdDev", "PctGood", and "PctBad".
Date	startDate	The starting point for the calculation window. If omitted, and range is not used, 8 hours before the current time is used. [optional]
Date	endDate	The end of the calculation window. If omitted, and range is not used, uses the current time. [optional]
Integer	rangeHours	Allows you to specify the query range in hours, instead of using start and end date. Can be positive or negative, and can be used in conjunction with startDate or endDate. [optional]
Integer	rangeMinutes	Same as rangeHours, but in minutes. [optional]
List[String]	aliases	Aliases that will be used to override the tag path names in the result dataset. Must be 1-to-1 with the tag paths. If not specified, the tag paths themselves will be used. [optional]
Boolean	includeBoundingValues	A boolean flag indicating that the system should attempt to load values before and after the query bounds for the purpose of interpolation. The effect depends on the aggregates used. The default is true. For more information see Seeded Values. [optional]
Boolean	validatesSCExec	A boolean flag indicating whether or not data should be validated against the scan class execution records. If false, calculations may include data that is assumed to be good, even though the system may not have been running. Default is true. [optional]
Boolean	noInterpolation	A boolean flag indicating that the system should not attempt to interpolate values in situations where it normally would, such as for analog Tags. Default is false. [optional]
Boolean	ignoreBadQuality	A boolean flag indicating that bad quality values should not be used in the query process. If set, any value with a "bad" quality will be completely ignored in calculations. Default is false. [optional]

Returns

Dataset - A dataset representing the calculations over the specified range. A demonstration of the table appears below. There is a row per tag ID, and a column per requested calculation. Tag path is returned in the first column.

tagpath	calculation1	calculation2	calculationN
path1	value	value	value
path2	value	value	value
pathN	value	value	value

Scope

Gateway, Vision Client, Perspective Session

Code Examples

Example #1

system.tag.queryTagCalculations(paths=['Historical Tag'], calculations=['Average'], noInterpolation=False)

Example #2

# Build a list of String tag paths
paths = [
            "[default]Folder/Tag1",
            "[default]Folder/Tag2"
        ]
 
# Determine the calculation to use
calc = ["StdDev"]
 
# Define the date range
end = system.date.now()
start = system.date.parse("2019-07-30 4:00:00")
 
# Run the query, returning the results as an Ignition dataset
data = system.tag.queryTagCalculations(paths, calc, start, end)
 
# From here you would need to do something useful with the data variable. You could extract the values
#   and write them to a Tag, pass them to a dataset property on a component, or any number of other things.
print "The calculated value for the first tag is " + str(data.getValueAt(0,1))
print "The calculated value for the second tag is " + str(data.getValueAt(1,1))