Extracting summaries

Extracting a summary for a single time interval

The PI system allows multiple types of summaries to be calculated from data. To get the maximum value of a PIPoint in the last 14 days, you would use the PIPoint.summary method. This takes at least three arguments, start_time, end_time and summary_types, as shown in the following code:

import PIconnect as PI
from PIconnect.Data import SummaryType

with PI.PIServer() as server:
    points = server.search('*')[0]
    data = points.summary('*-14d', '*', SummaryType.MAXIMUM)
    print(data)

The returned data is a pandas.DataFrame with the timestamps as index and a column for each requested summary. The timestamp in this case is the datetime at which the maximum occurred. This is more obvious when requesting multiple summaries over the same time span:

import PIconnect as PI
from PIconnect.Data import SummaryType

with PI.PIServer() as server:
    points = server.search('*')[0]
    data = points.summary('*-14d', '*', SummaryType.MAXIMUM | SummaryType.MINIMUM)
    print(data)

Similarly, a AFAttribute also has a AFAttribute.summary method, that works in the same way:

import PIconnect as PI
from PIconnect.Data import SummaryType

with PI.AFDatabase() as database:
    key = next(iter(database.children))
    element = database.children[key]
    attribute = next(iter(element.attributes.values()))
    data = attribute.summary('*-14d', '*', SummaryType.MAXIMUM | SummaryType.MINIMUM)
    print(data)

Note

Attributes on root elements within the database might not have meaningful summaries. To get a better result take a look at Finding descendants in the hierarchy.

Summary timestamps

Since the minimum and maximum of a point never occur at the same timestamp, the DataFrame in the previous example will typically occur two row. It is possible to reduce that to a single timestamp, when the time at which the summary value occurs is of no value.

There are two possibilities for the timestamp, the beginning of the requested time interval, or the end of the interval. Which to return is specified using the time_type argument. To always return the beginning of the interval, you should use the TimestampCalculation.EARLIEST_TIME constant from Data:

import PIconnect as PI
from PIconnect.Data import SummaryType, TimestampCalculation

with PI.PIServer() as server:
    points = server.search('*')[0]
    data = points.summary(
        '*-14d',
        '*',
        SummaryType.MAXIMUM | SummaryType.MINIMUM,
        time_type=TimestampCalculation.EARLIEST_TIME
    )
    print(data)

Similarly, the TimestampCalculation.MOST_RECENT_TIME constant always returns the time at the end of the interval:

import PIconnect as PI
from PIconnect.Data import SummaryType, TimestampCalculation

with PI.PIServer() as server:
    points = server.search('*')[0]
    data = points.summary(
        '*-14d',
        '*',
        SummaryType.MAXIMUM | SummaryType.MINIMUM,
        time_type=TimestampCalculation.MOST_RECENT_TIME
    )
    print(data)

Event weighting

Summaries of multiple data points, or events, in time can be calculated in several ways. By default each event is weighted according to the period of time for which it is valid. This period depends on the type of data, whether it is stepped or continuous data.

To get an unweighted summary, in which every event has equal weight, the CalculationBasis.EVENT_WEIGHTED constant from the Data module should be used:

import PIconnect as PI
from PIconnect.Data import CalculationBasis, SummaryType

with PI.PIServer() as server:
    points = server.search('*')[0]
    data = points.summary(
        '*-14d',
        '*',
        SummaryType.MAXIMUM | SummaryType.MINIMUM,
        calculation_basis=CalculationBasis.EVENT_WEIGHTED
    )
    print(data)

Extracting summaries at regular time intervals

Besides extracting a single summary over an entire period of time, it is also possible to extract summaries at fixed intervals within a period of time. This is done using the PIPoint.summaries or AFAttribute.summaries methods. In addition to the singular summary() method, this takes an interval as an argument. The following code extracts the maximum value for each hour within the last 14 days:

import PIconnect as PI
from PIconnect.Data import SummaryType

with PI.PIServer() as server:
    points = server.search('*')[0]
    data = points.summaries('*-14d', '*', '1h', SummaryType.MAXIMUM)
    print(data)

Just as the summary() methods, the summaries() methods support both changing the Event weighting and Summary timestamps.