Statistics-Based and Granules-Based Series

In most cases, variable series are based on "raw" historical values of the series variable. These values are stored in the server database.

However, it's possible to build a chart those historical data points are based on a statistical channel or granules with pre-aggregated data.

To build such a chart, first ensure that a statistical channel or granules exists for the series variable. Once a statistical channel or granules have been created, there are two ways to build a chart:

  • Automatically Detect the statistics channel or granules by creating a matching entry in the Source Variables property of the chart.

  • Use the statistics reference within a series Expression

Automatic Detection

To automatically detect an existing statistics or granulation channel, set the Data Source Type of the chart to Variable and create a row in the Source Variables property of the chart with values that match the statistics channel.

For example, suppose a device with context path users.admin.devices.thermometer has a variable named temp and a statistics channel named statisticsChannel_temp with an Expression ({temp_val}-32)*5/9 for converting the temperature from Fahrenheit to Celsius, Type selected as Gauge, no Timestamp Expression, and Aggregation Types of Average, Minimum, and Maximum.

In order to automatically detect this existing statistics channel, the Source Variables property in the chart must have a row with the following values:

Field

Notes

Name

statisticsChannel_temp

Context

users.admin.devices.thermometer

Variable

temp

Use Aggregated Data

Either Statistics, Granulation, or Both

Expression

({tempValue}-32)*5/9

Custom Timestamp Expression

Left blank, because the statistics channel doesn’t have a Timestamp Expression

Type

Gauge

Aggregation

Average

With these parameters, Iotellect attempts to find a statistics channel or granules with exactly matching properties. An error will be raised if multiple matches are identified.

In the case that no exact matches are found, the system tries to find a statistics channel or granule with the same parameters but with a finer level of aggregation, for example by minute rather than by hour.

If no matching statistics channel or granule can be found, but the indicated variable (temp in this case) exists in the context (users.admin.devices.thermometer in this case), then the raw variable history is used.

Statistics Reference

The statistics reference has one of the following formats: {statistics/channel} or {statistics/channel("key")}.

Once statistics reference is used inside series Expression, the chart builder takes historical data from the channel named channel. This channel should be based on the series source variable.

If a key is specified, the statistical Dataset matching this key will be used as a source.

The following series parameters affect fetching statistical data:

Series expression may include only one statistics reference. Referring multiple channels not possible.

Referring to Other Fields from Statistics-Based Series Expression

Statistics-based series expression may also refer to other fields of the source variable. However, such references have some important nuances:

  • Statistical channel doesn't keep the original historical values of the variable. Therefore, any reference to the cells of source variable is resolved using the current value of this variable.

  • If real-time history is enabled for a statistics-based series, the chart builder will merge statistical channel's expression and series' expression to generate new expression for building real-time data points.

Was this page helpful?