twindow#

swordfish.function.twindow()#

Apply func over a sliding window of funcArgs. Each element in funcArgs corresponds to a window that is determined by T and range. The result has the same dimension as that of funcArgs (If funcArgs is a tuple, the result has the same dimension as that of each element in the tuple).

Suppose range is set to d1:d2, the windows are determined based on the following rules:

  • When range is an integral pair:

    • T is a vector of integral type: For element Ti in T, the window range is [Ti+d1, Ti+d2].

    • T is a vector of temporal type: range has the precision of T by default. For element Ti in T, the window range is [temporalAdd(Ti, d1, unit), temporalAdd(Ti, d2, unit)], where “unit” indicates the precision of T.

  • When range is a duration pair, T can only be a vector of temporal type. For element Ti in T, the window range is [temporalAdd(Ti, d1), temporalAdd(Ti, d2)].

When the window boundary matches multiple duplicates, the prevailing parameter determines whether those duplicates are included in the window.

  • If prevailing = 0/false, the window includes all duplicates.

  • If prevailing = 1/true, the calculation window includes the last record of duplicates at the left boundary and all duplicates at the right boundary.

  • If prevailing = 2,

    • When d1 is 0, the window starts at the current record, excluding prior duplicates while including all duplicates at the right boundary.

    • When d2 is 0, the window ends at the current record, excluding following duplicates while including duplicates at the left boundary.

    • Note that prevailing and excludedPeriod cannot be set simultaneously.

Compared with the tmoving function, twindow has more flexible windows. The tmoving function can be considered roughly as a special case of twindow, where the right boundary of the range parameter is 0 and prevailing is set to 0. However, when the window is measured by time, the range of the window is (Ti - window, Ti] or (temporalAdd(Ti, -window), Ti], where the left boundary is exclusive. The current record is included as the last element in the corresponding window, regardless of whether the following records have identical values.

Parameters:

  • func (Constant) – An aggregate function.

  • funcArgs (Constant) – The argument(s) of func. If func has multiple parameters, funcArgs is a tuple.

  • T (Constant) – A non-strictly increasing vector of integers or temporal type.

  • range (Constant) – A data pair of INT or DURATION type (both boundaries are inclusive).

  • prevailing (Constant, optional) – Can be 0/false (default), 1/true, or 2, indicating how duplicate values at window boundaries are handled, by default DFLT. The specific windowing rules for each value are introduced in Details.

  • excludedPeriod (Constant, optional) –

    A pair of time values (of TIME, NANOTIME, MINUTE, and SECOND type) representing the start and end time of the period which is excluded from the calculation, by default DFLT.

    When the excludedPeriod is set, the input T cannot contain the time range specified by excludedPeriod and must be of TIMESTAMP, NANOTIMESTAMP, TIME, and NANOTIME types. Note that excludedPeriod must be within a calendar day and cannot be longer than the value of (24 - range).

On this page