FilteredSummaries Method (IPIData2 interface)

                     

This method, when supplied a filter expression that evaluates to true or false, evaluates it over the passed time range. For the time ranges where the expression evaluates to true, the method calculates the requested summaries on the source point.  The method returns a NamedValues collection containing the results.  The format of this returned collection is described under Remarks below. This method is currently not supported for PI2 servers.

Syntax

object.FilteredSummaries StartTime, EndTime, SummaryDuration, FilterExpression, SummaryType, CalculationBasis, SampleType, SampleInterval, asynchStatus

 

The FilteredSummaries method syntax has these parts:

Part Description
object An object expression that evaluates to a IPIData2 interface. This interface can be obtained from a PIData object.
StartTime A Variant containing the start time of the evaluation period. See the Settings section for allowable values. The StartTime, EndTime and SummaryDuration arguments together determine the number of calculation periods and the starting and ending times of each period. See the Remarks section for how the calculation periods are determined.
EndTime A Variant containing the end time of the evaluation period. See the Settings section for allowable values.
SummaryDuration A Variant containing the length of summary period. See the Settings section for allowable values and the Remarks section for usage.
FilterExpression

A string containing the expression to be evaluated.  The syntax for the expression follows the Performance Equation syntax as described in the server documentation.

SummaryType A value from the ArchiveSummariesTypeConstants enumeration specifying the kind(s) of summaries to calculate.  Note this argument is not a bit mask.  See the Settings section for allowable values.
CalculationBasis A value from the CalculationBasisConstants enumeration specifying the method of evaluating the event stream.  See the Settings section for allowable values. This argument is optional and the default value is cbTimeWeighted.
SampleType A value from the FilterSampleTypeConstants enumeration. See the Settings section for allowable values. Together with the SampleInterval argument, SampleType determines how often the expression is evaluated. See the Remarks section for usage. The default value for SampleType is fstPIPointRecordedValues.
SampleInterval A Variant containing the time interval at which the evaluation is performed within the specified time range.  See the Settings section for allowable values. If SampleType is specified as fstPIPointRecordedValues or fstExpRecordedValues , this argument is ignored. 
AsyncStatus A PIAsynchStatus object for launching an asynchronous call, determining the progress of, or canceling a lengthy call. [Optional]

Settings

The possible values in the variant for StartTime and EndTime are:

 

The possible values for CalculationDuration are:

 

The settings for SummaryType are:


 

The settings for CalculationBasis are:


 

The possible values for SampleType are:

Setting Description
fstPIPointRecordedValues Sampling / evaluation of the filter expression is done based on the archive events of the source tag where the summary calculation is performed. fstPIPointRecordedValues is the default SampleType setting for the FilterSummaries methods and it is supported on all versions of the PI server. The SampleInterval argument is ignored when fstPIPointRecordedvalues is selected for SampleType.
fstExpRecordedValues Sampling / evaluation is done based on the archive events of all tags used in the filter expression. The filter expression is evaluated at each of the timestamps of these retrieved events. The result of each evaluation is assumed to hold until the next evaluation, i.e. same as step attribute is true. This sampling algorithm is sometimes referred to as natural or event-based. The SampleInterval argument is ignored when fstExpRecordedvalues is selected for SampleType. fstExpRecordedvalues is only supported on PI server version 3.4 and above.
fstInterval Sampling / evaluation is done based on a passed interval (SampleInterval).  This is sometimes referred to as evenly-spaced evaluation. This option is only supported on PI server version 3.4 and above.
fstExpRecValWithMinSampTime This option is the same as fstExpRecordedValues with the additional requirement that the evaluation interval has to be less than or equal to the passed interval (SampleInterval). Therefore, the number of evaluations using this option will always be more or the same as the number of evaluations using the fstExpRecordedValues option or fstInterval option with the same SampleInterval. This option only supported on PI server version 3.4 and above.
fstAutoDetectChange With this option, the server tries to determine the times the expression result changes (true to false, false to true) to within the passed accuracy (SampleInterval) in the most efficient manner. First the expression is evaluated using the event-based algorithm (see fstExpRecordedValues discussion above), resulting in a time series of boolean events. Within this boolean events collection, whenever there is a boolean value change, the server further narrows down the interval until the interval is less than or equal to the passed SampleInterval. This option is currently NOT IMPLEMENTED.

 

The possible values for SampleInterval are:

 

 

Remarks

Usage Notes

AsCount is the only summary type that supports non-numeric tags (such as string tags or digital tags). Requesting for the any other summary types (including asAll) on non-numeric tags will result in an error of E_INVALIDARG.

