forcats v0.3.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\_Badge Travis-CI Build
Status Coverage


R uses factors to handle categorical variables, variables that have a fixed and known set of possible values. Historically, factors were much easier to work with than character vectors, so many base R functions automatically convert character vectors to factors. (For historical context, I recommend stringsAsFactors: An unauthorized biography by Roger Peng, and stringsAsFactors = \ 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.) These days, making factors automatically is no longer so helpful, so packages in the tidyverse never create them automatically.

However, factors are still useful when you have true categorical data, and when you want to override the ordering of character vectors to improve display. The goal of the forcats package is to provide a suite of useful tools that solve common problems with factors. If you’re not familiar with strings, 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 now part of the core tidyverse, so you do not need to load it explicitly:


Factors are used to describe categorical variables with a fixed and known set of levels. You can create factors with the base factor() or readr::parse_factor():

x1 <- c("Dec", "Apr", "Jan", "Mar")
month_levels <- c(
  "Jan", "Feb", "Mar", "Apr", "May", "Jun", 
  "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"

factor(x1, month_levels)
#> [1] Dec Apr Jan Mar
#> Levels: Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec

parse_factor(x1, month_levels)
#> [1] Dec Apr Jan Mar
#> Levels: Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec

The advantage of parse_factor() is that it will generate a warning if values of x are not valid levels:

x2 <- c("Dec", "Apr", "Jam", "Mar")

factor(x2, month_levels)
#> [1] Dec  Apr  <NA> Mar 
#> Levels: Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec

parse_factor(x2, month_levels)
#> Warning: 1 parsing failure.
#> row # A tibble: 1 x 4 col     row   col expected           actual expected   <int> <int> <chr>              <chr>  actual 1     3    NA value in level set Jam
#> [1] Dec  Apr  <NA> Mar 
#> attr(,"problems")
#> # A tibble: 1 x 4
#>     row   col expected           actual
#>   <int> <int> <chr>              <chr> 
#> 1     3    NA value in level set Jam   
#> Levels: Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec

Once you have the factor, forcats provides helpers for solving common problems.

Functions in forcats

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

Last month downloads


License GPL-3
Encoding UTF-8
LazyData true
RoxygenNote 6.0.1
NeedsCompilation no
Packaged 2018-02-19 17:34:45 UTC; hadley
Repository CRAN
Date/Publication 2018-02-19 19:43:26 UTC

Include our badge in your README