TagTot

Find the time-weighted (time integral) or event-weighted totalized value of an attribute's values over a specified time range, optionally converting the totalized value from its current unit of measure (UOM) to a specified UOM in same class. Time-weighted values are interpolated at time boundaries when possible and extrapolated otherwise.

Syntax

TagTot(attname, starttime, endtime [, toUnit, pctgood, calculationBasis])

Arguments

• attname

  attribute with time series data (such as PI point data reference) enclosed in single quotes

• starttime

  time expression representing the beginning of a time range enclosed in single quotes; can be a relative time (such as '-3h') in reference to an absolute endtime

• endtime

  time expression representing the end of a time range enclosed in single quotes; can be a relative time (such as '+1h') in reference to an absolute starttime

• toUnit

  Optional. The UOM to which the totalized value is converted. The specified UOM must be compatible with the UOM of the input attribute. Specifying an empty string ("") produces the same result as if no UOM were specified.

  pctgood

  Optional. Time-weighted or event-weighted minimum time percentage over a specified time range for which the attribute had good values

  calculationBasis

  Optional. A string indicating the type of calculation to be performed enclosed in double quotes. Choose between "TimeWeighted" or "EventWeighted". If omitted, the default is time-weighted.

Returns

The time-weighted (time integral) or event-weighted totalized value of an attribute's values over a specified time range. Time-weighted values are interpolated at time boundaries when possible and extrapolated otherwise.

Exceptions

• If the attribute has no good values or the pctgood minimum is not reached for the given time range, an error value is returned.

• If the specified UOM for conversion is incompatible with the UOM of the input attribute, an error value is returned. For example, if the UOM of the input attribute is gallons/minute, and the UOM for conversion is "m" (meters), then an error is returned.

Notes

• In case toUnit is not specified, the system chooses a scale factor such that the integral is correct only if the flow is expressed in units per day. If the flow is expressed in units per hour, or per some other time unit, you must multiply this result by a conversion factor. The conversion factor equals the number of actual flow time units in a day.

• For instance, if you totalize values measured in gallons per minute, multiply the result of TagTot by 1440 to get the answer in gallons. This conversion factor is not related to the time period you are totalizing over; it is strictly a function of the attribute's engineering units.

• Bad values are excluded from TagTot calculation.

• When the percentage of good data is less than 100%, TagTot determines the total based on good data and divides the fraction of good data in the interval. The time period during which the data is bad is ignored when calculating the total.

• In order to configure an optional parameter, any previous optional parameter must be specified.

  Note: If the attribute has very few good values during the time range, this function's result may not be trustworthy. Use the PctGood function to find out what percentage of the value is good.

Example

• TagTot('att1', 't', '+1h')

  [Return the time-weighted totalized value of 'att1' between 12:00 and 1:00am today.]

• TagTot('att1', 't', '+1h', "m")

  [Return the time-weighted totalized value of 'att1' calculated based on its unit between 12:00 and 1:00am today and convert to meters.]

• TagTot('att1', 't', '+1h', "", 80)

  [Return the time-weighted totalized value of 'att1' calculated based on its unit between 12:00 and 1:00am today when at least 80% of the values were good. Return error when minimum pctgood is not reached.]

• TagTot('att1', 't', '+1h', "", 80, "TimeWeighted")

  [Return the time-weighted totalized value of 'att1' calculated based on its unit between 12:00 and 1:00am today when at least 80% of the values were good. Return error when minimum pctgood is not reached.]

• TagTot('att1', 't', '+1h', "m", 80)

  [Return the time-weighted totalized value of 'att1' calculated based on its unit between 12:00 and 1:00am today and convert to meters when at least 80% of the values were good. Return error when minimum pctgood is not reached.]

• TagTot('att1', 't', '+1h', "m", 80, "EventWeighted")

  [Return the event-weighted totalized value of 'att1' calculated based on its unit between 12:00 and 1:00am today and convert to meters when at least 80% of the values were good. Return error when minimum pctgood is not reached.]