The PI server computes time-weighted total by integrating the rate tag values over the requested time range. If some of the data are bad in the time range, the calculated total is divided by the fraction of the time period for which there are good values. Mathematically, this approach is equivalent to assuming that during the period of bad data, the tag takes on the average values for the entire calculation time range. It is important for the user of the data to check the percentGood attribute to determine if the calculation result is suitable for the application's purposes.

When the PI server performs the integration for the time-weighted total, it does not have knowledge of the time unit of the rate tag. Therefore, the server performs the time-weighted total using the same time unit for all the tags. The default time unit for all PI3 servers and most PI2 systems is "per day". If the measured time component of the rate tag is not based on a day, the user of the data has to convert the totalization result to the appropriate units. For example, if the rate tag has engineering units of "gallons/minute", the user needs to multiply the time-weighted total result by 1440 (minutes/day) to obtain the correct number of gallons for the period.

 

Specifying Calculation Intervals

Given the StartTime, EndTime and Duration, this function generates a number of contiguous calculation time periods where the computation results are returned according to the following rules:

1.  When the Duration argument is specified as a string, the way the calculation interval is determined depends on the server type and the interval type.

Against a PI2.x server, wall clock rules based on client machine time zone are used to determine the interval length for all interval types.

Against a PI3.x server, intervals specified in "seconds", "minutes" and "hours" are interpreted as evenly spaced UTC time intervals. The rest of the interval types are interpreted using wall clock rules. Wall clock rules are time zone dependent. If the StartTime and EndTime arguments are specified as PITimeFormat objects, the wall clock rules of the PITimeZoneInfo of the passed PITimeFormat object are used to determine the calculation intervals. Otherwise, wall clock rules based on the client machine time zone are used. For example, against a PI 3 server, Duration of "24h" means using an evenly spaced 24 UTC hour interval for each calculation. On the other hand, for a StartTime of April 1, 2003, EndTime of April 10, 2003 and Duration of "1d", the calculation will be performed for nine one calendar day periods, with the sixth period covering only 23 UTC hours because of Daylight Savings Time change. 

2.  When the specified StartTime is earlier than the EndTime, the resulting PIValues collection will be indexed in time ascending direction. If the StartTime is more recent than the EndTime, the resulting PIValues collection will be indexed in time descending direction. Using the example in rule 1, reversing the StartTime and EndTime, the result PIValues collection will be generated in descending time order, starting with April 9 period and ending with the April 1 period.

3.  When positive Duration is specified, the function starts at the earliest time (i.e. the smaller of the StartTime and the EndTime argument) and applies the Duration as interval length repeatedly in ascending time direction to generate the calculation periods. Therefore, if the StartTime is more recent than the EndTime, the function starts at the EndTime, otherwise, the function starts at the StartTime. The function stops at the closest interval to the latest time (i.e. the larger of the StartTime and the EndTime argument) but does not go beyond the it. 

4.  For negative Duration, the function starts at the latest time (i.e. the larger of the StartTime and the EndTime argument) and applies the Duration as interval length repeatedly in descending time direction to generate the calculation periods. Therefore, if the StartTime is more recent than the EndTime, the function starts at the StartTime, otherwise, the function starts at the EndTime. The function stops at the closest interval to the earliest time (i.e. the smaller of the StartTime and the EndTime argument) but does not go beyond the it. 

Note that the order of the PIValues still obeys rule 2 where the results index order reflects the start and end time specification.

Rules 2, 3 and 4 apply to Duration specified in string as well as numeric format. The determination of the calculation interval and results index order from the Start/End time and Duration specifications are demonstrated in the following table:

 

  Time Ascending Time Descending Time Ascending with negative Duration Time Descending with negative Duration
StartTime

Y

T

Y T
EndTime

T

Y

T Y
Duration

5h

5h

-5h -5h
Period for PIValues(1) 12a.m. to 5a.m. 3p.m. to 8p.m. 4a.m. to 9a.m. 7p.m. to 12p.m.
Period for PIvalues(2) 5a.m. to 10a.m. 10a.m. to 3p.m. 9a.m. to 2p.m. 2p.m. to 7p.m.
Period for PIvalues(3) 10a.m. to 3p.m. 5a.m. to 10a.m. 2p.m. to 7p.m. 9a.m. to 2p.m.
Period for last PIvalue 3p.m. to 8p.m. 12a.m. to 5a.m. 7p.m. to 12p.m. 4a.m. to 9a.m.

 

 

SampleType and SampleInterval Usage:

