Modus

Aggregation functions modus

syntax

• modus(a)
• modus(a, relation)

definition

• modus(a) results in a parameter with the most occurring non null value of attribute a.
• modus(a, relation) results in an attribute with the most occurring non null value of attribute a, grouped by relation. The domain unit of the resulting attribute is the values unit of the relation.

description

An attribute might contain multiple most occurring non null values. In these cases, the modus function results in the lowest most occurring non null value, independent from the sequence of the values in the attribute, see also example 2.

Values of an integer value type that lie outside the range of the values unit of a are counted like any other value, and can be the result. Such values occur, for instance, where a switch gives a sentinel value beyond the last class in its last case: the result takes the values unit of the first case, whose range does not contain the sentinel. Since 20.22.0 this also holds for modus(a, relation) where the counts are kept in a table (see performance); before, that case left such values out, and counted them otherwise.

applies to

• attribute a with uint2, uint4, uint8, uint16, uint32 or bool value type
• relation with value type of the group CanBeDomainUnit

conditions

1. The values unit of the resulting data item should match with regard to value type and metric with the values unit of attribute a.
2. The domain of argument a and relation must match.

performance

• Values of an integer value type are counted in a table with a counter for each value in the range of the values unit of a, for each group with relation, when the table has no more counters than a has elements: O(n + v·p) time and O(v·p) memory, with n the number of elements of a, v the number of values in that range and p the number of groups (1 without relation). A values unit without a range of its own, such as uint8 or uint32 itself, has a counter for every non-null value of its value type. Values outside the range are counted apart, per distinct value. bool, uint2 and uint4 values are always counted in a table.
• Other values, and integer values whose table would be larger, are counted per distinct value in sorted order: O(n·log(n)) time at most, with memory in proportion to the number of distinct values.

example 1

parameter<uint32> modusLifeStyleCode                      := modus(City/LifeStyleCode); result = 1
attribute<uint32> modusLifeStyleCodeRegion (RegionDomain) := modus(City/LifeStyleCode, City/Region_rel);

City/LifeStyleCode	City/Region_rel
2	0
0	1
1	2
0	1
1	3
1	null
null	3

domain City, nr of rows = 7

modusLifeStyleCodeRegion
2
0
1
1
null

domain Region, nr of rows = 5

example 2

parameter<uint32> modusSeqA := modus(City/SeqA); result = 1
parameter<uint32> modusSeqB := modus(City/SeqB); result = 1
parameter<uint32> modusSeqC := modus(City/SeqC); result = 1
parameter<uint32> modusSeqD := modus(City/SeqD); result = 1

City/SeqA	City/SeqB	City/SeqC	City/SeqD
1	2	2	3
1	2	1	2
2	1	2	3
2	1	1	1
3	3	2	2
null	null	1	1
null	null	null	null

domain City, nr of rows = 7

The attributes SeqA, SeqB, SeqC and SeqD all contain multiple most occurring non null values, in different sequences. In all cases the modus function results in the lowest most occurring non null value: 1.

see also

• modus_weighted
• modus_count