The first-appearing mode

mode_first() returns the mode that appears first in a vector, i.e., before any other modes.

Usage

mode_first(
  x,
  na.rm = FALSE,
  na.rm.amount = 0,
  na.rm.from = c("first", "last", "random"),
  accept = FALSE
)

Arguments

x

A vector to search for its first mode.

na.rm

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

na.rm.amount

Numeric. Alternative to na.rm that only removes a specified number of missing values. Default is 0.

na.rm.from

String. If na.rm.amount is used, from which position in x should missing values be removed? Options are "first", "last", and "random". Default is "first".

accept

Logical. Should the first-appearing value known to be a mode be accepted? If FALSE (the default), returns NA if a value that appears earlier might be another mode due to missing values.

Value

The first mode (most frequent value) in x. If it can't be determined because of missing values, returns NA instead.

Details

Unlike mode_all() and mode_single(), mode_first() has an na.rm.from argument. That is because it cares about the order of x values, whereas the other ones do not.

See also

• mode_all() for the full set of modes.

• mode_single() for the only mode, or NA if there are more.

Examples

# `2` is most frequent:
mode_first(c(1, 2, 2, 2, 3))
#> [1] 2

# Can't determine the first mode --
# it might be `1` or `2` depending
# on the true value behind `NA:
mode_first(c(1, 1, 2, 2, NA))
#> [1] NA

# Ignore `NA`s with `na.rm = TRUE`
# (there should be good reasons for this!):
mode_first(c(1, 1, 2, 2, NA), na.rm = TRUE)
#> [1] 1

# `1` is the most frequent value,
# no matter what `NA` stands for:
mode_first(c(1, 1, 1, 2, NA))
#> [1] 1

# By default, the function insists on
# the first mode, so it won't accept the
# first value *known* to be a mode if an
# earlier value might be a mode, too:
mode_first(c(1, 2, 2, NA))
#> [1] NA

# You may accept the first-known mode:
mode_first(c(1, 2, 2, NA), accept = TRUE)
#> [1] 2