Rolling Method in Metrics
The ExpressionEngineFunction#rolling method takes in a time series and returns another time series. In the resulting time series every value can be the cumulative output after an aggregate function is applied to all the values in the input time series up to and including the current value. The cumulative value is carried over using a rolling value.
When using the Rolling method, the value begins rolling at the start of the EvalMetricsSpec, which might lead to incorrect or misleading results. See the Eval Method in Metrics topic for more information about using the Rolling method to establish start parameters.
Example
Consider a metric that calculates the cumulative energy consumption for a light bulb. The following sample data provided is the metric EnergyConsumption for a light bulb:
- At a quarter-hour granularity,
- From
"2018-01-01T00:00:00"until"2018-01-01T02:30:00"
[1, 2, 3, 5, 2, 1, 0, 2, 4, 1]
To calculate the cumulative energy consumption over the query period for the light bulb, define a metric CumulativeEnergyConsumption using SUM as the aggregate function, with the following expression:
rolling('SUM', EnergyConsumption)The rolling value is initialized to 0 before the first value of the time series.
Evaluating the CumulativeEnergyConsumption at the QUARTER_HOUR interval from "2018-01-01T00:00:00" until "2018-01-01T02:30:00" result in:
initial rolling value = 0, [1 + 0, 2 + 1, 3 + 2 + 1, 5 + 3 + 2 + 1, 2 + 5 + 3 + 2 + 1, 1 + 2 + 5 + 3 + 2 + 1, 0 + 1 + 2 + 5 + 3 + 2 + 1, 2 + 0 + 1 + 2 + 5 + 3 + 2 + 1, 4 + 2 + 0 + 1 + 2 + 5 + 3 + 2 + 1, 1 + 4 + 2 + 0 + 1 + 2 + 5 + 3 + 2 + 1] -> [1, 3, 6, 11, 13, 14, 14, 16, 20, 21]
Using reset
To reset the cumulative sum of EnergyConsumption every 4 points, use resetAfter and resetTo in this manner:
rolling('SUM', EnergyConsumption, null, 0, 4)Evaluating this new metric over same query period as the previous metric, can generate the result below:
initial rolling value = 0:
[0 + 1, 1 + 2, 3 + 3, 6 + 5, 0 + 2, 2 + 1, 3 + 0, 3 + 2, 0 + 4, 4 + 1] -> [1, 3, 6, 11, 2, 3, 3, 5, 4, 5]
To reset the cumulative sum of EnergyConsumption to 0 every time the light bulb turns off, that is, when the value for EnergyConsumption is 0, use resetOn and resetTo in this manner:
rolling('SUM', EnergyConsumption, 0, 0)Evaluating this new metric over same query period as the previous metric, results in:
initial rolling value = 0, resetOn = 0, and resetTo = 0:
[0 + 1, 1 + 2, 3 + 3, 6 + 5, 11 + 2, 13 + 1, 0 == resetOn: rolling value = resetTo, 0 + 2, 2 + 4, 6 + 1] -> [1, 3, 6, 11, 13, 14, 0, 2, 6, 7]