Cumulative Moving TopN Functions (cumTopN functions)

DolphinDB provides cumulative moving topN (cumTopN) functions to perform calculations on the top N elements in a cumulative sliding window.

Introduction

Syntax templates for cumTopN functions:

cumTopN(X, S, top, [ascending=true], [tiesMethod]='latest')
cumTopN(X, Y, S, top, [ascending=true], [tiesMethod='latest'])

Parameters:

X (Y) is a numeric vector or matrix.

S is a numeric/temporal vector or matrix, based on which X are sorted. NULL values in S are ignored.

top is an integer, indicating the first top elements of X after sorted based on S.

ascending (optional) is a Boolean value indicating whether to sort S in ascending order. It is an optional parameter and the default value is true.

tiesMethod (optional) is a string that specifies how to select elements if there are more elements with the same value than spots available in the top N after sorting X within a sliding window. It can be:

  • 'oldest': select elements starting from the earliest entry into the window;

  • 'latest': select elements starting from the latest entry into the window;

  • 'all': select all elements.

Windowing Logic

The function stably sorts X (or X, Y) by S in the order specified by ascending, then obtains the first top elements for calculation in a cumulative window.

The following example illustrates the calculation rules:

X = [2, 1, 5, 3, 4, 3, 1, 9, 0, 5, 2, 3]
S = [5, 8, 1, 9, 7, 3, 1, NULL, 0, 8, 7, 7]

cumsumTopN(X, S, top=3)
// output
[2,3,8,8,11,10,9,9,6,6,6,6]

The following examples show the usage of parameter tiesMethod:

X = [2, 1, 4, 3, 4, 3, 1]
S = [5, 8, 1, 1, 1, 3, 1]
// For the last cumulative window, there are four elements of value 1
// As tiesMethod is not specified, the default 'latest' is used, meaning the latest 3 occurrences of 1 (corresponding to 3, 4, 1 of X) are selected
cumsumTopN(X, S, top=3)
// output
[2,3,7,9,11,11,8]

// As tiesMethod is set to 'oldest', the first 3 occurrences of 1 (corresponding to 4, 3, 4 of X) are selected
cumsumTopN(X, S, top=3, tiesMethod=`oldest)
// output
[2,3,7,9,11,11,11]

// As tiesMethod is set to 'all', all the occurrences of 1 (corresponding to 4, 3, 4, 1 of X) are selected
cumsumTopN(X, S, top=3, tiesMethod=`all)
// output
[2,3,7,9,11,11,12]