forcats
Tools for Working with Categorical Variables (Factors)
Helpers for reordering factor levels (including moving specified levels to front, ordering by first appearance, reversing, and randomly shuffling), and tools for modifying factor levels (including collapsing rare levels into other, 'anonymising', and manually 'recoding').
Overview
R uses factors to handle categorical variables, variables that have a fixed and known set of possible values. Factors are also helpful for reordering character vectors to improve display. The goal of the forcats package is to provide a suite of tools that solve common problems with factors, including changing the order of levels or the values. Some examples include:
fct_reorder(): Reordering a factor by another variable.fct_infreq(): Reordering a factor by the frequency of values.fct_relevel(): Changing the order of a factor by hand.fct_lump(): Collapsing the least/most frequent values of a factor into "other".
You can learn more about each of these in vignette("forcats"). If you're new to factors, the best place to start is the chapter on factors in R for Data Science.
Installation
install.packages("tidyverse")
# Alternatively, install just forcats:
install.packages("forcats")
# Or the the development version from GitHub:
# install.packages("devtools")
devtools::install_github("tidyverse/forcats")
Getting started
forcats is part of the core tidyverse, so you can load it with library(tidyverse) or library(forcats).
library(forcats)library(dplyr)library(ggplot2)
starwars %>%filter(!is.na(species)) %>%count(species, sort = TRUE)#> # A tibble: 37 x 2#> species n#> <chr> <int>#> 1 Human 35#> 2 Droid 5#> 3 Gungan 3#> 4 Kaminoan 2#> 5 Mirialan 2#> 6 Twi'lek 2#> 7 Wookiee 2#> 8 Zabrak 2#> 9 Aleena 1#> 10 Besalisk 1#> # … with 27 more rows
starwars %>%filter(!is.na(species)) %>%mutate(species = fct_lump(species, n = 3)) %>%count(species)#> # A tibble: 4 x 2#> species n#> <fct> <int>#> 1 Droid 5#> 2 Gungan 3#> 3 Human 35#> 4 Other 39
ggplot(starwars, aes(x = eye_color)) +geom_bar() +coord_flip()
starwars %>%mutate(eye_color = fct_infreq(eye_color)) %>%ggplot(aes(x = eye_color)) +geom_bar() +coord_flip()
More resources
For a history of factors, I recommend stringsAsFactors: An unauthorized biography by Roger Peng and stringsAsFactors = <sigh> by Thomas Lumley. If you want to learn more about other approaches to working with factors and categorical data, I recommend Wrangling categorical data in R, by Amelia McNamara and Nicholas Horton.
Getting help
If you encounter a clear bug, please file a minimal reproducible example on github. For questions and other discussion, please use community.rstudio.com.
Code of Conduct
Please note that the 'forcats' project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.
News
forcats 0.4.0
New features
-
fct_collapse()gains agroup_otherargument to allow you to group all un-named levels into"Other". (#100, @AmeliaMN) -
fct_cross()creates a new factor containing the combined levels from two or more input factors, similar tobase::interaction(@tslumley, #136) -
fct_inseq()reorders labels in numeric order, if possible (#145, @kbodwin). -
fct_lump_min()preserves levels that appear at leastmintimes (can also be used with thewweighted argument) (@robinsones, #142). -
fct_match()performs validated matching, providing a safer alternative tof %in% c("x", "y")which silently returnsFALSEif"x"or"y"are not levels off(e.g. because of a typo) (#126, @jonocarroll). -
fct_relevel()can now level factors using a function that is passed the current levels (#117). -
as_factor()now has a numeric method. By default, orders factors in numeric order, unlike the other methods which default to order of appearance. (#145, @kbodwin)
Minor bug fixes and improvements
-
fct_count()gains a parameter to also compute the proportion (@zhiiiyang, #146). -
fct_lump()now does not change the label if no lumping occurs (@zhiiiyang, #130). -
fct_relabel()now accepts character input. -
fct_reorder()andfct_reorder2()no longer require that the summary function return a numeric vector of length 1; instead it can return any orderable vector of length 1 (#147). -
fct_reorder(),fct_reorder2()andas_factor()now use the ellipsis package to warn if you pass in named components to...(#174).
forcats 0.3.0
API changes
-
fct_c()now requires explicit splicing with!!!if you have a list of factors that you want to combine. This is consistent with an emerging standards for handling...throughout the tidyverse. -
fct_reorder()andfct_reorder2()have renamedfunto.funto avoid spurious matching of named arguments.
New features
-
All functions that take
...use "tidy" dots: this means that you use can!!!to splice in a list of values, and trailing empty arguments are automatically removed. Additionally, all other arguments gain a.prefix in order to avoid unhelpful matching of named arguments (#110). -
fct_lump()gainswargument (#70, @wilkox) to weight value frequencies before lumping them together (#68).
Improvements to NA handling
-
as_factor()andfct_inorder()accept NA levels (#98). -
fct_explicit_na()also replaces NAs encoded in levels. -
fct_lump()correctly acccounts forNAvalues in input (#41) -
lvls_revalue()preserves NA levels.
Minor improvements and bug fixes
-
Test coverage increased from 80% to 99%.
-
fct_drop()now preserves attributes (#83). -
fct_expand()andlvls_expand()now also take character vectors (#99). -
fct_relabel()now accepts objects coercible to functions byrlang::as_function(#91, @alistaire47)
forcats 0.2.0
New functions
-
as_factor()which works likeas.factor()but orders levels by appearance to avoid differences between locales (#39). -
fct_other()makes it easier to convert selected levels to "other" (#40) -
fct_relabel()allows programmatic relabeling of levels (#50, @krlmlr).
Minor improvements and bug fixes
-
fct_c()can take either a list of factors or individual factors (#42). -
fct_drop()gainsonlyargument to restrict which levels are dropped (#69) and no longer addsNAlevel if not present (#52). -
fct_recode()is now checks that each new value is of length 1 (#56). -
fct_relevel()gainsafterargument so you can also move levels to the end (or any other position you like) (#29). -
lvls_reorder(),fct_inorder(), andfct_infreq()gain anorderedargument, allowing you to override the existing "ordered" status (#54).
forcats 0.1.1
-
Minor fixes for R CMD check
-
Add package docs