Package forcats. February 19, 2018

Transcription

1 Package orcats February 19, 2018 Title Tools or Working with Categorical Variables (Factors) Version Helpers or reordering actor levels (including moving speciied levels to ront, ordering by irst appearance, reversing, and randomly shuling), and tools or modiying actor levels (including collapsing rare levels into other, 'anonymising', and manually 'recoding'). License GPL-3 URL BugReports Depends R (>= 3.1) Imports magrittr, rlang, tibble Suggests covr, ggplot2, testthat Encoding UTF-8 LazyData true RoxygenNote NeedsCompilation no Author Hadley Wickham [aut, cre], RStudio [cph, nd] Maintainer Hadley Wickham <hadley@rstudio.com> Repository CRAN Date/Publication :43:26 UTC R topics documented: as_actor ct_anon ct_c ct_collapse ct_count ct_drop

2 2 as_actor ct_expand ct_explicit_na ct_inorder ct_lump ct_other ct_recode ct_relabel ct_relevel ct_reorder ct_rev ct_shit ct_shule ct_uniy ct_unique gss_cat lvls lvls_union Index 19 as_actor Convert input to a actor. Compared to base R, this unction creates levels in the order in which they appear, which will be the same on every platorm. (Base R sorts in the current locale which can vary rom place to place.) as_actor(x,...) ## S3 method or class 'actor' as_actor(x,...) ## S3 method or class 'character' as_actor(x,...) x Object to coerce to a actor.... Other arguments passed down to method. Details This is a generic unction.

3 ct_anon 3 x <- c("a", "z", "g") as_actor(x) as.actor(x) ct_anon Anonymise actor levels Replaces actor levels with arbitary numeric identiiers. Neither the values nor the order o the levels are preserved. ct_anon(, preix = "") preix A actor. A character preix to insert in ront o the random labels. gss_cat$relig %>% ct_count() gss_cat$relig %>% ct_anon() %>% ct_count() gss_cat$relig %>% ct_anon() %>% ct_count() gss_cat$relig %>% ct_anon("x") %>% ct_count() ct_c Concatenate actors, combining levels This is a useul way o patching together actors rom multiple sources that really should have the same levels but don t. ct_c(...)... Individual actors. Uses tidy dots, so you can splice in a list o actors with!!!.

4 4 ct_collapse a <- actor("a") b <- actor("b") ab <- actor(c("a", "b")) c(a, b, ab) ct_c(a, b, ab) # You can also pass a list o actors with!!! s <- list(a, b, ab) ct_c(!!!s) ct_collapse Collapse actor levels into manually deined groups Collapse actor levels into manually deined groups ct_collapse(.,...). A actor (or character vector).... A series o named character vectors. The levels in each vector will be replaced with the name. ct_count(gss_cat$partyid) partyid2 <- ct_collapse(gss_cat$partyid, missing = c("no answer", "Don't know"), other = "Other party", rep = c("strong republican", "Not str republican"), ind = c("ind,near rep", "Independent", "Ind,near dem"), dem = c("not str democrat", "Strong democrat") ) ct_count(partyid2)

5 ct_count 5 ct_count Count entries in a actor Count entries in a actor ct_count(, sort = FALSE) sort A actor (or character vector). I TRUE, sort the result so that the most common values loat to the top. Value A tibble with columns and n. <- actor(sample(letters)[rpois(1000, 10)]) table() ct_count() ct_count(, sort = TRUE) ct_drop Drop unused levels Compared to base::droplevels(), does not drop NA levels that have values. ct_drop(, only) only A actor (or character vector). A character vector restricting the set o levels to be dropped. I supplied, only levels that have no entries and appear in this vector will be removed.