The FilterSummaries method first determine the time range where the filterExpression is evaluated to true. Then, summary calculation can be performed in these time ranges. The arguments SampleType and SampleInterval are used to determine the filter expression evaluation intervals as discussed in the table below. More frequent expression evaluations leads to more accurate result but increases server load. Therefore, care must be taken to avoid overloading the server by specifying too fine a calculation granularity.

 

FilterSampleTypeConstant Server Support Usage
fstPIPointRecordedValues All versions This is the default option for the filterSummaries method. When the summary source tag is not used in the filter expression, this option is not very accurate in determining the exact time when the filter expression change states. However, this option is supported on all versions of the PI server.
fstExpRecordedValues 3.4 and above This option is the most efficient in getting accurate result. Expressions using only digital tags will get exact answers with this option. However, for calculation covering a large time range, the server may have to evaluate the expression a large number of times if there are lots of data in the archive.
fstInterval 3.4 and above With this option, the server evaluates the expression at evenly spaced intervals (SampleInterval). This option may not be efficient in getting accurate result, i.e. evaluating expression at time stamp where data are not changing. But since user can specify the evaluation interval, user has better control of number of evaluation vs. desired accuracy. Hence, this option is ideal for getting a quick estimate for a large time period with limited expression evaluation.
fstExpRecValWithMinSampTime 3.4 and above This option allows the user to get more accurate answer than the fstExpRecordedValues option by evaluating the expression more frequently. Normally, this option is only necessary if the expression involves comparison of analog tag values.
fstAutoDetectChange Not supported on any Server now. This option allows the user to get more accurate answer than the fstExpRecordedValues option but is more efficient than the fstExpRecValWithMinSampTime option. The user can also specify the accuracy directly in the SampleInterval argument.

 

 

Calculation Result Format

The summaries methods can compute multiple summary results over multiple calculation periods. The summaries methods return the result as a NamedValues collection. Each requested summary type produce a corresponding NamedValue item in the NamedValues collection. The name property of the NamedValue item contains the string representing the summary type. The following table shows the string corresponding to each summary type. SummariesType like asAll or asTotalAndAvg will result in NamedValues collection with more than one item.

Summary Type Name in NamedValue item
Total Total
Minimum Minimum
Maximum Maximum
Range Range
Average Average
Standard Deviation StdDev
Population Standard Deviation PStdDev
Count Count

 

The value property of the NamedValue item contains a PIValues collection holding the result over multiple calculation periods for the corresponding summary type. Every calculation period has one corresponding PIValue object in the PIValues collection. The value field of the PIValue object holds the calculation result. The timestamp of each PIValue object is assigned to the start time of the calculation period. The start time of the calculation period is always the earliest time of the period even when the StartTime and the EndTime arguments are specified in reversed time order. If there is error in the calculation period, the value field of the PIValue object is set to VT_ERROR.

The ValueAttributes of each of the PIValue contains additional information about the calculation result in the period. The start time and the end time of the calculation period are stored as NamedValue item EarliestTime and MostRecentTime. If there is problem when the server computes the result, the PIValue.value will contain a variant with VT_ERROR type and the full error description is put into the NamedValue item of ErrDescription. The following table shows all the possible NamedValue items in the ValueAttributes of a summary calculation result PIValue:

Name Description Data Type Always Present
EarliestTime Start time of the calculation period PITime yes
MostRecentTime End time of the calculation period PITime yes
PercentGood Percent of data with good value during the calculation period. For timeweighted calculation, percentgood is based on time. For eventweighted, percentgood is based on event count. Double Precision Float yes except when the calculation result is VT_Error
TimeOfMaxVal Time of Maximum value in the period PITime only for type Maximum or range and no calculation error
TimeOfMinVal Time of Minimum value in the period PITime only for type Minimum or range

and no calculation error

ErrDescription Error message string String only when the calculation result is VT_Error

Trappable Errors

In addition to generic errors (such as Out of Memory), the following errors may occur:

Error Description
E_INVALIDARG Some of the function argument are not valid.
E_NOTIMPL This combination of the function arguments is not implemented at current PISDK version or not supported by this version of the PI Server.
PISDK_E_ERRCONVINPUT Problem converting input arguments to PI Server calling arguments.
E_ACCESSDENIED No read access to PI Server
PISDK_E_INVPEEXPR Invalid Expression Syntax
PISDK_E_PERUNTIMEERROR Expression evaluation runtime error
PISDK_E_DATENOTONLINE Archive not online for specified time range
PISDK_E_CALCFAILED Other calculation error from the PI Server
PISDK_E_ERRCONVOUTPUT Error converting PI Server result to PISDK result format

 

Enabling Operational Intelligence