SiteWise Time-Weighted Averages: Keep Reporting Frequency from Biasing an Equipment Metric

An equipment value that reports more often during a high state can produce a high sample average even when the equipment spent most of the reporting window at a lower value. The question is which quantity the metric should represent: the average of received observations, or the average value over elapsed time.

AWS IoT SiteWise provides TimeWeightedAvg for the second calculation. Choosing it still requires an interpolation and coverage contract. The worked numbers below are original arithmetic for synthetic signals, not results queried from SiteWise or measured from equipment.

Define the window and its boundary evidence

Use a sixty-second window from t = 0 to t = 60. A known good numeric observation at t = -5 establishes a value of 10 before the window starts. Inside the window, reports arrive as follows:

t =  5 s: 10
t = 40 s: 30
t = 45 s: 30
t = 50 s: 30
t = 55 s: 30
t = 60 s: 30

All points in this exercise have GOOD quality. Assume the process holds its previous reported value until the next change. Thus the value is 10 for forty seconds and 30 for twenty seconds. The report at the closing boundary has no duration after it inside this window.

The arithmetic mean of the six listed in-window observations is (10 + 5 * 30) / 6 = 26.67, rounded to two decimal places. This calculation counts reports. The five high-valued reports do not mean the high state occupied five-sixths of the time.

Weight the held value by duration

The SiteWise temporal-functions reference documents locf, the default interpolation, as carrying a value forward until the next observation. For the stated piecewise-constant signal, the time-weighted calculation is:

area = 10 * 40 + 30 * 20 = 1000 value-seconds
window duration = 60 seconds
average = 1000 / 60 = 16.67

Adding another report of 30 at t = 58 does not change that area. It does change the observation count and hence the sample mean. This is the useful acceptance property for the exercise: redundant same-value reports should not give that state extra temporal influence.

Do not use arrival time when the requirement concerns equipment time. The arithmetic assumes the supplied timestamps describe the intended signal chronology. A gateway that stamps queued measurements on delivery changes the input problem before SiteWise evaluates the expression.

Choose linear interpolation only for a justified signal model

linear is the other documented TimeWeightedAvg interpolation option. It is appropriate only when the application accepts the estimated path between observations. A changing analog quantity and a held command value need not share that interpretation.

For a separate synthetic case, suppose the value rises linearly from 10 at t = 0 to 30 at t = 60, with both endpoints known and good. The trapezoid area is (10 + 30) / 2 * 60 = 1200, giving an average of 20. Treating the same endpoints as a held value until t = 60 instead gives 10 over the window.

Neither answer identifies the actual physical trajectory from two samples. The interpolation choice supplies the missing assumption. Document why that assumption fits the measurement rather than selecting whichever produces a preferred dashboard number.

Do not silently average only the covered portion

SiteWise’s documentation includes neighboring points outside a window in time-weighted calculations and describes recalculation when relevant points change. It also states that the default result requires good coverage throughout the window.

Remove the pre-window observation from the first exercise and suppose the first known point is at t = 5. The initial five seconds are unknown. Do not divide the remaining area by fifty-five seconds and label that the documented full-window result. Keep the missing interval visible; under the documented default, incomplete good coverage suppresses the window result.

A carried-forward value is also not a freshness guarantee. If the application needs a maximum permissible sample age, specify that requirement separately instead of assuming interpolation detects a failed sensor.

Prepare three discriminating checks

Use an isolated fixture to compare the irregular report list with an extra redundant high report; the time-weighted expectation remains 16.67. Then use the separate ramp to distinguish linear from held-value assumptions. Finally, remove the opening coverage and verify that an absent result is handled distinctly from numeric zero.

Record the window boundaries, every input timestamp and quality, interpolation choice, and any neighboring points used by the calculation. No SiteWise execution is claimed here. That evidence makes a later discrepancy diagnosable as reporting density, signal interpretation or missing coverage instead of treating every average as the same quantity.