6 6 ct_explicit_na <- actor(c("a", "b"), levels = c("a", "b", "c")) ct_drop() # Set only to restrict which levels to drop ct_drop(, only = "a") ct_drop(, only = "c") ct_expand Add additional levels to a actor Add additional levels to a actor ct_expand(,...) A actor (or character vector).... Additional levels to add to the actor. Levels that already exist will be silently ignored. <- actor(sample(letters[1:3], 20, replace = TRUE)) ct_expand(, "d", "e", "") ct_expand(, letters[1:6]) ct_explicit_na Make missing values explicit This gives missing value an explicit actor level, ensuring that they appear in summaries and on plots. ct_explicit_na(, na_level = "(Missing)")

7 ct_inorder 7 na_level A actor (or character vector). Level to use or missing values. 1 <- actor(c("a", "a", NA, NA, "a", "b", NA, "c", "a", "c", "b")) table(1) 2 <- ct_explicit_na(1) table(2) ct_inorder Reorder actors levels by irst appearance or requency Reorder actors levels by irst appearance or requency ct_inorder(, ordered = NA) ct_inreq(, ordered = NA) ordered A actor A logical which determines the "ordered" status o the output actor. NA preserves the existing status o the actor. <- actor(c("b", "b", "a", "c", "c", "c")) ct_inorder() ct_inreq() ct_inorder(, ordered = TRUE)

8 8 ct_lump ct_lump Lump together least/most common actor levels into "other" Lump together least/most common actor levels into "other" ct_lump(, n, prop, w = NULL, other_level = "Other", ties.method = c("min", "average", "irst", "last", "random", "max")) A actor (or character vector). n, prop I both n and prop are missing, ct_lump lumps together the least requent levels into "other", while ensuring that "other" is still the smallest level. It s particularly useul in conjunction with ct_inorder(). Positive n preserves the most common n values. Negative n preserves the least common -n values. It there are ties, you will get at least abs(n) values. Positive prop preserves values that appear at least prop o the time. Negative prop preserves values that appear at most -prop o the time. w See Also other_level ties.method An optional numeric vector giving weights or requency o each value (not level) in. Value o level used or "other" values. Always placed at end o levels. A character string speciying how ties are treated. See rank() or details. ct_other() to convert speciied levels to other. x <- actor(rep(letters[1:9], times = c(40, 10, 5, 27, 1, 1, 1, 1, 1))) x %>% table() x %>% ct_lump() %>% table() x %>% ct_lump() %>% ct_inorder() %>% table() x <- actor(letters[rpois(100, 5)]) x table(x) table(ct_lump(x)) # Use positive values to collapse the rarest ct_lump(x, n = 3) ct_lump(x, prop = 0.1)

9 ct_other 9 # Use negative values to collapse the most common ct_lump(x, n = -3) ct_lump(x, prop = -0.1) # Use weighted requencies w <- c(rep(2, 50), rep(1, 50)) ct_lump(x, n = 5, w = w) # Use ties.method to control how tied actors are collapsed ct_lump(x, n = 6) ct_lump(x, n = 6, ties.method = "max") ct_other Replace levels with "other" Replace levels with "other" ct_other(, keep, drop, other_level = "Other") keep, drop other_level A actor (or character vector). keep will preserve listed levels, replacing all others with other_level. drop will replace listed levels with other_level, keeping all others as they are. Value o level used or "other" values. Always placed at end o levels. See Also ct_lump() to automatically convert the rarest (or most common) levels to "other". x <- actor(rep(letters[1:9], times = c(40, 10, 5, 27, 1, 1, 1, 1, 1))) ct_other(x, keep = c("a", "B")) ct_other(x, drop = c("a", "B"))

