forcats v0.4.0


Monthly downloads



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').



CRAN status Travis build status Codecov test coverage


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.


# The easiest way to get forcats is to install the whole tidyverse:

# Alternatively, install just forcats:

# Or the the development version from GitHub:
# install.packages("devtools")

Getting started

forcats is part of the core tidyverse, so you can load it with library(tidyverse) or library(forcats).

starwars %>% 
  filter(! %>%
  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(! %>%
  mutate(species = fct_lump(species, n = 3)) %>%
#> # 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() + 

starwars %>%
  mutate(eye_color = fct_infreq(eye_color)) %>%
  ggplot(aes(x = eye_color)) + 
  geom_bar() + 

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

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.

Functions in forcats

Name Description
as_factor Convert input to a factor.
fct_anon Anonymise factor levels
fct_count Count entries in a factor
fct_other Replace levels with "other"
fct_recode Change factor levels by hand
fct_cross Combine levels from two or more factors to create a new factor
%>% Pipe operator
fct_drop Drop unused levels
fct_explicit_na Make missing values explicit
fct_expand Add additional levels to a factor
fct_shift Shift factor levels to left or right, wrapping around at end
fct_shuffle Randomly permute factor levels
fct_unify Unify the levels in a list of factors
fct_inorder Reorder factors levels by first appearance, frequency, or numeric order.
fct_unique Unique values of a factor
fct_reorder Reorder factor levels by sorting along another variable
fct_rev Reverse order of factor levels
lvls Low-level functions for manipulating levels
lvls_union Find all levels in a list of factors
fct_c Concatenate factors, combining levels
fct_lump Lump together least/most common factor levels into "other"
fct_match Test for presence of levels in a factor
forcats-package forcats: Tools for Working with Categorical Variables (Factors)
gss_cat A sample of categorical variables from the General Social survey
fct_collapse Collapse factor levels into manually defined groups
fct_relabel Automatically relabel factor levels, collapse as necessary
fct_relevel Reorder factor levels by hand
No Results!

Vignettes of forcats

No Results!

Last month downloads


License GPL-3
Encoding UTF-8
LazyData true
RoxygenNote 6.1.1
VignetteBuilder knitr
NeedsCompilation no
Packaged 2019-02-17 14:15:34 UTC; hadley
Repository CRAN
Date/Publication 2019-02-17 14:40:02 UTC

Include our badge in your README