mode_is_trivial {moder}

Is the mode trivial?

Description

mode_is_trivial() checks whether all values in a given vector are equally frequent. The mode is not too informative in such cases.

Usage

mode_is_trivial(x, na.rm = FALSE, max_unique = NULL)

Arguments

x

A vector to search for its modes.

na.rm

Boolean. Should missing values in x be removed before computation proceeds? Default is FALSE.

max_unique

Numeric or string. If the maximum number of unique values in x is known, set max_unique to that number. This rules out that NAs represent values beyond that number (see examples). Set it to "known" instead if no values beyond those already known can occur. Default is NULL, which assumes no maximum.

Details

The function returns TRUE whenever x has length < 3 because no value is more frequent than another one. Otherwise, it returns NA in these cases:

• Some x values are missing and all known values are equal. Thus, it is unknown whether there is a value with a different frequency.

• All known values are modes if the NAs "fill up" the non-modal values exactly, i.e., without any NAs remaining.

• Some NAs remain after "filling up" the non-modal values with NAs (so that they are hypothetically modes), and the number of remaining NAs is divisible by the number of unique known values.

• There are so many missing values that they might form mode-sized groups of values that are not among the known values, and the number of NAs is divisible by the modal frequency so that all (partly hypothetical) values might be equally frequent. You can limit the number of such hypothetical values by specifying max_unique. The function might then return FALSE instead of NA.

Value

Boolean (length 1).

Examples

# The mode is trivial if
# all values are equal...
mode_is_trivial(c(1, 1, 1))

# ...and even if all unique
# values are equally frequent:
mode_is_trivial(c(1, 1, 2, 2))

# It's also trivial if
# all values are different:
mode_is_trivial(c(1, 2, 3))

# Here, the mode is nontrivial
# because `1` is more frequent than `2`:
mode_is_trivial(c(1, 1, 2))

# Two of the `NA`s might be `8`s, and
# the other three might represent a value
# different from both `7` and `8`. Thus,
# it's possible that all three distinct
# values are equally frequent:
mode_is_trivial(c(7, 7, 7, 8, rep(NA, 5)))

# The same is not true if all values,
# even the missing ones, must represent
# one of the known values:
mode_is_trivial(c(7, 7, 7, 8, rep(NA, 5)), max_unique = "known")