forcats 0.3.0

  2018/02/21

  tidyverse, forcats

  Mara Averick

We are pleased to announce that forcats 0.3.0 is now on CRAN.

The forcats package provides a suite of useful tools that solve common problems with factors in R. This version includes updates that resolve several of the “most popular” GitHub issues (as measured by reactions), some of which are highlighted below. For a complete set of changes, please see the release notes.

You can install the latest version with:

install.packages("forcats")

Improvements to NA handling

Closing out one of the most up-voted issues in the tidyverse, as_factor() and fct_inorder() can accept NA levels.

fct_inorder() allows you to reorder factor levels by their first appearance. In this latest release, NAs are properly ignored.

# forcats 0.3.0
f <- factor(c("b", "b", NA, "a", "c", "c", "c", NA))
f
#> [1] b    b    <NA> a    c    c    c    <NA>
#> Levels: a b c
fct_inorder(f)
#> [1] b    b    <NA> a    c    c    c    <NA>
#> Levels: b a c

fct_lump() now correctly accounts for NA in input. lvls_revalue() preserves NA levels. Missing values, including NAs, can be given an explicit factor level using fct_explicit_na(), which ensures that missing values will appear in summaries and plots.

New features

Consistent with other tidyverse packages, all functions that take ... now use tidy dots. This means that you can use !!! to splice in a list of values, and trailing empty arguments are automatically removed. For example:

fa <- factor("a")
fb <- factor("b")
fab <- factor(c("a", "b"))

# You can pass a list of factors with !!!
fs <- list(fa, fb, fab)
fct_c(!!!fs)
#> [1] a b a b
#> Levels: a b

All other arguments to functions that take ... gain a . prefix in order to avoid unhelpful matching of named arguments.

fct_lump() has a new argument, w, for weighing value frequencies before lumping them together. This is useful if you have pre-summarised data.

API changes

We needed to make two backward incompatible changes in order to increase consistency across the tidyverse:

  • fct_c() now requires explicit splicing with !!! if you have a list of factors that you want to combine. See example, above.

  • fct_reorder() and fct_reorder2() have renamed fun to .fun to avoid spurious matching of named arguments.