dev/dplyr/dplyr_docs.R
In abresler/asbtools: Alex Bresler's random tools
library(tidyverse)
library(dplyr)
# across ------------------------------------------------------------------
#' Apply a function (or functions) across multiple columns
# Different ways to select the same set of columns
# See <https://tidyselect.r-lib.org/articles/syntax.html> for details
iris %>%
as_tibble() %>%
mutate(across(c(Sepal.Length, Sepal.Width), round))
iris %>%
as_tibble() %>%
mutate(across(c(1, 2), round))
iris %>%
as_tibble() %>%
mutate(across(1:Sepal.Width, round))
iris %>%
as_tibble() %>%
mutate(across(where(is.double) &
!c(Petal.Length, Petal.Width), round))
# A purrr-style formula
iris %>%
group_by(Species) %>%
summarise(across(starts_with("Sepal"), ~ mean(.x, na.rm = TRUE)))
# A named list of functions
iris %>%
group_by(Species) %>%
summarise(across(starts_with("Sepal"), list(mean = mean, sd = sd)))
# Use the .names argument to control the output names
iris %>%
group_by(Species) %>%
summarise(across(starts_with("Sepal"), mean, .names = "mean_{.col}"))
iris %>%
group_by(Species) %>%
summarise(across(starts_with("Sepal"), list(mean = mean, sd = sd), .names = "{.col}.{.fn}"))
# When the list is not named, .fn is replaced by the function's position
iris %>%
group_by(Species) %>%
summarise(across(starts_with("Sepal"), list(mean, sd), .names = "{.col}.fn{.fn}"))
# across() returns a data frame, which can be used as input of another function
df <- data.frame(
x1 = c(1, 2, NA),
x2 = c(4, NA, 6),
y = c("a", "b", "c")
)
df %>%
mutate(x_complete = complete.cases(across(starts_with("x"))))
df %>%
filter(complete.cases(across(starts_with("x"))))
gdf <-
tibble(g = c(1, 1, 2, 3), v1 = 10:13, v2 = 20:23) %>%
group_by(g)
set.seed(1)
# Outside: 1 normal variate
n <- rnorm(1)
gdf %>% mutate(across(v1:v2, ~ .x + n))
# Inside a verb: 3 normal variates (ngroup)
gdf %>% mutate(n = rnorm(1), across(v1:v2, ~ .x + n))
gdf %>% mutate(across(v1:v2, ~ .x + rnorm(1)))
# if_any() and if_all() ----------------------------------------------------
iris %>%
filter(if_any(ends_with("Width"), ~ . > 4)) |> as_tibble()
iris %>%
filter(if_all(ends_with("Width"), ~ . > 2)) |> as_tibble()
# count -------------------------------------------------------------------
# count() is a convenient way to get a sense of the distribution of
# values in a dataset
starwars %>% count(species)
starwars %>% count(species, sort = TRUE)
starwars %>% count(sex, gender, sort = TRUE)
starwars %>% count(birth_decade = round(birth_year, -1))
starwars$birth_year |> round(-1)
# use the `wt` argument to perform a weighted count. This is useful
# when the data has already been aggregated once
df <- tribble(~ name,
~ gender,
~ runs,
"Max",
"male",
10,
"Sandra",
"female",
1,
"Susan",
"female",
4)
# counts rows:
df %>% count(gender)
# counts runs:
df %>% count(gender, wt = runs)
# tally() is a lower-level function that assumes you've done the grouping
starwars %>% tally()
starwars %>% group_by(species) %>% tally()
# both count() and tally() have add_ variants that work like
# mutate() instead of summarise
df %>% add_count(gender, wt = runs)
df |> count(name, gender, wt = runs)
df %>% add_tally(wt = runs)
# between -----------------------------------------------------------------
#' Do values in a numeric vector fall in specified range?
#' Description
#' This is a shortcut for x >= left & x <= right, implemented efficiently in C++ for local values, and translated to the appropriate SQL for remote tables.
between(1:12, 7, 9)
x <- rnorm(1e2)
x[between(x, -1, 1)]
## Or on a tibble using filter
filter(starwars, between(height, 100, 150))
var <- "height"
filter(starwars, between(!!!syms(var), 100, 150))
# bind --------------------------------------------------------------------
#' Efficiently bind multiple data frames by row and column
#' This is an efficient implementation of the common pattern of do.call(rbind, dfs) or do.call(cbind, dfs) for binding many data frames into one.
one <- starwars[1:4,]
two <- starwars[9:12,]
one
two
# You can supply data frames as arguments:
bind_rows(one, two)
# The contents of lists are spliced automatically:
bind_rows(list(one, two))
bind_rows(split(starwars, starwars$homeworld))
bind_rows(list(one, two), list(two, one))
# In addition to data frames, you can supply vectors. In the rows
# direction, the vectors represent rows and should have inner
# names:
bind_rows(c(a = 1, b = 2),
c(a = 3, b = 4))
# You can mix vectors and data frames:
bind_rows(c(a = 1, b = 2),
tibble(a = 3:4, b = 5:6),
c(a = 7, b = 8))
# When you supply a column name with the `.id` argument, a new
# column is created to link each row to its original data frame
bind_rows(list(one, two), .id = "id")
bind_rows(list(a = one, b = two), .id = "id")
bind_rows("group 1" = one,
"group 2" = two,
.id = "groups")
# Columns don't need to match when row-binding
bind_rows(tibble(x = 1:3), tibble(y = 1:4))
# Row sizes must be compatible when column-binding
try(bind_cols(tibble(x = 1:3), tibble(y = 1:2)))
# Even with 0 columns
try(bind_cols(tibble(x = 1:3), tibble()))
bind_cols(one, two)
bind_cols(list(one, two))
# case_when ---------------------------------------------------------------
#' A general vectorised if
x <- 1:50
case_when(x %% 35 == 0 ~ "fizz buzz",
x %% 5 == 0 ~ "fizz",
x %% 7 == 0 ~ "buzz",
TRUE ~ as.character(x))
# Like an if statement, the arguments are evaluated in order, so you must
# proceed from the most specific to the most general. This won't work:
case_when(TRUE ~ as.character(x),
x %% 5 == 0 ~ "fizz",
x %% 7 == 0 ~ "buzz",
x %% 35 == 0 ~ "fizz buzz")
# If none of the cases match, NA is used:
case_when(x %% 5 == 0 ~ "fizz",
x %% 7 == 0 ~ "buzz",
x %% 35 == 0 ~ "fizz buzz")
# Note that NA values in the vector x do not get special treatment. If you want
# to explicitly handle NA values you can use the `is.na` function:
x[2:4] <- NA_real_
case_when(
x %% 35 == 0 ~ "fizz buzz",
x %% 5 == 0 ~ "fizz",
x %% 7 == 0 ~ "buzz",
is.na(x) ~ "nope",
TRUE ~ as.character(x)
)
# All RHS values need to be of the same type. Inconsistent types will throw an error.
# This applies also to NA values used in RHS: NA is logical, use
# typed values like NA_real_, NA_complex, NA_character_, NA_integer_ as appropriate.
case_when(x %% 35 == 0 ~ NA_character_,
x %% 5 == 0 ~ "fizz",
x %% 7 == 0 ~ "buzz",
TRUE ~ as.character(x))
case_when(x %% 35 == 0 ~ 35,
x %% 5 == 0 ~ 5,
x %% 7 == 0 ~ 7,
TRUE ~ NA_real_)
# case_when() evaluates all RHS expressions, and then constructs its
# result by extracting the selected (via the LHS expressions) parts.
# In particular NaNs are produced in this case:
y <- seq(-2, 2, by = .5)
case_when(y >= 0 ~ sqrt(y),
TRUE ~ y)
# This throws an error as NA is logical not numeric
try(case_when(x %% 35 == 0 ~ 35,
x %% 5 == 0 ~ 5,
x %% 7 == 0 ~ 7,
TRUE ~ NA))
# case_when is particularly useful inside mutate when you want to
# create a new variable that relies on a complex combination of existing
# variables
starwars %>%
select(name:mass, gender, species) %>%
mutate(type = case_when(
height > 200 | mass > 200 ~ "large",
species == "Droid" ~ "robot",
TRUE ~ "other"
))
# `case_when()` is not a tidy eval function. If you'd like to reuse
# the same patterns, extract the `case_when()` call in a normal
# function:
case_character_type <- function(height, mass, species) {
case_when(height > 200 | mass > 200 ~ "large",
species == "Droid" ~ "robot",
TRUE ~ "other")
}
case_character_type(150, 250, "Droid")
case_character_type(150, 150, "Droid")
# Such functions can be used inside `mutate()` as well:
starwars %>%
mutate(type = case_character_type(height, mass, species)) %>%
pull(type)
# coalsece ----------------------------------------------------------------
# Use a single value to replace all missing values
x <- sample(c(1:5, NA, NA, NA))
coalesce(x, 0L)
# Or match together a complete vector from missing pieces
y <- c(1, 2, NA, NA, 5)
z <- c(NA, NA, 3, 4, 5)
coalesce(y, z)
# Supply lists by with dynamic dots
vecs <- list(c(1, 2, NA, NA, 5),
c(NA, NA, 3, 4, 5))
coalesce(!!!vecs)
# compute -----------------------------------------------------------------
#' Force computation of a database
#'
mtcars2 <- dbplyr::src_memdb() %>%
copy_to(mtcars, name = "mtcars2-cc", overwrite = TRUE)
remote <- mtcars2 %>%
filter(cyl == 8) %>%
select(mpg:drat)
# Compute query and save in remote table
compute(remote)
# Compute query bring back to this session
collect(remote)
# Creates a fresh query based on the generated SQL
collapse(remote)
# context -----------------------------------------------------------------
#' Context dependent expressions
df <- tibble(
g = sample(rep(letters[1:3], 1:3)),
x = runif(6),
y = runif(6)
)
df
gf <- df %>% group_by(g)
gf %>% summarise(n = n())
gf %>% mutate(id = cur_group_id())
gf %>% summarise(row = cur_group_rows())
gf %>% summarise(data = list(cur_group()))
gf %>% summarise(data = list(cur_data()))
gf %>% summarise(data = list(cur_data_all()))
gf %>% mutate(across(everything(), ~ paste(cur_column(), round(.x, 2))))
# cum_ --------------------------------------------------------------------
#' Cumulativate versions of any, all, and mean
x <- c(1, 3, 5, 2, 2)
cummean(x)
cumsum(x) / seq_along(x)
# `cumall()` and `cumany()` return logicals
cumall(x < 5)
cumany(x == 3)
# `cumall()` vs. `cumany()`
df <- data.frame(date = as.Date("2020-01-01") + 0:6,
balance = c(100, 50, 25, -25, -50, 30, 120))
# all rows after first overdraft
df %>% filter(cumany(balance < 0))
# all rows until first overdraft
df %>% filter(cumall(!(balance < 0)))
# c_aross -----------------------------------------------------------------
#' Combine values from multiple columns
df <- tibble(id = 1:4, w = runif(4), x = runif(4), y = runif(4), z = runif(4))
df
df %>%
rowwise() %>%
mutate(sum = sum(c_across(w:z)),
sd = sd(c_across(w:z)))
# rank --------------------------------------------------------------------
#' Six variations on ranking functions, mimicking the ranking functions described in SQL2003. They are currently implemented using the built in rank function, and are provided mainly as a convenience when converting between R and SQL. All ranking functions map smallest inputs to smallest outputs. Use desc() to reverse the direction.
x <- c(5, 1, 3, 2, 2, NA)
row_number(x)
min_rank(x)
dense_rank(x)
percent_rank(x)
cume_dist(x)
ntile(x, 2)
ntile(1:8, 3)
# row_number can be used with single table verbs without specifying x
# (for data frames and databases that support windowing)
mutate(mtcars, row_number() == 1L)
mtcars %>% filter(between(row_number(), 1, 10))
# explain -----------------------------------------------------------------
#' Explain details of a tbl
lahman_s <- dbplyr::lahman_sqlite()
batting <- tbl(lahman_s, "Batting")
batting %>% show_query()
batting %>% explain()
# The batting database has indices on all ID variables:
# SQLite automatically picks the most restrictive index
batting %>% filter(lgID == "NL" & yearID == 2000L) %>% explain()
# OR's will use multiple indexes
batting %>% filter(lgID == "NL" | yearID == 2000) %>% explain()
batting %>% filter(lgID == "NL" | yearID == 2000) |> collect() |> View()
batting %>% filter(lgID == "NL" | yearID == 2000) |> compute()
# Joins will use indexes in both tables
teams <- tbl(lahman_s, "Teams")
batting %>% left_join(teams, c("yearID", "teamID")) %>% explain()
batting %>% left_join(teams, c("yearID", "teamID")) |> collect()
# filter ------------------------------------------------------------------
# Filtering by one criterion
filter(starwars, species == "Human")
filter(starwars, mass > 1000)
# Filtering by multiple criteria within a single logical expression
filter(starwars, hair_color == "none" & eye_color == "black")
filter(starwars, hair_color == "none" | eye_color == "black")
# When multiple expressions are used, they are combined using &
filter(starwars, hair_color == "none", eye_color == "black")
# The filtering operation may yield different results on grouped
# tibbles because the expressions are computed within groups.
#
# The following filters rows where `mass` is greater than the
# global average:
starwars %>% filter(mass > mean(mass, na.rm = TRUE))
# Whereas this keeps rows with `mass` greater than the gender
# average:
starwars %>% group_by(gender) %>% filter(mass > mean(mass, na.rm = TRUE))
# To refer to column names that are stored as strings, use the `.data` pronoun:
vars <- c("mass", "height")
cond <- c(80, 150)
starwars %>%
filter(
.data[[vars[[1]]]] > cond[[1]],
.data[[vars[[2]]]] > cond[[2]]
)
# nth ------------------------------------------------------------
#' Extract the first, last or nth value from a vector
x <- 1:10
y <- 10:1
first(x)
last(y)
nth(x, 1)
nth(x, 5)
nth(x, -2)
nth(x, 11)
last(x)
# Second argument provides optional ordering
last(x, y)
# These functions always return a single value
first(integer())
# glimpse -----------------------------------------------------------------
glimpse(mtcars)
# Note that original x is (invisibly) returned, allowing `glimpse()` to be
# used within a pipeline.
mtcars %>%
glimpse() %>%
select(1:3)
glimpse(starwars)
# group_by ----------------------------------------------------------------
by_cyl <- mtcars %>% group_by(cyl)
# grouping doesn't change how the data looks (apart from listing
# how it's grouped):
by_cyl
# It changes how it acts with the other dplyr verbs:
by_cyl %>% summarise(
disp = mean(disp),
hp = mean(hp)
)
by_cyl %>% filter(disp == max(disp))
# Each call to summarise() removes a layer of grouping
by_vs_am <- mtcars %>% group_by(vs, am)
by_vs <- by_vs_am %>% summarise(n = n())
by_vs
by_vs %>% summarise(n = sum(n))
# To removing grouping, use ungroup
by_vs %>%
ungroup() %>%
summarise(n = sum(n))
# By default, group_by() overrides existing grouping
by_cyl %>%
group_by(vs, am) %>%
group_vars()
# Use add = TRUE to instead append
by_cyl %>%
group_by(vs, am, .add = TRUE) %>%
group_vars()
# You can group by expressions: this is a short-hand
# for a mutate() followed by a group_by()
mtcars %>%
group_by(vsam = vs + am)
# The implicit mutate() step is always performed on the
# ungrouped data. Here we get 3 groups:
mtcars %>%
group_by(vs) %>%
group_by(hp_cut = cut(hp, 3))
# If you want it to be performed by groups,
# you have to use an explicit mutate() call.
# Here we get 3 groups per value of vs
mtcars %>%
group_by(vs) %>%
mutate(hp_cut = cut(hp, 3)) %>%
group_by(hp_cut)
# when factors are involved and .drop = FALSE, groups can be empty
tbl <- tibble(
x = 1:10,
y = factor(rep(c("a", "c"), each = 5), levels = c("a", "b", "c"))
)
tbl %>%
group_by(y, .drop = FALSE) %>%
group_rows()
# group_cols --------------------------------------------------------------
gdf <- iris %>% group_by(Species)
gdf %>% select(group_cols())
# Remove the grouping variables from mutate selections:
gdf %>% mutate_at(vars(-group_cols()), `/`, 100)
# -> No longer necessary with across()
gdf %>% mutate(across(everything(), ~ . / 100))
# Apply a function to each group ------------------------------------------
# return a list
mtcars %>%
group_by(cyl) %>%
group_map(~ head(.x, 2L))
# return a tibble grouped by `cyl` with 2 rows per group
# the grouping data is recalculated
mtcars %>%
group_by(cyl) %>%
group_modify(~ head(.x, 2L))
# a list of tibbles
iris %>%
group_by(Species) %>%
group_map(~ broom::tidy(lm(Petal.Length ~ Sepal.Length, data = .x)))
# a restructured grouped tibble
iris %>%
group_by(Species) %>%
group_modify(~ broom::tidy(lm(Petal.Length ~ Sepal.Length, data = .x)))
# a list of vectors
iris %>%
group_by(Species) %>%
group_map(~ quantile(.x$Petal.Length, probs = c(0.25, 0.5, 0.75)))
# to use group_modify() the lambda must return a data frame
iris %>%
group_by(Species) %>%
group_modify(~ {
quantile(.x$Petal.Length, probs = c(0.25, 0.5, 0.75)) %>%
tibble::enframe(name = "prob", value = "quantile")
})
iris %>%
group_by(Species) %>%
group_modify(~ {
.x %>%
purrr::map_dfc(fivenum) %>%
mutate(nms = c("min", "Q1", "median", "Q3", "max"))
})
# group_walk() is for side effects
dir.create(temp <- tempfile())
iris %>%
group_by(Species) %>%
group_walk(~ write.csv(.x, file = file.path(temp, paste0(.y$Species, ".csv"))))
list.files(temp, pattern = "csv$")
unlink(temp, recursive = TRUE)
# group_modify() and ungrouped data frames
mtcars %>%
group_modify(~ head(.x, 2L))
# group_trim -----------------------------------------------------
#' Trim grouping structure
iris %>%
group_by(Species) %>%
filter(Species == "setosa", .preserve = TRUE) %>%
group_trim()
# group_split -------------------------------------------------------------
# ----- use case 1 : on an already grouped tibble
ir <- iris %>%
group_by(Species)
group_split(ir)
group_keys(ir)
# this can be useful if the grouped data has been altered before the split
ir <- iris %>%
group_by(Species) %>%
filter(Sepal.Length > mean(Sepal.Length))
group_split(ir)
group_keys(ir)
# ----- use case 2: using a group_by() grouping specification
# both group_split() and group_keys() have to perform the grouping
# so it only makes sense to do this if you only need one or the other
iris %>%
group_split(Species)
iris %>%
group_keys(Species)
# ident -------------------------------------------------------------------
#'
#' ident() takes unquoted strings and flags them as identifiers. ident_q() assumes its input has already been quoted, and ensures it does not get quoted again. This is currently used only for for schema.table.
ident("x")
# if_else --------------------------------------------------------
x <- c(-5:5, NA)
x
if_else(x < 0, NA_integer_, x)
if_else(x < 0, "negative", "positive", "missing")
# Unlike ifelse, if_else preserves types
x <- factor(sample(letters[1:5], 10, replace = TRUE))
ifelse(x %in% c("a", "b", "c"), x, factor(NA))
if_else(x %in% c("a", "b", "c"), x, factor(NA))
# Attributes are taken from the `true` vector,
# joins -------------------------------------------------------------------
#' The mutating joins add columns from y to x, matching rows based on the keys:
#' inner_join(): includes all rows in x and y.
#' left_join(): includes all rows in x.
#' right_join(): includes all rows in y.
#' full_join(): includes all rows in x or y.
#' ?join
band_members %>% inner_join(band_instruments)
band_members %>% left_join(band_instruments)
band_members %>% right_join(band_instruments) # adds anything in the right data frame
band_members %>% full_join(band_instruments)
# To suppress the message about joining variables, supply `by`
band_members %>% inner_join(band_instruments, by = "name")
band_members %>% inner_join(band_instruments, by = c(name = "name"))
# This is good practice in production code
# Use a named `by` if the join variables have different names
band_members %>% full_join(band_instruments2, by = c("name" = "artist"))
# By default, the join keys from `x` and `y` are coalesced in the output; use
# `keep = TRUE` to keep the join keys from both `x` and `y`
band_members %>%
full_join(band_instruments2, by = c("name" = "artist"), keep = TRUE)
# If a row in `x` matches multiple rows in `y`, all the rows in `y` will be
# returned once for each matching row in `x`
df1 <- tibble(x = 1:3)
df2 <- tibble(x = c(1, 1, 2), y = c("first", "second", "third"))
df1 %>% left_join(df2)
# By default, NAs match other NAs so that there are two
# rows in the output of this join:
df1 <- data.frame(x = c(1, NA), y = 2)
df2 <- data.frame(x = c(1, NA), z = 3)
left_join(df1, df2)
# You can optionally request that NAs don't match, giving a
# a result that more closely resembles SQL joins
left_join(df1, df2, na_matches = "never")
# lead-lag -------------------------------------------------------
#' Find the "previous" (lag()) or "next" (lead()) values in a vector. Useful for comparing values behind of or ahead of the current values.
lag(1:5)
lead(1:5)
x <- 1:5
tibble(behind = lag(x), x, ahead = lead(x))
# If you want to look more rows behind or ahead, use `n`
lag(1:5, n = 1)
lag(1:5, n = 2)
lead(1:5, n = 1)
lead(1:5, n = 2)
# If you want to define a value for non-existing rows, use `default`
lag(1:5)
lag(1:5, default = 0)
lead(1:5)
lead(1:5, default = 6)
# If data are not already ordered, use `order_by`
scrambled <- slice_sample(tibble(year = 2000:2005, value = (0:5) ^ 2), prop = 1)
wrong <- mutate(scrambled, previous_year_value = lag(value))
arrange(wrong, year)
right <- mutate(scrambled, previous_year_value = lag(value, order_by = year))
arrange(right, year)
# nth_first_last ----------------------------------------------------------
#' Extract the first, last or nth value from a vector
x <- 1:10
y <- 10:1
first(x)
last(y)
nth(x, 1)
nth(x, 5)
nth(x, -2)
nth(x, 11)
last(x)
# Second argument provides optional ordering
last(x, y)
# These functions always return a single value
first(integer())
# mutate ------------------------------------------------------------------
#' Create, modify, and delete columns
# mutate(
# .data,
# ...,
# .keep = c("all", "used", "unused", "none"),
# .before = NULL,
# .after = NULL
# )
# Newly created variables are available immediately
starwars %>%
select(name, mass) %>%
mutate(
mass2 = mass * 2,
mass2_squared = mass2 * mass2
)
# As well as adding new variables, you can use mutate() to
# remove variables and modify existing variables.
starwars %>%
select(name, height, mass, homeworld) %>%
mutate(
mass = NULL,
height = height * 0.0328084 # convert to feet
)
# Use across() with mutate() to apply a transformation
# to multiple columns in a tibble.
starwars %>%
select(name, homeworld, species) %>%
mutate(across(!name, as.factor))
# see more in ?across
# Window functions are useful for grouped mutates:
starwars %>%
select(name, mass, homeworld) %>%
group_by(homeworld) %>%
mutate(rank = min_rank(desc(mass)))
# see `vignette("window-functions")` for more details
# By default, new columns are placed on the far right.
# Experimental: you can override with `.before` or `.after`
df <- tibble(x = 1, y = 2)
df %>% mutate(z = x + y)
df %>% mutate(z = x + y, .before = 1)
df %>% mutate(z = x + y, .after = x)
# By default, mutate() keeps all columns from the input data.
# Experimental: You can override with `.keep`
df <- tibble(x = 1, y = 2, a = "a", b = "b")
df %>% mutate(z = x + y, .keep = "all") # the default
df %>% mutate(z = x + y, .keep = "used")
df %>% mutate(z = x + y, .keep = "unused")
df %>% mutate(z = x + y, .keep = "none") # same as transmute()
# The mutate operation may yield different results on grouped
# tibbles because the expressions are computed within groups.
# The following normalises `mass` by the global average:
starwars %>%
select(name, mass, species) %>%
mutate(mass_norm = mass / mean(mass, na.rm = TRUE))
# Whereas this normalises `mass` by the averages within species
# levels:
starwars %>%
select(name, mass, species) %>%
group_by(species) %>%
mutate(mass_norm = mass / mean(mass, na.rm = TRUE))
# Refer to column names stored as strings with the `.data` pronoun:
vars <- c("mass", "height")
mutate(starwars, prod = .data[[vars[[1]]]] * .data[[vars[[2]]]])
# Learn more in ?dplyr_data_masking
# na_if -------------------------------------------------------------------
#' Convert values to NA
na_if(1:5, 5:1)
x <- c(1, -1, 0, 10)
100 / x
100 / na_if(x, 0)
y <- c("abc", "def", "", "ghi")
na_if(y, "")
# na_if() is particularly useful inside mutate(),
# and is meant for use with vectors rather than entire data frames
starwars %>%
select(name, eye_color) %>%
mutate(eye_color = na_if(eye_color, "unknown"))
# na_if() can also be used with mutate() and across()
# to mutate multiple columns
starwars %>%
mutate(across(where(is.character), ~na_if(., "unknown")))
# nest_join ---------------------------------------------------------------
#' nest_join() returns all rows and columns in x with a new nested-df column that contains all matches from y. When there is no match, the list column is a 0-row tibble.
band_members %>% nest_join(band_instruments)
band_members %>% nest_join(band_instruments) |> unnest()
# near --------------------------------------------------------------------
#' Compare two numeric vectors
#' This is a safe way of comparing if two vectors of floating point numbers are (pairwise) equal. This is safer than using ==, because it has a built in tolerance
sqrt(2) ^ 2 == 2
near(sqrt(2) ^ 2, 2)
# order_by ----------------------------------------------------------------
#' Efficiently count the number of unique values in a set of vectors
x <- sample(1:10, 1e5, rep = TRUE)
length(unique(x))
n_distinct(x)
# recode ------------------------------------------------------------------
# For character values, recode values with named arguments only. Unmatched
# values are unchanged.
char_vec <- sample(c("a", "b", "c"), 10, replace = TRUE)
char_vec
recode(char_vec, a = "Apple")
recode(char_vec, a = "Apple", b = "Banana")
# Use .default as replacement for unmatched values. Note that NA and
# replacement values need to be of the same type. For more information, see
# https://adv-r.hadley.nz/vectors-chap.html#missing-values
recode(char_vec, a = "Apple", b = "Banana", .default = NA_character_)
# Throws an error as NA is logical, not character.
try(recode(char_vec, a = "Apple", b = "Banana", .default = NA))
# Use a named character vector for unquote splicing with !!!
level_key <- c(a = "apple", b = "banana", c = "carrot")
recode(char_vec, !!!level_key)
# For numeric values, named arguments can also be used
num_vec <- c(1:4, NA)
recode(num_vec, `2` = 20L, `4` = 40L)
# Or if you don't name the arguments, recode() matches by position.
# (Only works for numeric vector)
recode(num_vec, "a", "b", "c", "d")
# .x (position given) looks in (...), then grabs (... value at position)
# so if nothing at position (here 5), it uses .default or NA.
recode(c(1,5,3), "a", "b", "c", "d", .default = "nothing")
# Note that if the replacements are not compatible with .x,
# unmatched values are replaced by NA and a warning is issued.
recode(num_vec, `2` = "b", `4` = "d")
# use .default to change the replacement value
recode(num_vec, "a", "b", "c", .default = "other")
# use .missing to replace missing values in .x
recode(num_vec, "a", "b", "c", .default = "other", .missing = "missing")
# For factor values, use only named replacements
# and supply default with levels()
factor_vec <- factor(c("a", "b", "c"))
recode(factor_vec, a = "Apple", .default = levels(factor_vec))
# Use recode_factor() to create factors with levels ordered as they
# appear in the recode call. The levels in .default and .missing
# come last.
recode_factor(num_vec, `1` = "z", `2` = "y", `3` = "x")
recode_factor(num_vec, `1` = "z", `2` = "y", `3` = "x",
.default = "D")
recode_factor(num_vec, `1` = "z", `2` = "y", `3` = "x",
.default = "D", .missing = "M")
# When the input vector is a compatible vector (character vector or
# factor), it is reused as default.
recode_factor(letters[1:3], b = "z", c = "y")
recode_factor(factor(letters[1:3]), b = "z", c = "y")
# Use a named character vector to recode factors with unquote splicing.
level_key <- c(a = "apple", b = "banana", c = "carrot")
recode_factor(char_vec, !!!level_key)
# relocate ----------------------------------------------------------------
#' Change column order
df <- tibble(a = 1, b = 1, c = 1, d = "a", e = "a", f = "a")
df
df %>% relocate(f)
df %>% relocate(a, .after = c)
df %>% relocate(f, .before = b)
df %>% relocate(a, .after = last_col())
# relocated columns can change name
df %>% relocate(ff = f)
# Can also select variables based on their type
df %>% relocate(where(is.character))
df %>% relocate(where(is.numeric), .after = last_col())
# Or with any other select helper
df %>% relocate(any_of(c("a", "e", "i", "o", "u")))
# When .before or .after refers to multiple variables they will be
# moved to be immediately before/after the selected variables.
df2 <- tibble(a = 1, b = "a", c = 1, d = "a")
df2 %>% relocate(where(is.numeric), .after = where(is.character))
df2 %>% relocate(where(is.numeric), .before = where(is.character))
# rename ------------------------------------------------------------------
#' Rename columns
iris <- as_tibble(iris) # so it prints a little nicer
rename(iris, petal_length = Petal.Length)
rename_with(iris, toupper)
rename_with(iris, toupper, starts_with("Petal"))
iris |> rename_with(~ tolower(gsub(".", "_", .x, fixed = TRUE)))
# rowwise -----------------------------------------------------------------
#' group input by rows
df <- tibble(x = runif(6), y = runif(6), z = runif(6))
df
# Compute the mean of x, y, z in each row
df %>% rowwise() %>% mutate(m = mean(c(x, y, z)))
# use c_across() to more easily select many variables
df %>% rowwise() %>% mutate(m = mean(c_across(x:z)))
# Compute the minimum of x and y in each row
df %>% rowwise() %>% mutate(m = min(c(x, y, z))) # takes it for each row
df %>% mutate(m = min(c(x, y, z))) # takes the absolute min
# In this case you can use an existing vectorised function:
df %>% mutate(m = pmin(x, y, z))
# Where these functions exist they'll be much faster than rowwise
# so be on the lookout for them.
# rowwise() is also useful when doing simulations
params <- tribble(
~sim, ~n, ~mean, ~sd,
1, 1, 1, 1,
2, 2, 2, 4,
3, 3, -1, 2
)
params
# Here I supply variables to preserve after the summary
params %>%
rowwise(sim) %>%
summarise(z = rnorm(n, mean, sd))
# If you want one row per simulation, put the results in a list()
params %>%
rowwise(sim) %>%
summarise(z = list(rnorm(n, mean, sd)))
# setops ------------------------------------------------------------------
#' These functions override the set functions provided in base to make them generic so that efficient versions for data frames and other tables can be provided. The default methods call the base versions. Beware that intersect(), union() and setdiff() remove duplicates.
mtcars$model <- rownames(mtcars)
first <- mtcars[1:20, ]
second <- mtcars[10:32, ]
intersect(first, second)
union(first, second)
setdiff(first, second)
setdiff(second, first)
union_all(first, second)
setequal(mtcars, mtcars[32:1, ])
# Handling of duplicates:
a <- data.frame(column = c(1:10, 10))
b <- data.frame(column = c(1:5, 5))
# intersection is 1 to 5, duplicates removed (5)
intersect(a, b)
# union is 1 to 10, duplicates removed (5 and 10)
union(a, b)
# set difference, duplicates removed (10)
setdiff(a, b)
# union all does not remove duplicates
union_all(a, b)
# select ------------------------------------------------------------------
#' Subset columns using their names and types
library(tidyverse)
# For better printing
iris <- as_tibble(iris)
starwars %>% select(height)
iris %>% pivot_longer(Sepal.Length)
starwars %>% select(homeworld, height, mass)
iris %>% pivot_longer(c(Sepal.Length, Petal.Length))
starwars %>% select(name:mass)
starwars %>% select(!(name:mass))
iris %>% select(!c(Sepal.Length, Petal.Length))
iris %>% select(!ends_with("Width"))
iris %>% select(starts_with("Petal") & ends_with("Width"))
iris %>% select(starts_with("Petal") | ends_with("Width"))
iris %>% select(starts_with("Petal") & !ends_with("Width"))
# slice -------------------------------------------------------------------
#' Subset rows using their positions
mtcars %>% slice(1L)
# Similar to tail(mtcars, 1):
mtcars %>% slice(n())
mtcars %>% slice(5:n())
# Rows can be dropped with negative indices:
slice(mtcars, -(1:4))
# First and last rows based on existing order
mtcars %>% slice_head(n = 5)
mtcars %>% slice_tail(n = 5)
# Rows with minimum and maximum values of a variable
mtcars %>% slice_min(mpg, n = 5)
mtcars %>% slice_max(mpg, n = 5)
# slice_min() and slice_max() may return more rows than requested
# in the presence of ties. Use with_ties = FALSE to suppress
mtcars %>% slice_min(cyl, n = 1)
mtcars %>% slice_min(cyl, n = 1, with_ties = FALSE)
# slice_sample() allows you to random select with or without replacement
mtcars %>% slice_sample(n = 5)
mtcars %>% slice_sample(n = 5, replace = TRUE)
# you can optionally weight by a variable - this code weights by the
# physical weight of the cars, so heavy cars are more likely to get
# selected
mtcars %>% slice_sample(weight_by = wt, n = 5)
#' Group wise operation ----------------------------------------
df <- tibble(
group = rep(c("a", "b", "c"), c(1, 2, 4)),
x = runif(7)
)
# All slice helpers operate per group, silently truncating to the group
# size, so the following code works without error
df %>% group_by(group) %>% slice_head(n = 2)
# When specifying the proportion of rows to include non-integer sizes
# are rounded down, so group a gets 0 rows
df %>% group_by(group) %>% slice_head(prop = 0.5)
#' Filter equivalents --------------------------------------------
# slice() expressions can often be written to use `filter()` and
# `row_number()`, which can also be translated to SQL. For many databases,
# you'll need to supply an explicit variable to use to compute the row number.
filter(mtcars, row_number() == 1L)
filter(mtcars, row_number() == n())
filter(mtcars, between(row_number(), 5, n()))
# summarise ----------------------------------------------------------------
#' Summarise each group to fewer rows
mtcars %>%
summarise(mean = mean(disp), n = n())
# Usually, you'll want to group first
mtcars %>%
group_by(cyl) %>%
summarise(mean = mean(disp), n = n())
# dplyr 1.0.0 allows to summarise to more than one value:
mtcars %>%
group_by(cyl) %>%
summarise(qs = quantile(disp, c(0.25, 0.75)), prob = c(0.25, 0.75))
# You use a data frame to create multiple columns so you can wrap
# this up into a function:
my_quantile <- function(x, probs) {
tibble(x = quantile(x, probs), probs = probs)
}
mtcars %>%
group_by(cyl) %>%
summarise(my_quantile(disp, c(0.25, 0.75)))
# Each summary call removes one grouping level (since that group
# is now just a single row)
mtcars %>%
group_by(cyl, vs) %>%
summarise(cyl_n = n()) %>%
group_vars()
# BEWARE: reusing variables may lead to unexpected results
mtcars %>%
group_by(cyl) %>%
summarise(disp = mean(disp), sd = sd(disp))
# Refer to column names stored as strings with the `.data` pronoun:
var <- "mass"
summarise(starwars, avg = mean(.data[[var]], na.rm = TRUE))
# Learn more in ?dplyr_data_masking
# with_groups -------------------------------------------------------------
df <- tibble(g = c(1, 1, 2, 2, 3), x = runif(5))
df %>%
with_groups(g, mutate, x_mean = mean(x))
df %>%
with_groups(g, ~ mutate(.x, x1 = first(x)))
df %>%
group_by(g) %>%
with_groups(NULL, mutate, x_mean = mean(x))
# NB: grouping can't be restored if you remove the grouping variables
df %>%
group_by(g) %>%
with_groups(NULL, mutate, g = NULL)
abresler/asbtools documentation built on July 28, 2022, 11:04 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
library(tidyverse)
library(dplyr)
# across ------------------------------------------------------------------
#' Apply a function (or functions) across multiple columns
# Different ways to select the same set of columns
# See <https://tidyselect.r-lib.org/articles/syntax.html> for details
iris %>%
as_tibble() %>%
mutate(across(c(Sepal.Length, Sepal.Width), round))
iris %>%
as_tibble() %>%
mutate(across(c(1, 2), round))
iris %>%
as_tibble() %>%
mutate(across(1:Sepal.Width, round))
iris %>%
as_tibble() %>%
mutate(across(where(is.double) &
!c(Petal.Length, Petal.Width), round))
# A purrr-style formula
iris %>%
group_by(Species) %>%
summarise(across(starts_with("Sepal"), ~ mean(.x, na.rm = TRUE)))
# A named list of functions
iris %>%
group_by(Species) %>%
summarise(across(starts_with("Sepal"), list(mean = mean, sd = sd)))
# Use the .names argument to control the output names
iris %>%
group_by(Species) %>%
summarise(across(starts_with("Sepal"), mean, .names = "mean_{.col}"))
iris %>%
group_by(Species) %>%
summarise(across(starts_with("Sepal"), list(mean = mean, sd = sd), .names = "{.col}.{.fn}"))
# When the list is not named, .fn is replaced by the function's position
iris %>%
group_by(Species) %>%
summarise(across(starts_with("Sepal"), list(mean, sd), .names = "{.col}.fn{.fn}"))
# across() returns a data frame, which can be used as input of another function
df <- data.frame(
x1 = c(1, 2, NA),
x2 = c(4, NA, 6),
y = c("a", "b", "c")
)
df %>%
mutate(x_complete = complete.cases(across(starts_with("x"))))
df %>%
filter(complete.cases(across(starts_with("x"))))
gdf <-
tibble(g = c(1, 1, 2, 3), v1 = 10:13, v2 = 20:23) %>%
group_by(g)
set.seed(1)
# Outside: 1 normal variate
n <- rnorm(1)
gdf %>% mutate(across(v1:v2, ~ .x + n))
# Inside a verb: 3 normal variates (ngroup)
gdf %>% mutate(n = rnorm(1), across(v1:v2, ~ .x + n))
gdf %>% mutate(across(v1:v2, ~ .x + rnorm(1)))
# if_any() and if_all() ----------------------------------------------------
iris %>%
filter(if_any(ends_with("Width"), ~ . > 4)) |> as_tibble()
iris %>%
filter(if_all(ends_with("Width"), ~ . > 2)) |> as_tibble()
# count -------------------------------------------------------------------
# count() is a convenient way to get a sense of the distribution of
# values in a dataset
starwars %>% count(species)
starwars %>% count(species, sort = TRUE)
starwars %>% count(sex, gender, sort = TRUE)
starwars %>% count(birth_decade = round(birth_year, -1))
starwars$birth_year |> round(-1)
# use the `wt` argument to perform a weighted count. This is useful
# when the data has already been aggregated once
df <- tribble(~ name,
~ gender,
~ runs,
"Max",
"male",
10,
"Sandra",
"female",
1,
"Susan",
"female",
4)
# counts rows:
df %>% count(gender)
# counts runs:
df %>% count(gender, wt = runs)
# tally() is a lower-level function that assumes you've done the grouping
starwars %>% tally()
starwars %>% group_by(species) %>% tally()
# both count() and tally() have add_ variants that work like
# mutate() instead of summarise
df %>% add_count(gender, wt = runs)
df |> count(name, gender, wt = runs)
df %>% add_tally(wt = runs)
# between -----------------------------------------------------------------
#' Do values in a numeric vector fall in specified range?
#' Description
#' This is a shortcut for x >= left & x <= right, implemented efficiently in C++ for local values, and translated to the appropriate SQL for remote tables.
between(1:12, 7, 9)
x <- rnorm(1e2)
x[between(x, -1, 1)]
## Or on a tibble using filter
filter(starwars, between(height, 100, 150))
var <- "height"
filter(starwars, between(!!!syms(var), 100, 150))
# bind --------------------------------------------------------------------
#' Efficiently bind multiple data frames by row and column
#' This is an efficient implementation of the common pattern of do.call(rbind, dfs) or do.call(cbind, dfs) for binding many data frames into one.
one <- starwars[1:4,]
two <- starwars[9:12,]
one
two
# You can supply data frames as arguments:
bind_rows(one, two)
# The contents of lists are spliced automatically:
bind_rows(list(one, two))
bind_rows(split(starwars, starwars$homeworld))
bind_rows(list(one, two), list(two, one))
# In addition to data frames, you can supply vectors. In the rows
# direction, the vectors represent rows and should have inner
# names:
bind_rows(c(a = 1, b = 2),
c(a = 3, b = 4))
# You can mix vectors and data frames:
bind_rows(c(a = 1, b = 2),
tibble(a = 3:4, b = 5:6),
c(a = 7, b = 8))
# When you supply a column name with the `.id` argument, a new
# column is created to link each row to its original data frame
bind_rows(list(one, two), .id = "id")
bind_rows(list(a = one, b = two), .id = "id")
bind_rows("group 1" = one,
"group 2" = two,
.id = "groups")
# Columns don't need to match when row-binding
bind_rows(tibble(x = 1:3), tibble(y = 1:4))
# Row sizes must be compatible when column-binding
try(bind_cols(tibble(x = 1:3), tibble(y = 1:2)))
# Even with 0 columns
try(bind_cols(tibble(x = 1:3), tibble()))
bind_cols(one, two)
bind_cols(list(one, two))
# case_when ---------------------------------------------------------------
#' A general vectorised if
x <- 1:50
case_when(x %% 35 == 0 ~ "fizz buzz",
x %% 5 == 0 ~ "fizz",
x %% 7 == 0 ~ "buzz",
TRUE ~ as.character(x))
# Like an if statement, the arguments are evaluated in order, so you must
# proceed from the most specific to the most general. This won't work:
case_when(TRUE ~ as.character(x),
x %% 5 == 0 ~ "fizz",
x %% 7 == 0 ~ "buzz",
x %% 35 == 0 ~ "fizz buzz")
# If none of the cases match, NA is used:
case_when(x %% 5 == 0 ~ "fizz",
x %% 7 == 0 ~ "buzz",
x %% 35 == 0 ~ "fizz buzz")
# Note that NA values in the vector x do not get special treatment. If you want
# to explicitly handle NA values you can use the `is.na` function:
x[2:4] <- NA_real_
case_when(
x %% 35 == 0 ~ "fizz buzz",
x %% 5 == 0 ~ "fizz",
x %% 7 == 0 ~ "buzz",
is.na(x) ~ "nope",
TRUE ~ as.character(x)
)
# All RHS values need to be of the same type. Inconsistent types will throw an error.
# This applies also to NA values used in RHS: NA is logical, use
# typed values like NA_real_, NA_complex, NA_character_, NA_integer_ as appropriate.
case_when(x %% 35 == 0 ~ NA_character_,
x %% 5 == 0 ~ "fizz",
x %% 7 == 0 ~ "buzz",
TRUE ~ as.character(x))
case_when(x %% 35 == 0 ~ 35,
x %% 5 == 0 ~ 5,
x %% 7 == 0 ~ 7,
TRUE ~ NA_real_)
# case_when() evaluates all RHS expressions, and then constructs its
# result by extracting the selected (via the LHS expressions) parts.
# In particular NaNs are produced in this case:
y <- seq(-2, 2, by = .5)
case_when(y >= 0 ~ sqrt(y),
TRUE ~ y)
# This throws an error as NA is logical not numeric
try(case_when(x %% 35 == 0 ~ 35,
x %% 5 == 0 ~ 5,
x %% 7 == 0 ~ 7,
TRUE ~ NA))
# case_when is particularly useful inside mutate when you want to
# create a new variable that relies on a complex combination of existing
# variables
starwars %>%
select(name:mass, gender, species) %>%
mutate(type = case_when(
height > 200 | mass > 200 ~ "large",
species == "Droid" ~ "robot",
TRUE ~ "other"
))
# `case_when()` is not a tidy eval function. If you'd like to reuse
# the same patterns, extract the `case_when()` call in a normal
# function:
case_character_type <- function(height, mass, species) {
case_when(height > 200 | mass > 200 ~ "large",
species == "Droid" ~ "robot",
TRUE ~ "other")
}
case_character_type(150, 250, "Droid")
case_character_type(150, 150, "Droid")
# Such functions can be used inside `mutate()` as well:
starwars %>%
mutate(type = case_character_type(height, mass, species)) %>%
pull(type)
# coalsece ----------------------------------------------------------------
# Use a single value to replace all missing values
x <- sample(c(1:5, NA, NA, NA))
coalesce(x, 0L)
# Or match together a complete vector from missing pieces
y <- c(1, 2, NA, NA, 5)
z <- c(NA, NA, 3, 4, 5)
coalesce(y, z)
# Supply lists by with dynamic dots
vecs <- list(c(1, 2, NA, NA, 5),
c(NA, NA, 3, 4, 5))
coalesce(!!!vecs)
# compute -----------------------------------------------------------------
#' Force computation of a database
#'
mtcars2 <- dbplyr::src_memdb() %>%
copy_to(mtcars, name = "mtcars2-cc", overwrite = TRUE)
remote <- mtcars2 %>%
filter(cyl == 8) %>%
select(mpg:drat)
# Compute query and save in remote table
compute(remote)
# Compute query bring back to this session
collect(remote)
# Creates a fresh query based on the generated SQL
collapse(remote)
# context -----------------------------------------------------------------
#' Context dependent expressions
df <- tibble(
g = sample(rep(letters[1:3], 1:3)),
x = runif(6),
y = runif(6)
)
df
gf <- df %>% group_by(g)
gf %>% summarise(n = n())
gf %>% mutate(id = cur_group_id())
gf %>% summarise(row = cur_group_rows())
gf %>% summarise(data = list(cur_group()))
gf %>% summarise(data = list(cur_data()))
gf %>% summarise(data = list(cur_data_all()))
gf %>% mutate(across(everything(), ~ paste(cur_column(), round(.x, 2))))
# cum_ --------------------------------------------------------------------
#' Cumulativate versions of any, all, and mean
x <- c(1, 3, 5, 2, 2)
cummean(x)
cumsum(x) / seq_along(x)
# `cumall()` and `cumany()` return logicals
cumall(x < 5)
cumany(x == 3)
# `cumall()` vs. `cumany()`
df <- data.frame(date = as.Date("2020-01-01") + 0:6,
balance = c(100, 50, 25, -25, -50, 30, 120))
# all rows after first overdraft
df %>% filter(cumany(balance < 0))
# all rows until first overdraft
df %>% filter(cumall(!(balance < 0)))
# c_aross -----------------------------------------------------------------
#' Combine values from multiple columns
df <- tibble(id = 1:4, w = runif(4), x = runif(4), y = runif(4), z = runif(4))
df
df %>%
rowwise() %>%
mutate(sum = sum(c_across(w:z)),
sd = sd(c_across(w:z)))
# rank --------------------------------------------------------------------
#' Six variations on ranking functions, mimicking the ranking functions described in SQL2003. They are currently implemented using the built in rank function, and are provided mainly as a convenience when converting between R and SQL. All ranking functions map smallest inputs to smallest outputs. Use desc() to reverse the direction.
x <- c(5, 1, 3, 2, 2, NA)
row_number(x)
min_rank(x)
dense_rank(x)
percent_rank(x)
cume_dist(x)
ntile(x, 2)
ntile(1:8, 3)
# row_number can be used with single table verbs without specifying x
# (for data frames and databases that support windowing)
mutate(mtcars, row_number() == 1L)
mtcars %>% filter(between(row_number(), 1, 10))
# explain -----------------------------------------------------------------
#' Explain details of a tbl
lahman_s <- dbplyr::lahman_sqlite()
batting <- tbl(lahman_s, "Batting")
batting %>% show_query()
batting %>% explain()
# The batting database has indices on all ID variables:
# SQLite automatically picks the most restrictive index
batting %>% filter(lgID == "NL" & yearID == 2000L) %>% explain()
# OR's will use multiple indexes
batting %>% filter(lgID == "NL" | yearID == 2000) %>% explain()
batting %>% filter(lgID == "NL" | yearID == 2000) |> collect() |> View()
batting %>% filter(lgID == "NL" | yearID == 2000) |> compute()
# Joins will use indexes in both tables
teams <- tbl(lahman_s, "Teams")
batting %>% left_join(teams, c("yearID", "teamID")) %>% explain()
batting %>% left_join(teams, c("yearID", "teamID")) |> collect()
# filter ------------------------------------------------------------------
# Filtering by one criterion
filter(starwars, species == "Human")
filter(starwars, mass > 1000)
# Filtering by multiple criteria within a single logical expression
filter(starwars, hair_color == "none" & eye_color == "black")
filter(starwars, hair_color == "none" | eye_color == "black")
# When multiple expressions are used, they are combined using &
filter(starwars, hair_color == "none", eye_color == "black")
# The filtering operation may yield different results on grouped
# tibbles because the expressions are computed within groups.
#
# The following filters rows where `mass` is greater than the
# global average:
starwars %>% filter(mass > mean(mass, na.rm = TRUE))
# Whereas this keeps rows with `mass` greater than the gender
# average:
starwars %>% group_by(gender) %>% filter(mass > mean(mass, na.rm = TRUE))
# To refer to column names that are stored as strings, use the `.data` pronoun:
vars <- c("mass", "height")
cond <- c(80, 150)
starwars %>%
filter(
.data[[vars[[1]]]] > cond[[1]],
.data[[vars[[2]]]] > cond[[2]]
)
# nth ------------------------------------------------------------
#' Extract the first, last or nth value from a vector
x <- 1:10
y <- 10:1
first(x)
last(y)
nth(x, 1)
nth(x, 5)
nth(x, -2)
nth(x, 11)
last(x)
# Second argument provides optional ordering
last(x, y)
# These functions always return a single value
first(integer())
# glimpse -----------------------------------------------------------------
glimpse(mtcars)
# Note that original x is (invisibly) returned, allowing `glimpse()` to be
# used within a pipeline.
mtcars %>%
glimpse() %>%
select(1:3)
glimpse(starwars)
# group_by ----------------------------------------------------------------
by_cyl <- mtcars %>% group_by(cyl)
# grouping doesn't change how the data looks (apart from listing
# how it's grouped):
by_cyl
# It changes how it acts with the other dplyr verbs:
by_cyl %>% summarise(
disp = mean(disp),
hp = mean(hp)
)
by_cyl %>% filter(disp == max(disp))
# Each call to summarise() removes a layer of grouping
by_vs_am <- mtcars %>% group_by(vs, am)
by_vs <- by_vs_am %>% summarise(n = n())
by_vs
by_vs %>% summarise(n = sum(n))
# To removing grouping, use ungroup
by_vs %>%
ungroup() %>%
summarise(n = sum(n))
# By default, group_by() overrides existing grouping
by_cyl %>%
group_by(vs, am) %>%
group_vars()
# Use add = TRUE to instead append
by_cyl %>%
group_by(vs, am, .add = TRUE) %>%
group_vars()
# You can group by expressions: this is a short-hand
# for a mutate() followed by a group_by()
mtcars %>%
group_by(vsam = vs + am)
# The implicit mutate() step is always performed on the
# ungrouped data. Here we get 3 groups:
mtcars %>%
group_by(vs) %>%
group_by(hp_cut = cut(hp, 3))
# If you want it to be performed by groups,
# you have to use an explicit mutate() call.
# Here we get 3 groups per value of vs
mtcars %>%
group_by(vs) %>%
mutate(hp_cut = cut(hp, 3)) %>%
group_by(hp_cut)
# when factors are involved and .drop = FALSE, groups can be empty
tbl <- tibble(
x = 1:10,
y = factor(rep(c("a", "c"), each = 5), levels = c("a", "b", "c"))
)
tbl %>%
group_by(y, .drop = FALSE) %>%
group_rows()
# group_cols --------------------------------------------------------------
gdf <- iris %>% group_by(Species)
gdf %>% select(group_cols())
# Remove the grouping variables from mutate selections:
gdf %>% mutate_at(vars(-group_cols()), `/`, 100)
# -> No longer necessary with across()
gdf %>% mutate(across(everything(), ~ . / 100))
# Apply a function to each group ------------------------------------------
# return a list
mtcars %>%
group_by(cyl) %>%
group_map(~ head(.x, 2L))
# return a tibble grouped by `cyl` with 2 rows per group
# the grouping data is recalculated
mtcars %>%
group_by(cyl) %>%
group_modify(~ head(.x, 2L))
# a list of tibbles
iris %>%
group_by(Species) %>%
group_map(~ broom::tidy(lm(Petal.Length ~ Sepal.Length, data = .x)))
# a restructured grouped tibble
iris %>%
group_by(Species) %>%
group_modify(~ broom::tidy(lm(Petal.Length ~ Sepal.Length, data = .x)))
# a list of vectors
iris %>%
group_by(Species) %>%
group_map(~ quantile(.x$Petal.Length, probs = c(0.25, 0.5, 0.75)))
# to use group_modify() the lambda must return a data frame
iris %>%
group_by(Species) %>%
group_modify(~ {
quantile(.x$Petal.Length, probs = c(0.25, 0.5, 0.75)) %>%
tibble::enframe(name = "prob", value = "quantile")
})
iris %>%
group_by(Species) %>%
group_modify(~ {
.x %>%
purrr::map_dfc(fivenum) %>%
mutate(nms = c("min", "Q1", "median", "Q3", "max"))
})
# group_walk() is for side effects
dir.create(temp <- tempfile())
iris %>%
group_by(Species) %>%
group_walk(~ write.csv(.x, file = file.path(temp, paste0(.y$Species, ".csv"))))
list.files(temp, pattern = "csv$")
unlink(temp, recursive = TRUE)
# group_modify() and ungrouped data frames
mtcars %>%
group_modify(~ head(.x, 2L))
# group_trim -----------------------------------------------------
#' Trim grouping structure
iris %>%
group_by(Species) %>%
filter(Species == "setosa", .preserve = TRUE) %>%
group_trim()
# group_split -------------------------------------------------------------
# ----- use case 1 : on an already grouped tibble
ir <- iris %>%
group_by(Species)
group_split(ir)
group_keys(ir)
# this can be useful if the grouped data has been altered before the split
ir <- iris %>%
group_by(Species) %>%
filter(Sepal.Length > mean(Sepal.Length))
group_split(ir)
group_keys(ir)
# ----- use case 2: using a group_by() grouping specification
# both group_split() and group_keys() have to perform the grouping
# so it only makes sense to do this if you only need one or the other
iris %>%
group_split(Species)
iris %>%
group_keys(Species)
# ident -------------------------------------------------------------------
#'
#' ident() takes unquoted strings and flags them as identifiers. ident_q() assumes its input has already been quoted, and ensures it does not get quoted again. This is currently used only for for schema.table.
ident("x")
# if_else --------------------------------------------------------
x <- c(-5:5, NA)
x
if_else(x < 0, NA_integer_, x)
if_else(x < 0, "negative", "positive", "missing")
# Unlike ifelse, if_else preserves types
x <- factor(sample(letters[1:5], 10, replace = TRUE))
ifelse(x %in% c("a", "b", "c"), x, factor(NA))
if_else(x %in% c("a", "b", "c"), x, factor(NA))
# Attributes are taken from the `true` vector,
# joins -------------------------------------------------------------------
#' The mutating joins add columns from y to x, matching rows based on the keys:
#' inner_join(): includes all rows in x and y.
#' left_join(): includes all rows in x.
#' right_join(): includes all rows in y.
#' full_join(): includes all rows in x or y.
#' ?join
band_members %>% inner_join(band_instruments)
band_members %>% left_join(band_instruments)
band_members %>% right_join(band_instruments) # adds anything in the right data frame
band_members %>% full_join(band_instruments)
# To suppress the message about joining variables, supply `by`
band_members %>% inner_join(band_instruments, by = "name")
band_members %>% inner_join(band_instruments, by = c(name = "name"))
# This is good practice in production code
# Use a named `by` if the join variables have different names
band_members %>% full_join(band_instruments2, by = c("name" = "artist"))
# By default, the join keys from `x` and `y` are coalesced in the output; use
# `keep = TRUE` to keep the join keys from both `x` and `y`
band_members %>%
full_join(band_instruments2, by = c("name" = "artist"), keep = TRUE)
# If a row in `x` matches multiple rows in `y`, all the rows in `y` will be
# returned once for each matching row in `x`
df1 <- tibble(x = 1:3)
df2 <- tibble(x = c(1, 1, 2), y = c("first", "second", "third"))
df1 %>% left_join(df2)
# By default, NAs match other NAs so that there are two
# rows in the output of this join:
df1 <- data.frame(x = c(1, NA), y = 2)
df2 <- data.frame(x = c(1, NA), z = 3)
left_join(df1, df2)
# You can optionally request that NAs don't match, giving a
# a result that more closely resembles SQL joins
left_join(df1, df2, na_matches = "never")
# lead-lag -------------------------------------------------------
#' Find the "previous" (lag()) or "next" (lead()) values in a vector. Useful for comparing values behind of or ahead of the current values.
lag(1:5)
lead(1:5)
x <- 1:5
tibble(behind = lag(x), x, ahead = lead(x))
# If you want to look more rows behind or ahead, use `n`
lag(1:5, n = 1)
lag(1:5, n = 2)
lead(1:5, n = 1)
lead(1:5, n = 2)
# If you want to define a value for non-existing rows, use `default`
lag(1:5)
lag(1:5, default = 0)
lead(1:5)
lead(1:5, default = 6)
# If data are not already ordered, use `order_by`
scrambled <- slice_sample(tibble(year = 2000:2005, value = (0:5) ^ 2), prop = 1)
wrong <- mutate(scrambled, previous_year_value = lag(value))
arrange(wrong, year)
right <- mutate(scrambled, previous_year_value = lag(value, order_by = year))
arrange(right, year)
# nth_first_last ----------------------------------------------------------
#' Extract the first, last or nth value from a vector
x <- 1:10
y <- 10:1
first(x)
last(y)
nth(x, 1)
nth(x, 5)
nth(x, -2)
nth(x, 11)
last(x)
# Second argument provides optional ordering
last(x, y)
# These functions always return a single value
first(integer())
# mutate ------------------------------------------------------------------
#' Create, modify, and delete columns
# mutate(
# .data,
# ...,
# .keep = c("all", "used", "unused", "none"),
# .before = NULL,
# .after = NULL
# )
# Newly created variables are available immediately
starwars %>%
select(name, mass) %>%
mutate(
mass2 = mass * 2,
mass2_squared = mass2 * mass2
)
# As well as adding new variables, you can use mutate() to
# remove variables and modify existing variables.
starwars %>%
select(name, height, mass, homeworld) %>%
mutate(
mass = NULL,
height = height * 0.0328084 # convert to feet
)
# Use across() with mutate() to apply a transformation
# to multiple columns in a tibble.
starwars %>%
select(name, homeworld, species) %>%
mutate(across(!name, as.factor))
# see more in ?across
# Window functions are useful for grouped mutates:
starwars %>%
select(name, mass, homeworld) %>%
group_by(homeworld) %>%
mutate(rank = min_rank(desc(mass)))
# see `vignette("window-functions")` for more details
# By default, new columns are placed on the far right.
# Experimental: you can override with `.before` or `.after`
df <- tibble(x = 1, y = 2)
df %>% mutate(z = x + y)
df %>% mutate(z = x + y, .before = 1)
df %>% mutate(z = x + y, .after = x)
# By default, mutate() keeps all columns from the input data.
# Experimental: You can override with `.keep`
df <- tibble(x = 1, y = 2, a = "a", b = "b")
df %>% mutate(z = x + y, .keep = "all") # the default
df %>% mutate(z = x + y, .keep = "used")
df %>% mutate(z = x + y, .keep = "unused")
df %>% mutate(z = x + y, .keep = "none") # same as transmute()
# The mutate operation may yield different results on grouped
# tibbles because the expressions are computed within groups.
# The following normalises `mass` by the global average:
starwars %>%
select(name, mass, species) %>%
mutate(mass_norm = mass / mean(mass, na.rm = TRUE))
# Whereas this normalises `mass` by the averages within species
# levels:
starwars %>%
select(name, mass, species) %>%
group_by(species) %>%
mutate(mass_norm = mass / mean(mass, na.rm = TRUE))
# Refer to column names stored as strings with the `.data` pronoun:
vars <- c("mass", "height")
mutate(starwars, prod = .data[[vars[[1]]]] * .data[[vars[[2]]]])
# Learn more in ?dplyr_data_masking
# na_if -------------------------------------------------------------------
#' Convert values to NA
na_if(1:5, 5:1)
x <- c(1, -1, 0, 10)
100 / x
100 / na_if(x, 0)
y <- c("abc", "def", "", "ghi")
na_if(y, "")
# na_if() is particularly useful inside mutate(),
# and is meant for use with vectors rather than entire data frames
starwars %>%
select(name, eye_color) %>%
mutate(eye_color = na_if(eye_color, "unknown"))
# na_if() can also be used with mutate() and across()
# to mutate multiple columns
starwars %>%
mutate(across(where(is.character), ~na_if(., "unknown")))
# nest_join ---------------------------------------------------------------
#' nest_join() returns all rows and columns in x with a new nested-df column that contains all matches from y. When there is no match, the list column is a 0-row tibble.
band_members %>% nest_join(band_instruments)
band_members %>% nest_join(band_instruments) |> unnest()
# near --------------------------------------------------------------------
#' Compare two numeric vectors
#' This is a safe way of comparing if two vectors of floating point numbers are (pairwise) equal. This is safer than using ==, because it has a built in tolerance
sqrt(2) ^ 2 == 2
near(sqrt(2) ^ 2, 2)
# order_by ----------------------------------------------------------------
#' Efficiently count the number of unique values in a set of vectors
x <- sample(1:10, 1e5, rep = TRUE)
length(unique(x))
n_distinct(x)
# recode ------------------------------------------------------------------
# For character values, recode values with named arguments only. Unmatched
# values are unchanged.
char_vec <- sample(c("a", "b", "c"), 10, replace = TRUE)
char_vec
recode(char_vec, a = "Apple")
recode(char_vec, a = "Apple", b = "Banana")
# Use .default as replacement for unmatched values. Note that NA and
# replacement values need to be of the same type. For more information, see
# https://adv-r.hadley.nz/vectors-chap.html#missing-values
recode(char_vec, a = "Apple", b = "Banana", .default = NA_character_)
# Throws an error as NA is logical, not character.
try(recode(char_vec, a = "Apple", b = "Banana", .default = NA))
# Use a named character vector for unquote splicing with !!!
level_key <- c(a = "apple", b = "banana", c = "carrot")
recode(char_vec, !!!level_key)
# For numeric values, named arguments can also be used
num_vec <- c(1:4, NA)
recode(num_vec, `2` = 20L, `4` = 40L)
# Or if you don't name the arguments, recode() matches by position.
# (Only works for numeric vector)
recode(num_vec, "a", "b", "c", "d")
# .x (position given) looks in (...), then grabs (... value at position)
# so if nothing at position (here 5), it uses .default or NA.
recode(c(1,5,3), "a", "b", "c", "d", .default = "nothing")
# Note that if the replacements are not compatible with .x,
# unmatched values are replaced by NA and a warning is issued.
recode(num_vec, `2` = "b", `4` = "d")
# use .default to change the replacement value
recode(num_vec, "a", "b", "c", .default = "other")
# use .missing to replace missing values in .x
recode(num_vec, "a", "b", "c", .default = "other", .missing = "missing")
# For factor values, use only named replacements
# and supply default with levels()
factor_vec <- factor(c("a", "b", "c"))
recode(factor_vec, a = "Apple", .default = levels(factor_vec))
# Use recode_factor() to create factors with levels ordered as they
# appear in the recode call. The levels in .default and .missing
# come last.
recode_factor(num_vec, `1` = "z", `2` = "y", `3` = "x")
recode_factor(num_vec, `1` = "z", `2` = "y", `3` = "x",
.default = "D")
recode_factor(num_vec, `1` = "z", `2` = "y", `3` = "x",
.default = "D", .missing = "M")
# When the input vector is a compatible vector (character vector or
# factor), it is reused as default.
recode_factor(letters[1:3], b = "z", c = "y")
recode_factor(factor(letters[1:3]), b = "z", c = "y")
# Use a named character vector to recode factors with unquote splicing.
level_key <- c(a = "apple", b = "banana", c = "carrot")
recode_factor(char_vec, !!!level_key)
# relocate ----------------------------------------------------------------
#' Change column order
df <- tibble(a = 1, b = 1, c = 1, d = "a", e = "a", f = "a")
df
df %>% relocate(f)
df %>% relocate(a, .after = c)
df %>% relocate(f, .before = b)
df %>% relocate(a, .after = last_col())
# relocated columns can change name
df %>% relocate(ff = f)
# Can also select variables based on their type
df %>% relocate(where(is.character))
df %>% relocate(where(is.numeric), .after = last_col())
# Or with any other select helper
df %>% relocate(any_of(c("a", "e", "i", "o", "u")))
# When .before or .after refers to multiple variables they will be
# moved to be immediately before/after the selected variables.
df2 <- tibble(a = 1, b = "a", c = 1, d = "a")
df2 %>% relocate(where(is.numeric), .after = where(is.character))
df2 %>% relocate(where(is.numeric), .before = where(is.character))
# rename ------------------------------------------------------------------
#' Rename columns
iris <- as_tibble(iris) # so it prints a little nicer
rename(iris, petal_length = Petal.Length)
rename_with(iris, toupper)
rename_with(iris, toupper, starts_with("Petal"))
iris |> rename_with(~ tolower(gsub(".", "_", .x, fixed = TRUE)))
# rowwise -----------------------------------------------------------------
#' group input by rows
df <- tibble(x = runif(6), y = runif(6), z = runif(6))
df
# Compute the mean of x, y, z in each row
df %>% rowwise() %>% mutate(m = mean(c(x, y, z)))
# use c_across() to more easily select many variables
df %>% rowwise() %>% mutate(m = mean(c_across(x:z)))
# Compute the minimum of x and y in each row
df %>% rowwise() %>% mutate(m = min(c(x, y, z))) # takes it for each row
df %>% mutate(m = min(c(x, y, z))) # takes the absolute min
# In this case you can use an existing vectorised function:
df %>% mutate(m = pmin(x, y, z))
# Where these functions exist they'll be much faster than rowwise
# so be on the lookout for them.
# rowwise() is also useful when doing simulations
params <- tribble(
~sim, ~n, ~mean, ~sd,
1, 1, 1, 1,
2, 2, 2, 4,
3, 3, -1, 2
)
params
# Here I supply variables to preserve after the summary
params %>%
rowwise(sim) %>%
summarise(z = rnorm(n, mean, sd))
# If you want one row per simulation, put the results in a list()
params %>%
rowwise(sim) %>%
summarise(z = list(rnorm(n, mean, sd)))
# setops ------------------------------------------------------------------
#' These functions override the set functions provided in base to make them generic so that efficient versions for data frames and other tables can be provided. The default methods call the base versions. Beware that intersect(), union() and setdiff() remove duplicates.
mtcars$model <- rownames(mtcars)
first <- mtcars[1:20, ]
second <- mtcars[10:32, ]
intersect(first, second)
union(first, second)
setdiff(first, second)
setdiff(second, first)
union_all(first, second)
setequal(mtcars, mtcars[32:1, ])
# Handling of duplicates:
a <- data.frame(column = c(1:10, 10))
b <- data.frame(column = c(1:5, 5))
# intersection is 1 to 5, duplicates removed (5)
intersect(a, b)
# union is 1 to 10, duplicates removed (5 and 10)
union(a, b)
# set difference, duplicates removed (10)
setdiff(a, b)
# union all does not remove duplicates
union_all(a, b)
# select ------------------------------------------------------------------
#' Subset columns using their names and types
library(tidyverse)
# For better printing
iris <- as_tibble(iris)
starwars %>% select(height)
iris %>% pivot_longer(Sepal.Length)
starwars %>% select(homeworld, height, mass)
iris %>% pivot_longer(c(Sepal.Length, Petal.Length))
starwars %>% select(name:mass)
starwars %>% select(!(name:mass))
iris %>% select(!c(Sepal.Length, Petal.Length))
iris %>% select(!ends_with("Width"))
iris %>% select(starts_with("Petal") & ends_with("Width"))
iris %>% select(starts_with("Petal") | ends_with("Width"))
iris %>% select(starts_with("Petal") & !ends_with("Width"))
# slice -------------------------------------------------------------------
#' Subset rows using their positions
mtcars %>% slice(1L)
# Similar to tail(mtcars, 1):
mtcars %>% slice(n())
mtcars %>% slice(5:n())
# Rows can be dropped with negative indices:
slice(mtcars, -(1:4))
# First and last rows based on existing order
mtcars %>% slice_head(n = 5)
mtcars %>% slice_tail(n = 5)
# Rows with minimum and maximum values of a variable
mtcars %>% slice_min(mpg, n = 5)
mtcars %>% slice_max(mpg, n = 5)
# slice_min() and slice_max() may return more rows than requested
# in the presence of ties. Use with_ties = FALSE to suppress
mtcars %>% slice_min(cyl, n = 1)
mtcars %>% slice_min(cyl, n = 1, with_ties = FALSE)
# slice_sample() allows you to random select with or without replacement
mtcars %>% slice_sample(n = 5)
mtcars %>% slice_sample(n = 5, replace = TRUE)
# you can optionally weight by a variable - this code weights by the
# physical weight of the cars, so heavy cars are more likely to get
# selected
mtcars %>% slice_sample(weight_by = wt, n = 5)
#' Group wise operation ----------------------------------------
df <- tibble(
group = rep(c("a", "b", "c"), c(1, 2, 4)),
x = runif(7)
)
# All slice helpers operate per group, silently truncating to the group
# size, so the following code works without error
df %>% group_by(group) %>% slice_head(n = 2)
# When specifying the proportion of rows to include non-integer sizes
# are rounded down, so group a gets 0 rows
df %>% group_by(group) %>% slice_head(prop = 0.5)
#' Filter equivalents --------------------------------------------
# slice() expressions can often be written to use `filter()` and
# `row_number()`, which can also be translated to SQL. For many databases,
# you'll need to supply an explicit variable to use to compute the row number.
filter(mtcars, row_number() == 1L)
filter(mtcars, row_number() == n())
filter(mtcars, between(row_number(), 5, n()))
# summarise ----------------------------------------------------------------
#' Summarise each group to fewer rows
mtcars %>%
summarise(mean = mean(disp), n = n())
# Usually, you'll want to group first
mtcars %>%
group_by(cyl) %>%
summarise(mean = mean(disp), n = n())
# dplyr 1.0.0 allows to summarise to more than one value:
mtcars %>%
group_by(cyl) %>%
summarise(qs = quantile(disp, c(0.25, 0.75)), prob = c(0.25, 0.75))
# You use a data frame to create multiple columns so you can wrap
# this up into a function:
my_quantile <- function(x, probs) {
tibble(x = quantile(x, probs), probs = probs)
}
mtcars %>%
group_by(cyl) %>%
summarise(my_quantile(disp, c(0.25, 0.75)))
# Each summary call removes one grouping level (since that group
# is now just a single row)
mtcars %>%
group_by(cyl, vs) %>%
summarise(cyl_n = n()) %>%
group_vars()
# BEWARE: reusing variables may lead to unexpected results
mtcars %>%
group_by(cyl) %>%
summarise(disp = mean(disp), sd = sd(disp))
# Refer to column names stored as strings with the `.data` pronoun:
var <- "mass"
summarise(starwars, avg = mean(.data[[var]], na.rm = TRUE))
# Learn more in ?dplyr_data_masking
# with_groups -------------------------------------------------------------
df <- tibble(g = c(1, 1, 2, 2, 3), x = runif(5))
df %>%
with_groups(g, mutate, x_mean = mean(x))
df %>%
with_groups(g, ~ mutate(.x, x1 = first(x)))
df %>%
group_by(g) %>%
with_groups(NULL, mutate, x_mean = mean(x))
# NB: grouping can't be restored if you remove the grouping variables
df %>%
group_by(g) %>%
with_groups(NULL, mutate, g = NULL)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.