10 10 ct_relabel ct_recode Change actor levels by hand Change actor levels by hand ct_recode(.,...). A actor (or character vector).... A sequence o named character vectors where the name gives the new level, and the value gives the old level. Levels not otherwise mentioned will be let as is. Levels can be removed by naming them NULL. Uses tidy dots. x <- actor(c("apple", "bear", "banana", "dear")) ct_recode(x, ruit = "apple", ruit = "banana") # I you make a mistake you'll get a warning ct_recode(x, ruit = "apple", ruit = "bananana") # I you name the level NULL it will be removed ct_recode(x, NULL = "apple", ruit = "banana") ct_relabel Automatically relabel actor levels, collapse as necessary Automatically relabel actor levels, collapse as necessary ct_relabel(.,.un,...). A actor..un A unction to be applied to each level. Must accept one character argument and return a character vector o the same length as its input. You can also use ~ to create as shorthand (in the style o purrr). ~ paste(., "x") is equivalent to unction(.) paste(., "x")... Additional arguments to un.

11 ct_relevel 11 gss_cat$partyid %>% ct_count() gss_cat$partyid %>% ct_relabel(~ gsub(",", ", ",.x)) %>% ct_count() convert_income <- unction(x) { regex <- "^(?:Lt )[$]([0-9]+).*$" is_range <- grepl(regex, x) num_income <- as.numeric(gsub(regex, "\\1", x[is_range])) num_income <- trunc(num_income / 5000) * 5000 x[is_range] <- paste0("gt $", num_income) x } ct_count(gss_cat$rincome) convert_income(levels(gss_cat$rincome)) rincome2 <- ct_relabel(gss_cat$rincome, convert_income) ct_count(rincome2) ct_relevel Reorder actor levels by hand This is a generalisaton o stats::relevel() that allows you to move any number o levels to any location. ct_relevel(.,..., ater = 0L). A actor (or character vector).... Character vector o levels. Any levels not mentioned will be let in existing order, ater the explicitly mentioned levels. Supports tidy dots. ater <- actor(c("a", "b", "c", "d")) ct_relevel() ct_relevel(, "c") ct_relevel(, "b", "a") # Move to the third position ct_relevel(, "a", ater = 2) # Relevel to the end ct_relevel(, "a", ater = In) Where should the new values be placed?

12 12 ct_reorder ct_relevel(, "a", ater = 3) # Using 'In' allows you to relevel to the end when the number # o levels is unknown or variable (e.g. vectorised operations) d <- orcats::gss_cat[, c("rincome", "denom")] lapply(d, levels) d2 <- lapply(d, ct_relevel, "Don't know", ater = In) lapply(d2, levels) # You'll get a warning i the levels don't exist ct_relevel(, "e") ct_reorder Reorder actor levels by sorting along another variable ct_reorder() is useul or 1d displays where the actor is mapped to position; ct_reorder2() or 2d displays where the actor is mapped to a non-position aesthetic. last2() is a helper or ct_reorder2(); it inds the last value o y when sorted by x. ct_reorder(.,.x,.un = median,...,.desc = FALSE) ct_reorder2(.,.x,.y,.un = last2,...,.desc = TRUE) last2(.x,.y). A actor (or character vector)..x,.y.un The levels o are reordered so that the values o.un(.x) (or ct_reorder()) and un(.x,.y) (or ct_reorder2()) are in ascending order. n summary unction. It should take one vector or ct_reorder, and two vectors or ct_reorder2.... Other arguments passed on to.un. A common argument is na.rm = TRUE..desc Order in descending order? Note the deault is dierent between ct_reorder and ct_reorder2, in order to match the deault ordering o actors in the legend.

