system.tag.queryTagDensity

This function is used in Python Scripting.

Description

Queries the Tag history system for information about the density of data. In other words, how much data is available for a given time span.

This function is called with a list of Tag paths, and a start and end date. The result set is a two column dataset specifying the timestamp, and a relative weight. Each row is valid from the given time until the next row. Tags are assigned a 1 or a 0 if they are present or not. All values are then multiplied together to get a decimal based percentage for the density. Thus, for four Tag paths passed in, if three Tags were present during the span, the result would be 0.75.

note

This function relies on being able to validate the data against tag group execution. This function will be unable to return density information for tags that were stored by an Internal Historian Provider, as well as cases where tag group validation is disabled (such as by disabling Enable State Data Detection).

Client Permission Restrictions

This scripting function has no Client Permission restrictions.

Syntax

system.tag.queryTagDensity(paths, startDate, endDate)

Parameters

Type	Parameter	Description
PySequence	paths	An array of tag paths (strings) to query.
Date	startDate	The start of the range to query.
Date	endDate	The end of the range to query.

Returns

Dataset - A two-column dataset consisting of a timestamp and a weight with a value between 0 and 1. Each row is valid until the next row.

Scope

Gateway, Vision Client, Perspective Session

Code Examples

Example #1 - Print Example

# Will grab the density of a Tag and print it out to the console.
density = system.tag.queryTagDensity(
    ['[default]myTag'],
    system.date.addHours(system.date.now(), -24),
    system.date.now())  
 
density = system.dataset.toPyDataSet(density)
for row in density:
    print row[0], row[1]

Example #2 - Density Readouts for Each Day

# Create a list of times going back in time at day increments.
# This forces density readouts at each day, even if two days had the same density.
now = system.date.now()
times = [system.date.addDays(now, -1), system.date.addDays(now, -2), system.date.addDays(now, -3), system.date.addDays(now, -4), system.date.addDays(now, -5), system.date.addDays(now, -6)]
 
# Create start and end date variables, as well as a variable that holds each history density.
startDate = now
endDate = now
list = []
 
# Loop through the list of times.
for time in times:
 
    # Set the new end date to whatever the start date was previously
    # and the new start date to the next time in the list.
    endDate = startDate
    startDate = time
     
    # Query Tag Density using a list of Tagpaths with the startDate and endDate values.
    density = system.tag.queryTagDensity(
    ['[default]tag1', '[default]tag2', '[default]tag3', '[default]tag4', '[default]tag5'],
    startDate, endDate)
     
    # Add each row of the returned dataset to a list of rows.
    density = system.dataset.toPyDataSet(density)
    for row in density:
        list.append([row[0], row[1]])
         
# Place the results in a table.
event.source.parent.getComponent('Table').data = system.dataset.toDataSet(['Times', 'Density Percentages'], list)

Example #3

# Create a list of times going back in time at day increments.
# This forces density readouts at each day, even if two days had the same density.
# This differs from the previous example in that it uses the new system.dataset.appendDataset function, which is only available in 7.9.7.
now = system.date.now()
times = [system.date.addDays(now, -1), system.date.addDays(now, -2), system.date.addDays(now, -3), system.date.addDays(now, -4), system.date.addDays(now, -5), system.date.addDays(now, -6)]
 
# Create start and end date variables.
startDate = now
endDate = now
 
# Loop through the list of times.
for time in times:
    # Set the new end date to whatever the start date was previously
    # and the new start date to the next time in the list.
    endDate = startDate
    startDate = time
     
    # Query Tag Density using a list of Tagpaths with the startDate and endDate values.
    density = system.tag.queryTagDensity(
    ['[default]EquipmentFour', '[default]Ramp/Ramp6', '[default]Ramp/Ramp7', '[default]Ramp/Ramp8', '[default]Ramp/Ramp9'],
    startDate, endDate)
    if endDate == now:
        densities = density
    else:
        densities = system.dataset.appendDataset(densities, density)
     
# Place the results in a table.
event.source.parent.getComponent('Table').data = densities