Understanding Rollups and Statistics for Time Series Data

Overview

When you query historical data in Mango by Radix IoT, you rarely want every raw sample. A data point logging every 5 seconds produces 17,280 values per day. Rollups aggregate those raw samples into meaningful summaries – averages, totals, minimums, maximums – over fixed time periods. They are used throughout Mango in charts, watchlist tables, Excel reports, and REST API responses.

Two things about Mango’s rollups routinely catch people out, and both are covered in detail below:

• AVERAGE is time-weighted, not the arithmetic mean. A separate ARITHMETIC_MEAN rollup gives the unweighted sample mean. On irregularly sampled data the two differ, sometimes substantially.
• INTEGRAL integrates over seconds. A point in kW yields kW·seconds by default, not kWh, unless you configure the point’s integral unit.

Prerequisites

• Mango 4.x or 5.x
• At least one data point with logged history in the range you intend to query
• Permission to read the point, and access to charts, reports, or the REST API
• For energy work: knowing the point’s engineering unit and its configured integral unit

What Is a Rollup?

A rollup divides a time range into equal intervals (called rollup periods) and applies an aggregation function to each interval. For example, requesting a 1-hour AVERAGE rollup over 24 hours returns 24 values – one average per hour.

Raw samples:  |...........|...........|...........|
              0h          1h          2h          3h
Rollup:       [  avg=72.3 ]  [  avg=73.1 ]  [  avg=71.8 ]

Accurate statistics need to know the value in force when the period opened, so Mango carries a start value into each period: the point’s value as of the period boundary, which is usually the last sample logged before it. Several rollups below behave differently depending on whether that start value exists.

Numeric Rollups

These rollups apply to Numeric (analog) data points:

Non-Numeric Rollups

Binary, Multistate, and Alphanumeric data points support only the subset of rollups that make sense without arithmetic:

Rollups that require arithmetic – AVERAGE, ARITHMETIC_MEAN, SUM, DELTA, INTEGRAL, ACCUMULATOR, the minimum and maximum family – are numeric-only. Requesting one for a non-numeric point is not supported.

Statistics by Data Type

When you request detailed statistics (not a single rollup), Mango returns a statistics object that varies by data type:

Analog Statistics (Numeric Points)

State and Runtime Statistics (Binary, Multistate, and Alphanumeric Points)

All three non-numeric data types go through the same statistics path. There is no separate, reduced result shape for alphanumeric points – an alphanumeric point gets state-and-runtime statistics exactly as a binary or multistate point does, treating each distinct string as a state.

For a binary point tracking a pump, the data list shows how many milliseconds the pump was ON versus OFF, the proportion (e.g., 0.75 = 75% runtime), and starts — how many times it cycled on, which is what you want for short-cycling and maintenance-interval work. For an alphanumeric status point, the same structure tells you how long the device reported each distinct status string.

Using Rollups in Charts

When configuring charts in the Dashboard Designer or custom pages:

1. Select the data point(s) to display
2. Set the range in the Date range picker — the Quick dates presets cover the common
   windows, and Update date range applies it
3. Choose a Rollup (e.g., AVERAGE)
4. Set the period with Time period type and Time periods (e.g., MINUTES and 15) — the
   same pair the REST API takes as timePeriodType and timePeriods

Choosing the Right Rollup Period

Using Rollups in the REST API

Query rolled-up values using the point-values time-period endpoint. The rollup is part of
the path, not a query parameter:

# Get hourly averages for the past 24 hours
curl "http://localhost:8080/rest/latest/point-values/time-period/DP_TEMP_001/AVERAGE?from=2024-01-01T00:00:00Z&to=2024-01-02T00:00:00Z&timePeriodType=HOURS&timePeriods=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

[
  { "timestamp": 1704067200000, "value": 72.3 },
  { "timestamp": 1704070800000, "value": 73.1 },
  { "timestamp": 1704074400000, "value": 71.8 }
]

API Parameters for Rollups

Practical Examples

Example 1: Daily Energy Consumption

For a kW power meter, use the INTEGRAL rollup with a 1-day period. Before reading the result as kWh, configure the point’s integral unit as kWh – otherwise the aggregate is in kW·seconds and a day at a steady 1 kW returns 86,400 rather than 24.

Example 2: Peak Demand Detection

Use the MAXIMUM rollup with a 15-minute period to find the highest demand interval, which is how most utilities calculate demand charges.

Example 3: Equipment Runtime Report

For a binary pump-status point, query /rest/latest/point-values/statistics/{xids} to get the runtime proportion. A proportion of 0.82 means the pump ran 82% of the tracked runtime in the queried period.

Example 4: Data Quality Check

Use the COUNT rollup to verify how many samples were logged per hour. If your point polls every 10 seconds, you expect 360 samples per hour. Significantly fewer indicates data gaps.

Verification

Before trusting rolled-up figures in a report or dashboard:

• Confirm which average you are getting. Query an irregularly sampled point with both AVERAGE and ARITHMETIC_MEAN over the same period; if the numbers differ, the weighting is doing exactly what it should, and you need to decide which one your report means
• For any INTEGRAL, create a point held at a constant 1 kW for one hour and query it. An unconfigured integral unit returns 3600 (kW·s); with the integral unit set to kWh you should see 1
• Compare DELTA against the meter’s own start and end readings for the same window, and check that consumption spanning a period boundary is not lost
• Aggregate an alphanumeric point and confirm you receive state and runtime statistics, including count and changes
• Create a deliberate acquisition gap, then query raw and rolled-up data over it and confirm the rollup reports empty periods rather than manufacturing values
• Check COUNT against the expected sample count for the point’s logging configuration

Troubleshooting

Rollup returns null or no data

• The data point must have logged values in the requested time range
• Verify the point’s logging type is not set to “Do not log”
• Check that the time range parameters are in the correct ISO 8601 format

AVERAGE does not match a hand-calculated mean

• This is expected. AVERAGE is time-weighted: a value that persisted for 50 minutes counts ten times as much as one that persisted for 5
• Use ARITHMETIC_MEAN if you want each logged sample to count equally
• Irregular sampling amplifies the difference. Even interval logging makes the two converge

INTEGRAL values seem wrong

• Check the unit first. The default is source unit × seconds, not hours: a kW point returns kW·s, so an hour at 1 kW reads 3600
• Set a compatible integral unit on the point (kWh for a kW point) if you want the value rendered in energy units, and confirm whether the surface you are reading applies that conversion
• Ensure timestamps on the raw data are correct; gaps produce inaccurate integrals

DELTA returns negative values

• This is normal for meters that decrease or reset. Check for meter resets or rollover at 32-bit or 64-bit boundaries
• ACCUMULATOR is not the fix here: it returns the last value in the period (or the maximum when there is none), not a monotonically increasing total

Report has empty periods

• Rollups do not restore missing history. Check whether the point was logging, whether the data source was healthy, whether the requested range is correct, and whether purge has already removed the data
• Only once you know the samples exist should you reach for a rollup to summarise them

Chart shows flat lines instead of curves

• You may be using FIRST or LAST rollup, which returns a single value per period. Switch to AVERAGE for smoother trends
• Increase the number of rollup periods for more detail