twindow

语法

twindow(func, funcArgs, T, range, [prevailing=false], [excludedPeriod])

参数

• func 是一个聚合函数。

• funcArgs 是 func 的参数。func 有多个参数时，它是一个元组。

• T 是一个非严格递增的整型或时间类型的向量。

• range 是一个整型数据对或 DURATION 数据对，左右边界都包含在内。

• prevailing 是一个布尔值，默认值为 false。 prevailing = true时，滑动窗口左边界选取规则同 pwj。

• excludedPeriod 是一个支持 TIME、NANOTIME、MINUTE 和 SECOND 数据类型的时间对，可用于设定一天内的非交易时段。该参数的设置必须遵循以下原则：

  1. 起始时间和结束时间必须同属于相同一天，并且结束时间晚于起始时间：[startTime:endTime），其中 startTime < endTime。

  2. 参数 window 的值表达的时间长度小于 24 小时。

  3. 时间对的长度不大于（24 - window 值）。

  4. 参数 T 的值的数据类型必须是 TIMESTAMP、NANOTIMESTAMP、TIME、NANOTIME 中的任意一个。

  5. 时间数据对中的起始时间和结束时间不能与 T 存在任何重合。

详情

应用函数/运算符到给定对象的滑动窗口。对给定对象的每一个元素，滑动窗口由 T 和 range 决定。 结果的维度与 funcArgs 的维度相同（若 funcArgs 是一个元组，结果的维度与该元组中每个元素的维度相同）。

滑动窗口的确定规则（假设 range 参数为 d₁:d₂）：

1. range 是整型数据对时：

   • T 如果为整型向量，对 T 内元素 T_i，可以确定 T 对应的窗口范围为 [T_i+d₁, T_i+d₂]。

   • T 如果为时间类型向量，range 的精度默认为 T 的精度，对于 T 内元素 T_i，确定的窗口范围为 [temporalAdd(T_i, d₁, unit), temporalAdd(T_i, d₂, unit)]，其中 unit 是 T 的精度。

2. range 是 DURATION 数据对时，T 只能是时间类型向量，对于 T 内元素 T_i，确定 T 对应的窗口元素范围为 [temporalAdd(T_i, d₁), temporalAdd(T_i, d₂)]。

与 tmoving 函数相比，twindow 函数具有更灵活的窗口。tmoving 可以视为 twindow 指定 range 右边界为 0 的特殊情况， 但需要注意以时间长度衡量窗口时，两者对窗口边界的处理有区别：

1. twindow 窗口的右边界与多条相同的值匹配时，该窗口会包含所有重复匹配的记录。当其窗口左边界与多条相同的值匹配时， 若 prevailing = true，则窗口只包含最后一个值；若 prevailing = false，则窗口亦会包含所有重复值。

2. tmoving 函数的窗口范围为(T_i - window, T_i] 或 (temporalAdd(T_i - window), T_i]，即 tmoving 函数只基于当前滑动到的记录，确定一个向前的窗口， 不考虑右边界是否有重复值；且左边界不包含在内。

例子

prevailing = false，左边界对应多个重复值，计算窗口会包含所有重复值

t = 2021.01.02 2021.01.02 2021.01.06 2021.03.09 2021.03.10 2021.03.12 2021.03.12
x = -5 5 NULL -1 2 4 -8
twindow(func=min,funcArgs=x,T=t,range=0:2)

输出返回：[-5, -5, , -1, -8, -8, -8]

prevailing = true，左边界对应多个重复值，计算窗口只包含最后一个值

twindow(func=min, funcArgs=x, T=t, range=0:3, prevailing=true)

输出返回：[5, 5, ,-8, -8, -8, -8]

twindow(func=max, funcArgs=x, T=t, range=0d:3d)

输出返回：[5, 5, , 4, 4, 4, 4]

twindow(func=max, funcArgs=x, T=t, range=0:3, prevailing=true)

输出返回：[5, 5, , 4, 4, -8, -8]

twindow(func=max, funcArgs=x, T=t, range=0M:3M)

输出返回：[5, 5, 4, 4, 4, 4, 4]

twindow(func=max, funcArgs=x, T=t, range=0M:3M, prevailing=true)

输出返回：[5, 5, 4, 4, 4, -8, -8]

y = 4.8 9.6 7.1 3.3 5.9 2.7 6.9
twindow(func=corr, funcArgs=(x,y), T=t, range=0:3)

输出返回：[1, 1, , -0.685, -0.7893, -1, -1]

t1 = table(`A`A`B`B`C`C as sym, 09:56:03 09:56:07 09:56:02 09:56:05 09:56:04 09:56:06 as time, 10.6 10.7 20.6 11.6 11.7 19.6 as price)
select *, twindow(func=avg, funcArgs=t1.price, T=t1.time, range=2s:4s) from t1 context by sym

返回：

以下例子创建了一个包含时间（time）和价格（price）的表，并对价格在指定时间窗口内的总和（sum）进行计算。

t = 09:56:03.000 + (1..100) * 1000
p = (1..100)
itbl = table(t as time, p as price)
select time, price, twindow(sum, price, T=time, range=1s:3s, excludedPeriod=((09:56:09):(09:56:12))) from itbl where time >= 09:56:12 or time <= 09:56:09

1. 第一行代码创建了一个从 09:56:03.000 开始的时间序列 t。
2. 第二行代码创建了代表价格的 1 到 100 的整数序列。
3. 第三行代码通过 table 函数将前面两行的时间和价格分作两列合并为一个表 itbl。
4. 第四行代码对表 itbl 进行查询，选择不在 excludedPeriod 指定的时间区间内的记录，并对价格在指定时间窗口内的总和进行计算。

返回：