twavg

twavg(X, Y)

Calculates the time-weighted average of X based on time intervals in Y.

The formula is as follows:

If duplicate time points exist, records with the same time point are merged into a single record, and the arithmetic mean of those records replaces the corresponding X value. The time-weighted average is then calculated based on the merged time series. Records with null values in either X or Y are ignored.

The time interval between the current time point and the next one determines the weight of each X value. Therefore, values that persist for a longer duration have a greater impact on the final result.

The key difference between twavg and wavg lies in how weights are derived: wavg uses explicitly specified weights, whereas twavg automatically calculates weights from intervals between adjacent timestamps. twavg is suitable for time-series data with uneven sampling intervals, such as financial market data and IoT sensor readings, and helps prevent densely sampled periods from dominating the average.

Note: This function does not support MapReduce.

X is of numeric type. It can be a scalar, vector, matrix, table, dictionary, or tuple.

Y is of integral or temporal type. It can be a scalar, vector, matrix, table, dictionary, or tuple. The non-NULL values in Y must be sorted in ascending order.

DOUBLE type. Returns a scalar when the input is a scalar or vector; returns a vector when the input is a matrix, dictionary, or tuple; and returns a table when the input is a table. If the number of valid elements (non-null values) involved in the computation is less than 2, an empty value is returned.

Example 1: This example demonstrates how twavg works with different input forms.

x = 1 2 3 4 5
y = 2026.06.23T09:30:00.000 + 0 5 10 20 30 * 1000
twavg(x, y)
// output: 2.83

x = 1 2 NULL 4 5
y = 2026.06.23T09:30:00.000 + 0 5 10 20 30 * 1000
twavg(x, y)
// output: 2.5

X = matrix(25.10 25.15 25.08 25.20, 80.50 80.60 80.55 80.70)
// Two columns of timestamps (each column must be in ascending order).
Y = matrix(09:30:00.000 09:30:05.000 09:30:12.000 09:31:00.000, 09:30:00.000 09:30:08.000 09:30:20.000 09:31:00.000)
twavg(X, Y)
// output: [25.0898,80.5533]

// When the input parameter of twavg is a dictionary, it must be set to an ordered dictionary using the ordered parameter. During computation, dictionary keys are ignored, and twavg is applied directly to the values.
X = dict(`stockA`stockB, [25.10 25.15 25.08 25.20, 80.50 80.60 80.55 80.70], ordered=true)
Y = dict(`stockA`stockB, [09:30:00.000 09:30:05.000 09:30:12.000 09:31:00.000, 09:30:00.000 09:30:08.000 09:30:20.000 09:31:00.000], ordered=true)
twavg(X, Y)
// output: [,25.15,25.08,]

X = [25.10 25.15 25.08 25.20, 80.50 80.60 80.55 80.70]
Y = [09:30:00.000 09:30:05.000 09:30:12.000 09:31:00.000, 09:30:00.000 09:30:08.000 09:30:20.000 09:31:00.000]
twavg(X, Y)
// output: [,25.15,25.08,]

X = table(25.10 25.15 25.08 25.20 as price1, 80.50 80.60 80.55 80.70 as price2)
Y = table(09:30:00.000 09:30:05.000 09:30:12.000 09:31:00.000 as t1, 09:30:00.000 09:30:08.000 09:30:20.000 09:31:00.000 as t2)
twavg(X, Y)      // Column-wise paired computation: price1 is weighted by t1, and price2 is weighted by t2.

Example 2: This example calculates the TWAP (time-weighted average price) from a sequence of stock price changes. Each price is weighted by how long it persists, so prices that remain unchanged for longer periods have a greater impact on the final TWAP.

// Price changes of a stock after market open
tradeTime = 2026.06.23T09:30:00.000 2026.06.23T09:30:05.000 2026.06.23T09:30:12.000 2026.06.23T09:30:30.000 2026.06.23T09:31:00.000
price = 25.10 25.15 25.08 25.20 25.18

// Calculate the time-weighted average price within the time interval
twavg(price, tradeTime)
// output: 25.1498

Example 3: This example calculates the time-weighted average temperature from sensor readings sampled at uneven intervals. Compared with a simple arithmetic average, twavg weights each temperature reading by its duration and prevents densely sampled short periods from dominating the result.

// The temperature sensor readings are sampled at uneven intervals
sampleTime = 2026.06.23T08:00:00 2026.06.23T08:00:10 2026.06.23T08:05:00 2026.06.23T08:05:30 2026.06.23T08:10:00
temperature = 36.5 36.8 37.2 36.9 37.0

// Calculate the average temperature weighted by time intervals
twavg(temperature, sampleTime)
// output: 36.86

Related functions: wavg, rowTwavg