dplyr

across(.cols, .fns, ..., .names = NULL, .unpack = FALSE) if_any(.cols, .fns, ..., .names = NULL) if_all(.cols, .fns, ..., .names = NULL)

# For better printing iris <- as_tibble(iris) # across() ----------------------------------------------------------------- # Using everything() to apply the same function to all columns iris |> mutate(across(everything(), as.character)) # Different ways to select the same set of columns # See <https://tidyselect.r-lib.org/articles/syntax.html> for details iris |> mutate(across(c(Sepal.Length, Sepal.Width), round)) iris |> mutate(across(c(1, 2), round)) iris |> mutate(across(1:Sepal.Width, round)) iris |> mutate(across(where(is.double) & !c(Petal.Length, Petal.Width), round)) # Using an external vector of names cols <- c("Sepal.Length", "Petal.Width") iris |> mutate(across(all_of(cols), round)) # If the external vector is named, the output columns will be named according # to those names names(cols) <- tolower(cols) iris |> mutate(across(all_of(cols), 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" ) ) # If a named external vector is used for column selection, .names will use # those names when constructing the output names iris |> group_by(Species) |> summarise(across(all_of(cols), mean, .names = "mean_.col")) # 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") ) # When the functions in .fns return a data frame, you typically get a # "packed" data frame back quantile_df <- function(x, probs = c(0.25, 0.5, 0.75)) tibble(quantile = probs, value = quantile(x, probs)) iris |> reframe(across(starts_with("Sepal"), quantile_df)) # Use .unpack to automatically expand these packed data frames into their # individual columns iris |> reframe(across(starts_with("Sepal"), quantile_df, .unpack = TRUE)) # .unpack can utilize a glue specification if you don't like the defaults iris |> reframe( across(starts_with("Sepal"), quantile_df, .unpack = "outer.inner") ) # This is also useful inside mutate(), for example, with a multi-lag helper multilag <- function(x, lags = 1:3) names(lags) <- as.character(lags) purrr::map_dfr(lags, lag, x = x) iris |> group_by(Species) |> mutate(across(starts_with("Sepal"), multilag, .unpack = TRUE)) |> select(Species, starts_with("Sepal")) # if_any() and if_all() ---------------------------------------------------- iris |> filter(if_any(ends_with("Width"), ~ . > 4)) iris |> filter_out(if_any(ends_with("Width"), ~ . > 4)) iris |> filter(if_all(ends_with("Width"), ~ . > 2)) iris |> filter_out(if_all(ends_with("Width"), ~ . > 2))

all_equal( target, current, ignore_col_order = TRUE, ignore_row_order = TRUE, convert = FALSE, ... )

scramble <- function(x) x[sample(nrow(x)), sample(ncol(x))] # `all_equal()` ignored row and column ordering by default, # but we now feel that that makes it too easy to make mistakes mtcars2 <- scramble(mtcars) all_equal(mtcars, mtcars2) # Instead, be explicit about the row and column ordering all.equal( mtcars, mtcars2[rownames(mtcars), names(mtcars)] )

all_vars(expr) any_vars(expr)

arrange(.data, ..., .by_group = FALSE) arrangedata.frame(.data, ..., .by_group = FALSE, .locale = NULL)

arrange(mtcars, cyl, disp) arrange(mtcars, desc(disp)) # grouped arrange ignores groups by_cyl <- mtcars |> group_by(cyl) by_cyl |> arrange(desc(wt)) # Unless you specifically ask: by_cyl |> arrange(desc(wt), .by_group = TRUE) # use embracing when wrapping in a function; # see ?rlang::args_data_masking for more details tidy_eval_arrange <- function(.data, var) .data |> arrange( var ) tidy_eval_arrange(mtcars, mpg) # Use `across()` or `pick()` to select columns with tidy-select iris |> arrange(pick(starts_with("Sepal"))) iris |> arrange(across(starts_with("Sepal"), desc))

arrange_all(.tbl, .funs = list(), ..., .by_group = FALSE, .locale = NULL) arrange_at(.tbl, .vars, .funs = list(), ..., .by_group = FALSE, .locale = NULL) arrange_if( .tbl, .predicate, .funs = list(), ..., .by_group = FALSE, .locale = NULL )

df <- as_tibble(mtcars) arrange_all(df) # -> arrange(df, pick(everything())) arrange_all(df, desc) # -> arrange(df, across(everything(), desc))

auto_copy(x, y, copy = FALSE, ...)

db_desc(x) sql_translate_env(con) db_list_tables(con) db_has_table(con, table) db_data_type(con, fields) db_save_query(con, sql, name, temporary = TRUE, ...) db_begin(con, ...) db_commit(con, ...) db_rollback(con, ...) db_write_table(con, table, types, values, temporary = FALSE, ...) db_create_table(con, table, types, temporary = FALSE, ...) db_insert_into(con, table, values, ...) db_create_indexes(con, table, indexes = NULL, unique = FALSE, ...) db_create_index(con, table, columns, name = NULL, unique = FALSE, ...) db_drop_table(con, table, force = FALSE, ...) db_analyze(con, table, ...) db_explain(con, sql, ...) db_query_fields(con, sql, ...) db_query_rows(con, sql, ...) sql_select( con, select, from, where = NULL, group_by = NULL, having = NULL, order_by = NULL, limit = NULL, distinct = FALSE, ... ) sql_subquery(con, from, name = random_table_name(), ...) sql_join(con, x, y, vars, type = "inner", by = NULL, ...) sql_semi_join(con, x, y, anti = FALSE, by = NULL, ...) sql_set_op(con, x, y, method) sql_escape_string(con, x) sql_escape_ident(con, x)

band_members band_instruments band_instruments2

band_members band_instruments band_instruments2

between(x, left, right, ..., ptype = NULL)

between(1:12, 7, 9) x <- rnorm(1e2) x[between(x, -1, 1)] # On a tibble using `filter()` filter(starwars, between(height, 100, 150)) # Using the `ptype` argument with ordered factors, where otherwise everything # is cast to the common type of character before the comparison x <- ordered( c("low", "medium", "high", "medium"), levels = c("low", "medium", "high") ) between(x, "medium", "high") between(x, "medium", "high", ptype = x)

bind_cols( ..., .name_repair = c("unique", "universal", "check_unique", "minimal") )

df1 <- tibble(x = 1:3) df2 <- tibble(y = 3:1) bind_cols(df1, df2) # Row sizes must be compatible when column-binding try(bind_cols(tibble(x = 1:3), tibble(y = 1:2)))

bind_rows(..., .id = NULL)

