twavg

twavg(X, Y)

按时间长度加权计算 X 的平均值。

计算公式如下：

如果存在重复的时间点，则将相同时间点合并成一个点，并使用对应 X 值的算术平均值作为该时间点的取值，然后基于合并后的时间序列计算时间加权平均值。X 或 Y 为 NULL 的记录会被忽略，不参与计算。

每个 X 值的权重由当前时间点与下一个时间点之间的时间间隔决定，因此数值持续时间越长，对最终结果的影响越大。

twavg 与 wavg 的关键区别在于权重来源不同：wavg 使用显式给定的权重，而 twavg 根据相邻时间点的间隔自动计算权重。twavg 适用于金融行情、物联网传感器等采样间隔不均匀的时序数据场景，可避免高频采样区间对平均值产生过度影响。

注意：该函数不支持 MapReduce。

X 数值类型。支持标量、向量、矩阵、表、字典和元组。

Y 整型或时间类型。支持标量、向量、矩阵、表、字典和元组。Y 中非空值必须升序排列。

DOUBLE 类型。输入为标量或向量时返回标量；输入为矩阵、字典或元组时返回向量；输入为表时返回表。当参与计算的有效元素（非空值）个数小于 2 时，返回空值。

例1：展示 twavg 在不同输入形式下的计算方式。

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)
// 两列时间戳（每列必须升序）
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]

// 当 twavg 的输入参数为字典时，需通过 ordered 参数将其设置为有序字典。计算时会忽略字典 key，直接对 values 调用 twavg。
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)      // 逐列配对计算：price1 按 t1 加权，price2 按 t2 加权

输出返回：

例2：使用股票价格变动记录计算 TWAP（时间加权平均价格）。该示例中价格按其持续时间加权，某个价格维持时间越长，对最终 TWAP 的影响越大。

// 某只股票在上午开盘后的一组价格变动记录
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

// 计算该时间段内的时间加权平均价格
twavg(price, tradeTime)
// output: 25.1498

例3：使用采样间隔不均匀的温度传感器数据计算时间加权平均温度。相比直接求算术平均，twavg 会按每个温度读数持续的时间加权，避免短时间内的高频采样对结果产生过度影响。

// 设备温度传感器的采样时间不均匀
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

// 按时间长度加权计算平均温度，避免高频采样区间被过度代表
twavg(temperature, sampleTime)
// output: 36.86

相关函数：wavg、rowWavg、rowTwavg