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 Status

Overview

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 more historical context, I recommend stringsAsFactors: An unauthorized biography by Roger Peng, and stringsAsFactors = <sigh> by Thomas Lumley.) 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.

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 not part of the core tidyverse, so you need to load it explicitly:

library(tidyverse)
library(forcats)

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 col           expected actual
#>   3  -- value in level set    Jam
#> [1] Dec  Apr  <NA> Mar 
#> attr(,"problems")
#> # A tibble: 1 × 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.

News

forcats 0.2.0

New functions

  • as_factor() which works like as.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() gains only argument to restrict which levels are dropped (#69) and no longer adds NA level if not present (#52).

  • fct_recode() is now checks that each new value is of length 1 (#56).

  • fct_relevel() gains after argument so you can also move levels to the end (or any other position you like) (#29).

  • lvls_reorder(), fct_inorder(), and fct_infreq() gain an ordered argument, allowing you to override the existing "ordered" status (#54).

forcats 0.1.1

  • Minor fixes for R CMD check

  • Add package docs

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.