df1 <- tibble(x = 1:2, y = letters[1:2]) df2 <- tibble(x = 4:5, z = 1:2) # You can supply individual data frames as arguments: bind_rows(df1, df2) # Or a list of data frames: bind_rows(list(df1, df2)) # 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(df1, df2), .id = "id") bind_rows(list(a = df1, b = df2), .id = "id")

c_across(cols)

df <- tibble(id = 1:4, w = runif(4), x = runif(4), y = runif(4), z = runif(4)) df |> rowwise() |> mutate( sum = sum(c_across(w:z)), sd = sd(c_across(w:z)) )

case_when( ..., .default = NULL, .unmatched = "default", .ptype = NULL, .size = NULL ) replace_when(x, ...)

x <- 1:70 case_when( x %% 35 == 0 ~ "fizz buzz", x %% 5 == 0 ~ "fizz", x %% 7 == 0 ~ "buzz", .default = 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( x %% 5 == 0 ~ "fizz", x %% 7 == 0 ~ "buzz", x %% 35 == 0 ~ "fizz buzz", .default = as.character(x) ) # If none of the cases match and no `.default` is supplied, NA is used: case_when( x %% 35 == 0 ~ "fizz buzz", x %% 5 == 0 ~ "fizz", x %% 7 == 0 ~ "buzz" ) # Note that `NA` values on the LHS are treated like `FALSE` and will be # assigned the `.default` value. You must handle them explicitly if you # want to use a different value. The exact way to handle missing values is # dependent on the set of LHS conditions you use. x[2:4] <- NA_real_ case_when( x %% 35 == 0 ~ "fizz buzz", x %% 5 == 0 ~ "fizz", x %% 7 == 0 ~ "buzz", is.na(x) ~ "nope", .default = as.character(x) ) # `case_when()` is not a replacement for basic if/else control flow. When # you have a single scalar condition, using if/else is faster, simpler to # reason about, and is lazy on the branch that isn't run. For example, this # seems to work: x <- "value" case_when(is.character(x) ~ x, .default = "not-a-character") # Until `x` is a non-character type x <- 1 try(case_when(is.character(x) ~ x, .default = "not-a-character")) # Instead, you should use if/else if (is.character(x)) y <- x else y <- "not-a-character" y # If you believe that you've covered every possible case, then set # `.unmatched = "error"` rather than supplying a `.default`. This adds an # extra layer of safety to `case_when()` and is particularly useful when you # have a series of complex expressions! set.seed(123) x <- sample(50) # Oops, we forgot to handle `50` try(case_when( x < 10 ~ "ten", x < 20 ~ "twenty", x < 30 ~ "thirty", x < 40 ~ "forty", x < 50 ~ "fifty", .unmatched = "error" )) case_when( x < 10 ~ "ten", x < 20 ~ "twenty", x < 30 ~ "thirty", x < 40 ~ "forty", x <= 50 ~ "fifty", .unmatched = "error" ) # Note that `NA` is considered unmatched and must be handled with its own # explicit case, even if that case just propagates the missing value! x[c(2, 5)] <- NA case_when( x < 10 ~ "ten", x < 20 ~ "twenty", x < 30 ~ "thirty", x < 40 ~ "forty", x <= 50 ~ "fifty", is.na(x) ~ NA, .unmatched = "error" ) # `replace_when()` is useful when you're updating an existing vector, # rather than creating an entirely new one. Note the so-far unused "puppy" # factor level: pets <- tibble( name = c("Max", "Bella", "Chuck", "Luna", "Cooper"), type = factor( c("dog", "dog", "cat", "dog", "cat"), levels = c("dog", "cat", "puppy") ), age = c(1, 3, 5, 2, 4) ) # We can replace some values with `"puppy"` based on arbitrary conditions. # Even though we are using a character `"puppy"` value, `replace_when()` will # automatically cast it to the factor type of `type` for us. pets |> mutate( type = replace_when(type, type == "dog" & age <= 2 ~ "puppy") ) # Compare that with this `case_when()` call, which loses the factor class. # It's always better to use `replace_when()` when updating a few values in # an existing vector! pets |> mutate( type = case_when(type == "dog" & age <= 2 ~ "puppy", .default = type) ) # `case_when()` and `replace_when()` evaluate all RHS expressions, and then # construct their result by extracting the selected (via the LHS expressions) # parts. For example, `NaN`s are produced here because `sqrt(y)` is evaluated # on all of `y`, not just where `y >= 0`. y <- seq(-2, 2, by = .5) replace_when(y, y >= 0 ~ sqrt(y)) # These functions are 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", .default = "other" ) ) # `case_when()` is not a tidy eval function. If you'd like to reuse # the same patterns, extract the `case_when()` call into a normal # function: case_character_type <- function(height, mass, species) case_when( height > 200 | mass > 200 ~ "large", species == "Droid" ~ "robot", .default = "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) # `case_when()` ignores `NULL` inputs. This is useful when you'd # like to use a pattern only under certain conditions. Here we'll # take advantage of the fact that `if` returns `NULL` when there is # no `else` clause: case_character_type <- function(height, mass, species, robots = TRUE) case_when( height > 200 | mass > 200 ~ "large", if (robots) species == "Droid" ~ "robot", .default = "other" ) starwars |> mutate(type = case_character_type(height, mass, species, robots = FALSE)) |> pull(type) # `replace_when()` can also be used in combination with `pick()` to # conditionally mutate rows within multiple columns using a single condition. # Here `replace_when()` returns a data frame with new `species` and `name` # columns, which `mutate()` then automatically unpacks. starwars |> select(homeworld, species, name) |> mutate(replace_when( pick(species, name), homeworld == "Tatooine" ~ tibble( species = "Tatooinese", name = paste(name, "(Tatooine)") ) ))

case_match(.x, ..., .default = NULL, .ptype = NULL)

# `case_match()` is deprecated and has been replaced by `recode_values()` and # `replace_values()` x <- c("a", "b", "a", "d", "b", NA, "c", "e") # `recode_values()` is a 1:1 replacement for `case_match()` case_match( x, "a" ~ 1, "b" ~ 2, "c" ~ 3, "d" ~ 4 ) recode_values( x, "a" ~ 1, "b" ~ 2, "c" ~ 3, "d" ~ 4 ) # `recode_values()` has an additional `unmatched` argument to help you catch # missed mappings try(recode_values( x, "a" ~ 1, "b" ~ 2, "c" ~ 3, "d" ~ 4, unmatched = "error" )) # `recode_values()` also has additional `from` and `to` arguments, which are # useful when your lookup table is defined elsewhere (for example, it could # be read in from a CSV file). This is very difficult to do with # `case_match()`! lookup <- tribble( ~from, ~to, "a", 1, "b", 2, "c", 3, "d", 4 ) recode_values(x, from = lookup$from, to = lookup$to) # Both `case_match()` and `recode_values()` work with more than just # character inputs: y <- as.integer(c(1, 2, 1, 3, 1, NA, 2, 4)) case_match( y, c(1, 3) ~ "odd", c(2, 4) ~ "even", .default = "missing" ) recode_values( y, c(1, 3) ~ "odd", c(2, 4) ~ "even", default = "missing" ) # Or with a lookup table lookup <- tribble( ~from, ~to, c(1, 3), "odd", c(2, 4), "even" ) recode_values(y, from = lookup$from, to = lookup$to, default = "missing") # `replace_values()` is a convenient way to replace selected values, leaving # everything else as is. It's similar to `case_match(y, .default = y)`. replace_values(y, NA ~ 0) case_match(y, NA ~ 0, .default = y) # Notably, `replace_values()` is type stable, which means that `y` can't # change types out from under you, unlike with `case_match()`! typeof(y) typeof(replace_values(y, NA ~ 0)) typeof(case_match(y, NA ~ 0, .default = y)) # We believe that `replace_values()` better expresses intent when doing a # partial replacement. Compare these two `mutate()` calls, each with the # goals of: # - Replace missings in `hair_color` # - Replace some of the `species` starwars |> mutate( hair_color = case_match(hair_color, NA ~ "unknown", .default = hair_color), species = case_match( species, "Human" ~ "Humanoid", "Droid" ~ "Robot", c("Wookiee", "Ewok") ~ "Hairy", .default = species ), .keep = "used" ) updates <- tribble( ~from, ~to, "Human", "Humanoid", "Droid", "Robot", c("Wookiee", "Ewok"), "Hairy" ) starwars |> mutate( hair_color = replace_values(hair_color, NA ~ "unknown"), species = replace_values(species, from = updates$from, to = updates$to), .keep = "used" )

check_dbplyr() wrap_dbplyr_obj(obj_name)

if (requireNamespace("dbplyr", quietly = TRUE)) withAutoprint(\ # examplesIf wrap_dbplyr_obj("build_sql") wrap_dbplyr_obj("base_agg") \) # examplesIf

coalesce(..., .ptype = NULL, .size = NULL)

# Replace missing values with a single value x <- sample(c(1:5, NA, NA, NA)) coalesce(x, 0L) # Or replace missing values with the corresponding non-missing value in # another vector x <- c(1, 2, NA, NA, 5, NA) y <- c(NA, NA, 3, 4, 5, NA) coalesce(x, y) # For cases like these where your replacement is a single value or a single # vector, `replace_values()` works just as well replace_values(x, NA ~ 0) coalesce(x, 0) replace_values(x, NA ~ y) coalesce(x, y) # `coalesce()` really shines when you have >2 vectors to coalesce with z <- c(NA, 2, 3, 4, 5, 6) coalesce(x, y, z) # If you're looking to replace values with `NA`, rather than replacing `NA` # with a value, then use `replace_values()` x <- c(0, -1, 5, -99, 8) replace_values(x, c(-1, -99) ~ NA) # The equivalent to a missing value in a list is `NULL` coalesce(list(1, 2, NULL, NA), list(0)) # Supply lists of vectors by splicing them into dots vecs <- list( c(1, 2, NA, NA, 5), c(NA, NA, 3, 4, 5) ) coalesce(!!!vecs)

common_by(by = NULL, x, y)

compute(x, ...) collect(x, ...) collapse(x, ...)

if (requireNamespace("dbplyr", quietly = TRUE) && requireNamespace("RSQLite", quietly = TRUE)) withAutoprint(\ # examplesIf 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) \) # examplesIf

consecutive_id(...)

consecutive_id(c(TRUE, TRUE, FALSE, FALSE, TRUE, FALSE, NA, NA)) consecutive_id(c(1, 1, 1, 2, 1, 1, 2, 2)) df <- data.frame(x = c(0, 0, 1, 0), y = c(2, 2, 2, 2)) df |> group_by(x, y) |> summarise(n = n()) df |> group_by(id = consecutive_id(x, y), x, y) |> summarise(n = n())

n() cur_group() cur_group_id() cur_group_rows() cur_column()

df <- tibble( g = sample(rep(letters[1:3], 1:3)), x = runif(6), y = runif(6) ) gf <- df |> group_by(g) gf |> summarise(n = n()) gf |> mutate(id = cur_group_id()) gf |> reframe(row = cur_group_rows()) gf |> summarise(data = list(cur_group())) gf |> mutate(across(everything(), ~ paste(cur_column(), round(.x, 2))))

copy_to(dest, df, name = deparse(substitute(df)), overwrite = FALSE, ...)

iris2 <- dbplyr::src_memdb() |> copy_to(iris, overwrite = TRUE) iris2

count(x, ..., wt = NULL, sort = FALSE, name = NULL) countdata.frame( x, ..., wt = NULL, sort = FALSE, name = NULL, .drop = group_by_drop_default(x) ) tally(x, wt = NULL, sort = FALSE, name = NULL) add_count(x, ..., wt = NULL, sort = FALSE, name = NULL, .drop = deprecated()) add_tally(x, wt = NULL, sort = FALSE, name = NULL)

# 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)) # 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) # When factors are involved, `.drop = FALSE` can be used to retain factor # levels that don't appear in the data df2 <- tibble( id = 1:5, type = factor(c("a", "c", "a", NA, "a"), levels = c("a", "b", "c")) ) df2 |> count(type) df2 |> count(type, .drop = FALSE) # Or, using `group_by()`: df2 |> group_by(type, .drop = FALSE) |> count() # 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 |> add_tally(wt = runs)

cross_join(x, y, ..., copy = FALSE, suffix = c(".x", ".y"))

# Cross joins match each row in `x` to every row in `y`. # Data within the columns is not used in the matching process. cross_join(band_instruments, band_members) # Control the suffix added to variables duplicated in # `x` and `y` with `suffix`. cross_join(band_instruments, band_members, suffix = c("", "_y"))

cumall(x) cumany(x) cummean(x)

# `cummean()` returns a numeric/integer vector of the same length # as the input vector. 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)))

# Deprecated in 1.0.0 ------------------------------------- combine(...) src_mysql( dbname, host = NULL, port = 0L, username = "root", password = "", ... ) src_postgres( dbname = NULL, host = NULL, port = NULL, user = NULL, password = NULL, ... ) src_sqlite(path, create = FALSE) src_local(tbl, pkg = NULL, env = NULL) src_df(pkg = NULL, env = NULL) tbl_df(data) as.tbl(x, ...) add_rownames(df, var = "rowname")

summarise_each(tbl, funs, ...) summarise_each_(tbl, funs, vars) mutate_each(tbl, funs, ...) mutate_each_(tbl, funs, vars) summarize_each(tbl, funs, ...) summarize_each_(tbl, funs, vars)

add_count_(x, vars, wt = NULL, sort = FALSE) add_tally_(x, wt, sort = FALSE) arrange_(.data, ..., .dots = list()) count_(x, vars, wt = NULL, sort = FALSE, .drop = group_by_drop_default(x)) distinct_(.data, ..., .dots, .keep_all = FALSE) do_(.data, ..., .dots = list()) filter_(.data, ..., .dots = list()) funs_(dots, args = list(), env = base_env()) group_by_(.data, ..., .dots = list(), add = FALSE) group_indices_(.data, ..., .dots = list()) mutate_(.data, ..., .dots = list()) tally_(x, wt, sort = FALSE) transmute_(.data, ..., .dots = list()) rename_(.data, ..., .dots = list()) select_(.data, ..., .dots = list()) slice_(.data, ..., .dots = list()) summarise_(.data, ..., .dots = list()) summarize_(.data, ..., .dots = list())

cur_data() cur_data_all()

desc(x)

desc(1:10) desc(factor(letters)) first_day <- seq(as.Date("1910/1/1"), as.Date("1920/1/1"), "years") desc(first_day) starwars |> arrange(desc(mass))

dim_desc(x)

dim_desc(mtcars)

distinct(.data, ..., .keep_all = FALSE)

df <- tibble( x = sample(10, 100, rep = TRUE), y = sample(10, 100, rep = TRUE) ) nrow(df) nrow(distinct(df)) nrow(distinct(df, x, y)) distinct(df, x) distinct(df, y) # You can choose to keep all other variables as well distinct(df, x, .keep_all = TRUE) distinct(df, y, .keep_all = TRUE) # You can also use distinct on computed variables distinct(df, diff = abs(x - y)) # Use `pick()` to select columns with tidy-select distinct(starwars, pick(contains("color"))) # Grouping ------------------------------------------------- df <- tibble( g = c(1, 1, 2, 2, 2), x = c(1, 1, 2, 1, 2), y = c(3, 2, 1, 3, 1) ) df <- df |> group_by(g) # With grouped data frames, distinctness is computed within each group df |> distinct(x) # When `...` are omitted, `distinct()` still computes distinctness using # all variables in the data frame df |> distinct()

distinct_all(.tbl, .funs = list(), ..., .keep_all = FALSE) distinct_at(.tbl, .vars, .funs = list(), ..., .keep_all = FALSE) distinct_if(.tbl, .predicate, .funs = list(), ..., .keep_all = FALSE)

df <- tibble(x = rep(2:5, each = 2) / 2, y = rep(2:3, each = 4) / 2) distinct_all(df) # -> distinct(df, pick(everything())) distinct_at(df, vars(x,y)) # -> distinct(df, pick(x, y)) distinct_if(df, is.numeric) # -> distinct(df, pick(where(is.numeric))) # You can supply a function that will be applied before extracting the distinct values # The variables of the sorted tibble keep their original values. distinct_all(df, round) # -> distinct(df, across(everything(), round))

distinct_prepare( .data, vars, group_vars = character(), .keep_all = FALSE, caller_env = caller_env(2), error_call = caller_env() ) group_by_prepare( .data, ..., .add = FALSE, .dots = deprecated(), add = deprecated(), error_call = caller_env() )

do(.data, ...)

# do() with unnamed arguments becomes reframe() or summarise() # . becomes pick() by_cyl <- mtcars |> group_by(cyl) by_cyl |> do(head(., 2)) # -> by_cyl |> reframe(head(pick(everything()), 2)) by_cyl |> slice_head(n = 2) # Can refer to variables directly by_cyl |> do(mean = mean(.$vs)) # -> by_cyl |> summarise(mean = mean(vs)) # do() with named arguments becomes nest_by() + mutate() & list() models <- by_cyl |> do(mod = lm(mpg ~ disp, data = .)) # -> models <- mtcars |> nest_by(cyl) |> mutate(mod = list(lm(mpg ~ disp, data = data))) models |> summarise(rsq = summary(mod)$r.squared) # use broom to turn models into data models |> do(data.frame( var = names(coef(.$mod)), coef(summary(.$mod))) ) if (requireNamespace("broom", quietly = TRUE)) withAutoprint(\ # examplesIf # -> models |> reframe(broom::tidy(mod)) \) # examplesIf

if (dplyr:::has_minimum_stringi()) withAutoprint(\ # examplesIf df <- tibble(x = c("a", "b", "C", "B", "c")) df # Default locale is C, which groups the English alphabet by case, placing # uppercase letters before lowercase letters. arrange(df, x) # The American English locale groups the alphabet by letter. # Explicitly override `.locale` with `"en"` for this ordering. arrange(df, x, .locale = "en") # This Danish letter is expected to sort after `z` df <- tibble(x = c("o", "p", "00F8", "z")) df # The American English locale sorts it right after `o` arrange(df, x, .locale = "en") # Using `"da"` for Danish ordering gives the expected result arrange(df, x, .locale = "da") \) # examplesIf

dplyr_row_slice(data, i, ...) dplyr_col_modify(data, cols) dplyr_reconstruct(data, template)

explain(x, ...) show_query(x, ...)

if (requireNamespace("dbplyr", quietly = TRUE) && requireNamespace("RSQLite", quietly = TRUE)) withAutoprint(\ # examplesIf 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() # Joins will use indexes in both tables teams <- tbl(lahman_s, "Teams") batting |> left_join(teams, c("yearID", "teamID")) |> explain() \) # examplesIf

filter(.data, ..., .by = NULL, .preserve = FALSE) filter_out(.data, ..., .by = NULL, .preserve = FALSE)

# Filtering for one criterion filter(starwars, species == "Human") # Filtering for multiple criteria within a single logical expression filter(starwars, hair_color == "none" & eye_color == "black") filter(starwars, hair_color == "none" | eye_color == "black") # Multiple comma separated expressions are combined using `&` starwars |> filter(hair_color == "none", eye_color == "black") # To combine comma separated expressions using `|` instead, use `when_any()` starwars |> filter(when_any(hair_color == "none", eye_color == "black")) # Filtering out to drop rows filter_out(starwars, hair_color == "none") # When filtering out, it can be useful to first interactively filter for the # rows you want to drop, just to double check that you've written the # conditions correctly. Then, just change `filter()` to `filter_out()`. filter(starwars, mass > 1000, eye_color == "orange") filter_out(starwars, mass > 1000, eye_color == "orange") # The filtering operation may yield different results on grouped # tibbles because the expressions are computed within groups. # # The following keeps 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 per `gender` # average: starwars |> filter(mass > mean(mass, na.rm = TRUE), .by = gender) # If you find yourself trying to use a `filter()` to drop rows, then # you should consider if switching to `filter_out()` can simplify your # conditions. For example, to drop blond individuals, you might try: starwars |> filter(hair_color != "blond") # But this also drops rows with an `NA` hair color! To retain those: starwars |> filter(hair_color != "blond" | is.na(hair_color)) # But explicit `NA` handling like this can quickly get unwieldy, especially # with multiple conditions. Since your intent was to specify rows to drop # rather than rows to keep, use `filter_out()`. This also removes the need # for any explicit `NA` handling. starwars |> filter_out(hair_color == "blond") # 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]] ) # Learn more in ?rlang::args_data_masking

semi_join(x, y, by = NULL, copy = FALSE, ...) semi_joindata.frame(x, y, by = NULL, copy = FALSE, ..., na_matches = c("na", "never")) anti_join(x, y, by = NULL, copy = FALSE, ...) anti_joindata.frame(x, y, by = NULL, copy = FALSE, ..., na_matches = c("na", "never"))

# "Filtering" joins keep cases from the LHS band_members |> semi_join(band_instruments) band_members |> anti_join(band_instruments) # To suppress the message about joining variables, supply `by` band_members |> semi_join(band_instruments, by = join_by(name)) # This is good practice in production code

filter_all(.tbl, .vars_predicate, .preserve = FALSE) filter_if(.tbl, .predicate, .vars_predicate, .preserve = FALSE) filter_at(.tbl, .vars, .vars_predicate, .preserve = FALSE)

# While filter() accepts expressions with specific variables, the # scoped filter verbs take an expression with the pronoun `.` and # replicate it over all variables. This expression should be quoted # with all_vars() or any_vars(): all_vars(is.na(.)) any_vars(is.na(.)) # You can take the intersection of the replicated expressions: filter_all(mtcars, all_vars(. > 150)) # -> filter(mtcars, if_all(everything(), ~ .x > 150)) # Or the union: filter_all(mtcars, any_vars(. > 150)) # -> filter(mtcars, if_any(everything(), ~ . > 150)) # You can vary the selection of columns on which to apply the # predicate. filter_at() takes a vars() specification: filter_at(mtcars, vars(starts_with("d")), any_vars((. %% 2) == 0)) # -> filter(mtcars, if_any(starts_with("d"), ~ (.x %% 2) == 0)) # And filter_if() selects variables with a predicate function: filter_if(mtcars, ~ all(floor(.) == .), all_vars(. != 0)) # -> is_int <- function(x) all(floor(x) == x) filter(mtcars, if_all(where(is_int), ~ .x != 0))

funs(..., .args = list())

funs("mean", mean(., na.rm = TRUE)) # -> list(mean = mean, mean = ~ mean(.x, na.rm = TRUE)) funs(m1 = mean, m2 = "mean", m3 = mean(., na.rm = TRUE)) # -> list(m1 = mean, m2 = "mean", m3 = ~ mean(.x, na.rm = TRUE))

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(.data, ..., .add = FALSE, .drop = group_by_drop_default(.data)) ungroup(x, ...)

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_by_all( .tbl, .funs = list(), ..., .add = FALSE, .drop = group_by_drop_default(.tbl) ) group_by_at( .tbl, .vars, .funs = list(), ..., .add = FALSE, .drop = group_by_drop_default(.tbl) ) group_by_if( .tbl, .predicate, .funs = list(), ..., .add = FALSE, .drop = group_by_drop_default(.tbl) )

# Group a data frame by all variables: group_by_all(mtcars) # -> mtcars |> group_by(pick(everything())) # Group by variables selected with a predicate: group_by_if(iris, is.factor) # -> iris |> group_by(pick(where(is.factor))) # Group by variables selected by name: group_by_at(mtcars, vars(vs, am)) # -> mtcars |> group_by(pick(vs, am)) # Like group_by(), the scoped variants have optional mutate # semantics. This provide a shortcut for group_by() + mutate(): d <- tibble(x=c(1,1,2,2), y=c(1,2,1,2)) group_by_all(d, as.factor) # -> d |> group_by(across(everything(), as.factor)) group_by_if(iris, is.factor, as.character) # -> iris |> group_by(across(where(is.factor), as.character))

group_by_drop_default(.tbl)

group_by_drop_default(iris) iris |> group_by(Species) |> group_by_drop_default() iris |> group_by(Species, .drop = FALSE) |> group_by_drop_default()

group_cols(vars = NULL, data = NULL)

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

group_data(.data) group_keys(.tbl, ...) group_rows(.data) group_indices(.data, ...) group_vars(x) groups(x) group_size(x) n_groups(x)

df <- tibble(x = c(1,1,2,2)) group_vars(df) group_rows(df) group_data(df) group_indices(df) gf <- group_by(df, x) group_vars(gf) group_rows(gf) group_data(gf) group_indices(gf)

group_map(.data, .f, ..., .keep = FALSE) group_modify(.data, .f, ..., .keep = FALSE) group_walk(.data, .f, ..., .keep = FALSE)

# 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)) if (requireNamespace("broom", quietly = TRUE)) withAutoprint(\ # examplesIf # 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))) \) # examplesIf # 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_nest(.tbl, ..., .key = "data", keep = FALSE)

#----- use case 1: a grouped data frame iris |> group_by(Species) |> group_nest() # this can be useful if the grouped data has been altered before nesting iris |> group_by(Species) |> filter(Sepal.Length > mean(Sepal.Length)) |> group_nest() #----- use case 2: using group_nest() on a ungrouped data frame with # a grouping specification that uses the data mask starwars |> group_nest(species, homeworld)

group_split(.tbl, ..., .keep = TRUE)

ir <- iris |> group_by(Species) group_split(ir) group_keys(ir)

group_trim(.tbl, .drop = group_by_drop_default(.tbl))

iris |> group_by(Species) |> filter(Species == "setosa", .preserve = TRUE) |> group_trim()

grouped_df(data, vars, drop = group_by_drop_default(data)) is.grouped_df(x) is_grouped_df(x)

ident(...)

# Identifiers are escaped with " if (requireNamespace("dbplyr", quietly = TRUE)) withAutoprint(\ # examplesIf ident("x") \) # examplesIf

if_else( condition, true, false, missing = NULL, ..., ptype = NULL, size = deprecated() )

x <- c(-5:5, NA) if_else(x < 0, NA, x) # Explicitly handle `NA` values in the `condition` with `missing` if_else(x < 0, "negative", "positive", missing = "missing") # Unlike `ifelse()`, `if_else()` preserves types x <- factor(sample(letters[1:5], 10, replace = TRUE)) ifelse(x %in% c("a", "b", "c"), x, NA) if_else(x %in% c("a", "b", "c"), x, NA) # `if_else()` is often useful for creating new columns inside of `mutate()` starwars |> mutate(category = if_else(height < 100, "short", "tall"), .keep = "used")

join_by(...)

sales <- tibble( id = c(1L, 1L, 1L, 2L, 2L), sale_date = as.Date(c("2018-12-31", "2019-01-02", "2019-01-05", "2019-01-04", "2019-01-01")) ) sales promos <- tibble( id = c(1L, 1L, 2L), promo_date = as.Date(c("2019-01-01", "2019-01-05", "2019-01-02")) ) promos # Match `id` to `id`, and `sale_date` to `promo_date` by <- join_by(id, sale_date == promo_date) left_join(sales, promos, by) # For each `sale_date` within a particular `id`, # find all `promo_date`s that occurred before that particular sale by <- join_by(id, sale_date >= promo_date) left_join(sales, promos, by) # For each `sale_date` within a particular `id`, # find only the closest `promo_date` that occurred before that sale by <- join_by(id, closest(sale_date >= promo_date)) left_join(sales, promos, by) # If you want to disallow exact matching in rolling joins, use `>` rather # than `>=`. Note that the promo on `2019-01-05` is no longer considered the # closest match for the sale on the same date. by <- join_by(id, closest(sale_date > promo_date)) left_join(sales, promos, by) # Same as before, but also require that the promo had to occur at most 1 # day before the sale was made. We'll use a full join to see that id 2's # promo on `2019-01-02` is no longer matched to the sale on `2019-01-04`. sales <- mutate(sales, sale_date_lower = sale_date - 1) by <- join_by(id, closest(sale_date >= promo_date), sale_date_lower <= promo_date) full_join(sales, promos, by) # --------------------------------------------------------------------------- segments <- tibble( segment_id = 1:4, chromosome = c("chr1", "chr2", "chr2", "chr1"), start = c(140, 210, 380, 230), end = c(150, 240, 415, 280) ) segments reference <- tibble( reference_id = 1:4, chromosome = c("chr1", "chr1", "chr2", "chr2"), start = c(100, 200, 300, 415), end = c(150, 250, 399, 450) ) reference # Find every time a segment `start` falls between the reference # `[start, end]` range. by <- join_by(chromosome, between(start, start, end)) full_join(segments, reference, by) # If you wanted the reference columns first, supply `reference` as `x` # and `segments` as `y`, then explicitly refer to their columns using `x$` # and `y$`. by <- join_by(chromosome, between(y$start, x$start, x$end)) full_join(reference, segments, by) # Find every time a segment falls completely within a reference. # Sometimes using `x$` and `y$` makes your intentions clearer, even if they # match the default behavior. by <- join_by(chromosome, within(x$start, x$end, y$start, y$end)) inner_join(segments, reference, by) # Find every time a segment overlaps a reference in any way. by <- join_by(chromosome, overlaps(x$start, x$end, y$start, y$end)) full_join(segments, reference, by) # It is common to have right-open ranges with bounds like `[)`, which would # mean an end value of `415` would no longer overlap a start value of `415`. # Setting `bounds` allows you to compute overlaps with those kinds of ranges. by <- join_by(chromosome, overlaps(x$start, x$end, y$start, y$end, bounds = "[)")) full_join(segments, reference, by)

last_dplyr_warnings(n = 5)

lag(x, n = 1L, default = NULL, order_by = NULL, ...) lead(x, n = 1L, default = NULL, order_by = NULL, ...)

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 to pad with, use `default` lag(1:5) lag(1:5, default = 0) lead(1:5) lead(1:5, default = 6) # If the 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)

make_tbl(subclass, ...)

mutate(.data, ...) mutatedata.frame( .data, ..., .by = NULL, .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. 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. 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") # Grouping ---------------------------------------- # 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)) # Indirection ---------------------------------------- # 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 ?rlang::args_data_masking

inner_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = NULL ) inner_joindata.frame( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = NULL, na_matches = c("na", "never"), multiple = "all", unmatched = "drop", relationship = NULL ) left_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = NULL ) left_joindata.frame( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = NULL, na_matches = c("na", "never"), multiple = "all", unmatched = "drop", relationship = NULL ) right_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = NULL ) right_joindata.frame( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = NULL, na_matches = c("na", "never"), multiple = "all", unmatched = "drop", relationship = NULL ) full_join( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = NULL ) full_joindata.frame( x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ..., keep = NULL, na_matches = c("na", "never"), multiple = "all", relationship = NULL )

band_members |> inner_join(band_instruments) band_members |> left_join(band_instruments) band_members |> right_join(band_instruments) band_members |> full_join(band_instruments) # To suppress the message about joining variables, supply `by` band_members |> inner_join(band_instruments, by = join_by(name)) # This is good practice in production code # Use an equality expression if the join variables have different names band_members |> full_join(band_instruments2, by = join_by(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 = join_by(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) # If a row in `y` also matches multiple rows in `x`, this is known as a # many-to-many relationship, which is typically a result of an improperly # specified join or some kind of messy data. In this case, a warning is # thrown by default: df3 <- tibble(x = c(1, 1, 1, 3)) df3 |> left_join(df2) # In the rare case where a many-to-many relationship is expected, set # `relationship = "many-to-many"` to silence this warning df3 |> left_join(df2, relationship = "many-to-many") # Use `join_by()` with a condition other than `==` to perform an inequality # join. Here we match on every instance where `df1$x > df2$x`. df1 |> left_join(df2, join_by(x > x)) # 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")

mutate_all(.tbl, .funs, ...) mutate_if(.tbl, .predicate, .funs, ...) mutate_at(.tbl, .vars, .funs, ..., .cols = NULL) transmute_all(.tbl, .funs, ...) transmute_if(.tbl, .predicate, .funs, ...) transmute_at(.tbl, .vars, .funs, ..., .cols = NULL)

iris <- as_tibble(iris) # All variants can be passed functions and additional arguments, # purrr-style. The _at() variants directly support strings. Here # we'll scale the variables `height` and `mass`: scale2 <- function(x, na.rm = FALSE) (x - mean(x, na.rm = na.rm)) / sd(x, na.rm) starwars |> mutate_at(c("height", "mass"), scale2) # -> starwars |> mutate(across(c("height", "mass"), scale2)) # You can pass additional arguments to the function: starwars |> mutate_at(c("height", "mass"), scale2, na.rm = TRUE) starwars |> mutate_at(c("height", "mass"), ~scale2(., na.rm = TRUE)) # -> starwars |> mutate(across(c("height", "mass"), ~ scale2(.x, na.rm = TRUE))) # You can also supply selection helpers to _at() functions but you have # to quote them with vars(): iris |> mutate_at(vars(matches("Sepal")), log) iris |> mutate(across(matches("Sepal"), log)) # The _if() variants apply a predicate function (a function that # returns TRUE or FALSE) to determine the relevant subset of # columns. Here we divide all the numeric columns by 100: starwars |> mutate_if(is.numeric, scale2, na.rm = TRUE) starwars |> mutate(across(where(is.numeric), ~ scale2(.x, na.rm = TRUE))) # mutate_if() is particularly useful for transforming variables from # one type to another iris |> mutate_if(is.factor, as.character) iris |> mutate_if(is.double, as.integer) # -> iris |> mutate(across(where(is.factor), as.character)) iris |> mutate(across(where(is.double), as.integer)) # Multiple transformations ---------------------------------------- # If you want to apply multiple transformations, pass a list of # functions. When there are multiple functions, they create new # variables instead of modifying the variables in place: iris |> mutate_if(is.numeric, list(scale2, log)) iris |> mutate_if(is.numeric, list(~scale2(.), ~log(.))) iris |> mutate_if(is.numeric, list(scale = scale2, log = log)) # -> iris |> as_tibble() |> mutate(across(where(is.numeric), list(scale = scale2, log = log))) # When there's only one function in the list, it modifies existing # variables in place. Give it a name to instead create new variables: iris |> mutate_if(is.numeric, list(scale2)) iris |> mutate_if(is.numeric, list(scale = scale2))

n_distinct(..., na.rm = FALSE)

x <- c(1, 1, 2, 2, 2) n_distinct(x) y <- c(3, 3, NA, 3, 3) n_distinct(y) n_distinct(y, na.rm = TRUE) # Pairs (1, 3), (2, 3), and (2, NA) are distinct n_distinct(x, y) # (2, NA) is dropped, leaving 2 distinct combinations n_distinct(x, y, na.rm = TRUE) # Also works with data frames n_distinct(data.frame(x, y))

na_if(x, y)

# `na_if()` is useful for replacing a single problematic value with `NA` na_if(c(-99, 1, 4, 3, -99, 5), -99) na_if(c("abc", "def", "", "ghi"), "") # You can use it to standardize `NaN`s to `NA` na_if(c(1, NaN, NA, 2, NaN), NaN) # Because `na_if()` is an R translation of SQL's `NULLIF` command, # it compares `x` and `y` element by element. Where `x` and `y` are # equal, the value in `x` is replaced with an `NA`. na_if( x = c(1, 2, 5, 5, 6), y = c(0, 2, 3, 5, 4) ) # If you have multiple problematic values that you'd like to replace with # `NA`, then `replace_values()` is a better choice than `na_if()` x <- c(-99, 1, 4, 0, -99, 5, -1, 0, 5) replace_values(x, c(0, -1, -99) ~ NA) # You'd have to nest `na_if()`s to achieve this try(na_if(x, c(0, -1, -99))) na_if(na_if(na_if(x, 0), -1), -99) # If you'd like to replace values that match a logical condition with `NA`, # use `replace_when()` replace_when(x, x < 0 ~ NA) # If you'd like to replace `NA` with some other value, use `replace_values()` x <- c(NA, 5, 2, NA, 0, 3) replace_values(x, NA ~ 0) # `na_if()` is particularly useful inside `mutate()` starwars |> select(name, eye_color) |> mutate(eye_color = na_if(eye_color, "unknown")) # `na_if()` can also be used with `mutate()` and `across()` # to alter multiple columns starwars |> mutate(across(where(is.character), ~na_if(., "unknown")))

near(x, y, tol = .Machine$double.eps^0.5)

sqrt(2) ^ 2 == 2 near(sqrt(2) ^ 2, 2)

nest_by(.data, ..., .key = "data", .keep = FALSE)

# After nesting, you get one row per group iris |> nest_by(Species) starwars |> nest_by(species) # The output is grouped by row, which makes modelling particularly easy models <- mtcars |> nest_by(cyl) |> mutate(model = list(lm(mpg ~ wt, data = data))) models models |> summarise(rsq = summary(model)$r.squared) if (requireNamespace("broom", quietly = TRUE)) withAutoprint(\ # examplesIf # This is particularly elegant with the broom functions models |> summarise(broom::glance(model)) models |> reframe(broom::tidy(model)) \) # examplesIf # Note that you can also `reframe()` to unnest the data models |> reframe(data)

nest_join(x, y, by = NULL, copy = FALSE, keep = NULL, name = NULL, ...) nest_joindata.frame( x, y, by = NULL, copy = FALSE, keep = NULL, name = NULL, ..., na_matches = c("na", "never"), unmatched = "drop" )

df1 <- tibble(x = 1:3) df2 <- tibble(x = c(2, 3, 3), y = c("a", "b", "c")) out <- nest_join(df1, df2) out out$df2

new_grouped_df(x, groups, ..., class = character()) validate_grouped_df(x, check_bounds = FALSE) new_rowwise_df(data, group_data = NULL, ..., class = character()) validate_rowwise_df(x)

# 5 bootstrap samples tbl <- new_grouped_df( tibble(x = rnorm(10)), groups = tibble(".rows" := replicate(5, sample(1:10, replace = TRUE), simplify = FALSE)) ) # mean of each bootstrap sample summarise(tbl, x = mean(x))

nth(x, n, order_by = NULL, default = NULL, na_rm = FALSE) first(x, order_by = NULL, default = NULL, na_rm = FALSE) last(x, order_by = NULL, default = NULL, na_rm = FALSE)

x <- 1:10 y <- 10:1 first(x) last(y) nth(x, 1) nth(x, 5) nth(x, -2) # `first()` and `last()` are often useful in `summarise()` df <- tibble(x = x, y = y) df |> summarise( across(x:y, first, .names = "col_first"), y_last = last(y) ) # Selecting a position that is out of bounds returns a default value nth(x, 11) nth(x, 0) # This out of bounds behavior also applies to empty vectors first(integer()) # You can customize the default value with `default` nth(x, 11, default = -1L) first(integer(), default = 0L) # `order_by` provides optional ordering last(x) last(x, order_by = y) # `na_rm` removes missing values before extracting the value z <- c(NA, NA, 1, 3, NA, 5, NA) first(z) first(z, na_rm = TRUE) last(z, na_rm = TRUE) nth(z, 3, na_rm = TRUE) # For data frames, these select entire rows df <- tibble(a = 1:5, b = 6:10) first(df) nth(df, 4)

ntile(x = row_number(), n)

x <- c(5, 1, 3, 2, 2, NA) ntile(x, 2) ntile(x, 4) # If the bucket sizes are uneven, the larger buckets come first ntile(1:8, 3) # Ties are ignored ntile(rep(1, 8), 3)

order_by(order_by, call)

order_by(10:1, cumsum(1:10)) x <- 10:1 y <- 1:10 order_by(x, cumsum(y)) df <- data.frame(year = 2000:2005, value = (0:5) ^ 2) scrambled <- df[sample(nrow(df)), ] wrong <- mutate(scrambled, running = cumsum(value)) arrange(wrong, year) right <- mutate(scrambled, running = order_by(year, cumsum(value))) arrange(right, year)

percent_rank(x) cume_dist(x)

x <- c(5, 1, 3, 2, 2) cume_dist(x) percent_rank(x) # You can understand what's going on by computing it by hand sapply(x, function(xi) sum(x <= xi) / length(x)) sapply(x, function(xi) sum(x < xi) / (length(x) - 1)) # The real computations are a little more complex in order to # correctly deal with missing values

pick(...)

df <- tibble( x = c(3, 2, 2, 2, 1), y = c(0, 2, 1, 1, 4), z1 = c("a", "a", "a", "b", "a"), z2 = c("c", "d", "d", "a", "c") ) df # `pick()` provides a way to select a subset of your columns using # tidyselect. It returns a data frame. df |> mutate(cols = pick(x, y)) # This is useful for functions that take data frames as inputs. # For example, you can compute a joint rank between `x` and `y`. df |> mutate(rank = dense_rank(pick(x, y))) # `pick()` is also useful as a bridge between data-masking functions (like # `mutate()` or `group_by()`) and functions with tidy-select behavior (like # `select()`). For example, you can use `pick()` to create a wrapper around # `group_by()` that takes a tidy-selection of columns to group on. For more # bridge patterns, see # https://rlang.r-lib.org/reference/topic-data-mask-programming.html#bridge-patterns. my_group_by <- function(data, cols) group_by(data, pick( cols )) df |> my_group_by(c(x, starts_with("z"))) # Or you can use it to dynamically select columns to `count()` by df |> count(pick(starts_with("z")))

progress_estimated(n, min_time = 0)

p <- progress_estimated(3) p$tick() p$tick() p$tick() p <- progress_estimated(3) for (i in 1:3) p$pause(0.1)$tick()$print() p <- progress_estimated(3) p$tick()$print()$ pause(1)$stop() # If min_time is set, progress bar not shown until that many # seconds have elapsed p <- progress_estimated(3, min_time = 3) for (i in 1:3) p$pause(0.1)$tick()$print() p <- progress_estimated(10, min_time = 3) for (i in 1:10) p$pause(0.5)$tick()$print()

pull(.data, var = -1, name = NULL, ...)

mtcars |> pull(-1) mtcars |> pull(1) mtcars |> pull(cyl) if (requireNamespace("dbplyr", quietly = TRUE) && requireNamespace("RSQLite", quietly = TRUE)) withAutoprint(\ # examplesIf # Also works for remote sources df <- dbplyr::memdb_frame(x = 1:10, y = 10:1, .name = "pull-ex") df |> mutate(z = x * y) |> pull() \) # examplesIf # Pull a named vector starwars |> pull(height, name)

recode(.x, ..., .default = NULL, .missing = NULL) recode_factor(.x, ..., .default = NULL, .missing = NULL, .ordered = FALSE)

set.seed(1234) x <- sample(c("a", "b", "c"), 10, replace = TRUE) # `recode()` is superseded by `recode_values()` and `replace_values()` # If you are fully recoding a vector use `recode_values()` recode(x, a = "Apple", b = "Banana", .default = NA_character_) recode_values(x, "a" ~ "Apple", "b" ~ "Banana") # With a default recode(x, a = "Apple", b = "Banana", .default = "unknown") recode_values(x, "a" ~ "Apple", "b" ~ "Banana", default = "unknown") # If you are partially updating a vector and want to retain the original # vector's values in locations you don't make a replacement, use # `replace_values()` recode(x, a = "Apple", b = "Banana") replace_values(x, "a" ~ "Apple", "b" ~ "Banana") # `replace_values()` is easier to use with numeric vectors, because you don't # need to turn the numeric values into names y <- c(1:4, NA) recode(y, `2` = 20L, `4` = 40L) replace_values(y, 2 ~ 20L, 4 ~ 40L) # `recode()` is particularly confusing because it tries to handle both # full recodings to new vector types and partial updating of an existing # vector. With the above example, using doubles (20) rather than integers # (20L) results in a warning from `recode()`, because it thinks you are # doing a full recode and missed a case. `replace_values()` is type stable # on `y` and will instead coerce the double values to integer. recode(y, `2` = 20, `4` = 40) replace_values(y, 2 ~ 20, 4 ~ 40) # This also makes `replace_values()` much safer. If you provide # incompatible types, it will error. recode(y, `2` = "20", `4` = "40") try(replace_values(y, 2 ~ "20", 4 ~ "40")) # If you were trying to fully recode the vector and want a different output # type, use `recode_values()` recode_values(y, 2 ~ "20", 4 ~ "40") # And if you want to ensure you don't miss a case, use `unmatched`, which # errors rather than warns try(recode_values(y, 2 ~ "20", 4 ~ "40", unmatched = "error")) # --------------------------------------------------------------------------- # Lookup tables # If you were splicing an external lookup vector into `recode()`, you can # instead use the `from` and `to` arguments of `recode_values()` x <- c("a", "b", "a", "c", "d", "c") lookup <- c( "a" = "A", "b" = "B", "c" = "C", "d" = "D" ) recode(x, !!!lookup) recode_values(x, from = names(lookup), to = unname(lookup)) # `recode_values()` is much more flexible here because the lookup table # isn't restricted to just character values. We recommend using `tribble()` # to build your lookup tables. lookup <- tribble( ~from, ~to, "a", 1, "b", 2, "c", 3, "d", 4 ) recode_values(x, from = lookup$from, to = lookup$to) # --------------------------------------------------------------------------- # Factors # The factor method of `recode()` can generally be replaced with # `forcats::fct_recode()` x <- factor(c("a", "b", "c")) recode(x, a = "Apple") # forcats::fct_recode(x, "Apple" = "a") # `recode_factor()` does not currently have a direct replacement, but we # plan to add one to forcats. In the meantime, use a lookup table that # recodes every case, and then convert the `to` column to a factor. If you # define your lookup table in your preferred level order, then the conversion # to factor is straightforward! y <- c(3, 4, 1, 2, 4, NA) recode_factor( y, `1` = "a", `2` = "b", `3` = "c", `4` = "d", .missing = "M" ) lookup <- tribble( ~from, ~to, 1, "a", 2, "b", 3, "c", 4, "d", NA, "M" ) # `factor()` generates levels by sorting the unique values of `to`, which we # don't want, so we supply `levels = to` directly. Alternatively, use # `forcats::fct(to)`, which generates levels in order of appearance. lookup <- mutate(lookup, to = factor(to, levels = to)) recode_values(y, from = lookup$from, to = lookup$to)