Cumulative Moving TopN Functions (cumTopN functions)
DolphinDB provides cumTopN functions to perform calculations on the top N elements in a cumulative sliding window.
First Release 1.30.22/2.00.10
Introduction
A general template for cumTopN functions is:
$ 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 is a Boolean value indicating whether to sort S in ascending order. It is an optional parameter and the default value is true.
tiesMethod 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.
List of Functions
See also
cumTopN(X, S, top, [ascending=true], [tiesMethod]='latest')
cumsumTopN, cumavgTopN, cumstdTopN, cumstdpTopN, cumvarTopN, cumvarpTopN, cumskewTopN, cumkurtosisTopN
cumTopN( X, Y, S, top, [ascending=true], [tiesMethod='latest'])
Windowing Logic
After sorting X (or X, Y) based on S in a cumulative window, the function obtains the first top elements for calculation. It adopts stable sorting algorithms and the order is specified by ascending.
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)
[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)
[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)
[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)
[2,3,7,9,11,11,12]