13 ct_rev 13 boxplot(sepal.width ~ Species, data = iris) boxplot(sepal.width ~ ct_reorder(species, Sepal.Width), data = iris) boxplot(sepal.width ~ ct_reorder(species, Sepal.Width,.desc = TRUE), data = iris) chks <- subset(chickweight, as.integer(chick) < 10) chks <- transorm(chks, Chick = ct_shule(chick)) i (require("ggplot2")) { ggplot(chks, aes(time, weight, colour = Chick)) + geom_point() + geom_line() # Note that lines match order in legend ggplot(chks, aes(time, weight, colour = ct_reorder2(chick, Time, weight))) + geom_point() + geom_line() + labs(colour = "Chick") } ct_rev Reverse order o actor levels This is sometimes useul when plotting a actor. ct_rev() A actor (or character vector). <- actor(c("a", "b", "c")) ct_rev()

14 14 ct_shule ct_shit Shit actor levels to let or right, wrapping around at end This is useul when the levels o an ordered actor are actually cyclical, with dierent conventions on the starting point. ct_shit(, n = 1L) n A actor. Positive values shit to the let; negative values shit to the right. x <- actor( c("mon", "Tue", "Wed"), levels = c("sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"), ordered = TRUE ) x ct_shit(x) ct_shit(x, 2) ct_shit(x, -1) ct_shule Randomly permute actor levels Randomly permute actor levels ct_shule() A actor (or character vector). <- actor(c("a", "b", "c")) ct_shule() ct_shule()

15 ct_uniy 15 ct_uniy Uniy the levels in a list o actors Uniy the levels in a list o actors ct_uniy(s, levels = lvls_union(s)) s levels A list o actors Set o levels to apply to every actor. Deault to union o all actor levels s <- list(actor("a"), actor("b"), actor(c("a", "b"))) ct_uniy(s) ct_unique Unique values o a actor Unique values o a actor ct_unique() A actor. <- actor(letters[rpois(100, 10)]) unique() # in order o appearance ct_unique() # in order o levels

16 16 gss_cat gss_cat A sample o categorical variables rom the General Social survey A sample o categorical variables rom the General Social survey gss_cat Format year year o survey, age age. Maximum age truncated to 89. marital marital status race race rincome reported income partyid party ailiation relig religion denom denomination tvhours hours per day watching tv Source Downloaded rom gss_cat ct_count(gss_cat$relig) ct_count(ct_lump(gss_cat$relig))

17 lvls 17 lvls Low-level unctions or manipulating levels lvls_reorder leaves values as they are, but changes the order. lvls_revalue changes the values o existing levels; there must be one new level or each old level. lvls_expand expands the set o levels; the new levels must include the old levels. lvls_reorder(, idx, ordered = NA) lvls_revalue(, new_levels) lvls_expand(, new_levels) idx ordered new_levels A actor (or character vector). A integer index, with one integer or each existing level. A logical which determines the "ordered" status o the output actor. NA preserves the existing status o the actor. A character vector o new levels. Details These unctions are less helpul than the higher-level ct_ unctions, but are saer than the very lowlevel manipulation o levels directly, because they are more speciic, and hence can more careully check their arguments. <- actor(c("a", "b", "c")) lvls_reorder(, 3:1) lvls_revalue(, c("apple", "banana", "carrot")) lvls_expand(, c("a", "b", "c", "d"))

18 18 lvls_union lvls_union Find all levels in a list o actors Find all levels in a list o actors lvls_union(s) s A list o actors. s <- list(actor("a"), actor("b"), actor(c("a", "b"))) lvls_union(s)

19 Index Topic datasets gss_cat, 16 as_actor, 2 ct_anon, 3 ct_c, 3 ct_collapse, 4 ct_count, 5 ct_drop, 5 ct_expand, 6 ct_explicit_na, 6 ct_inreq (ct_inorder), 7 ct_inorder, 7, 8 ct_lump, 8 ct_lump(), 9 ct_other, 9 ct_other(), 8 ct_recode, 10 ct_relabel, 10 ct_relevel, 11 ct_reorder, 12 ct_reorder2 (ct_reorder), 12 ct_rev, 13 ct_shit, 14 ct_shule, 14 ct_uniy, 15 ct_unique, 15 gss_cat, 16 last2 (ct_reorder), 12 lvls, 17 lvls_expand (lvls), 17 lvls_reorder (lvls), 17 lvls_revalue (lvls), 17 lvls_union, 18 rank(), 8 stats::relevel(), 11 19