Modern tidyverse R style

Contract

Enforces the modern-tidyverse form of R. Apply to every R snippet, function, or script you write. Each rule below overrides a base-R or legacy-tidyverse default that the base model reaches for by reflex; emit the conforming form instead.

Rules

1. Assignment — use <-. Reserve = strictly for passing function

arguments (mean(x, na.rm = TRUE)). Never assign a top-level object with =.

1. Pipe — use the native |>. Never use the magrittr %>%, and do not

library(magrittr) to get it.

1. Grouped summaries — compute per-group statistics with the .by =

argument inside summarise() or mutate(). Never write group_by() + summarise() + ungroup(). Multiple keys go in .by = c(a, b).

1. Embracing column arguments — when a function takes a bare (unquoted)

column name and forwards it to dplyr, embrace it with {{ col }}. Never pass the column as a string, and never use substitute(), deparse(), df[[col]], eval(), or aes_string().

1. Iteration — use type-stable purrr: map_dbl(), map_chr(),

map_lgl(), map_int(). Never use sapply() or vapply(), and never bare map() when the output type is known. Use bare map() only when each result is itself a list/data frame.

1. Errors — raise with cli::cli_abort(). Never stop(). Pass a character

vector c(...): the FIRST element states the problem, the remaining elements are NAMED bullets — x = for the failure detail, i = for a hint/fix. Use inline markup: {.arg name} (argument), {.fn name} (function), {.cls {class(x)}} (class), {.val {x}} (value), {?s} (pluralise).

1. File I/O — read and write CSVs with readr read_csv() / write_csv().

Never base read.csv() / write.csv().

1. Strings — use stringr: str_to_lower(), str_to_upper(),

str_detect(), str_replace_all(), str_remove_all(), str_extract(), str_trim(), str_squish(). Never base tolower(), toupper(), grepl(), gsub(), sub(), regmatches(), trimws(), substr() for these jobs.

1. Logicals — spell TRUE / FALSE in full. Never T / F (they are

reassignable variables, not constants).

1. Optional arguments — default optional filter bounds and flags to NULL

and guard with if (!is.null(x)). Never default a bound to NA, -Inf, Inf, or a sentinel number.

1. Function signatures — put the primary data frame FIRST so calls pipe

cleanly (data |> f(...)). Prefix optional/meta arguments with . (.by, .data) to avoid clashing with columns captured by ....

1. Names — snake_case for variables and functions; functions are verbs

(calculate_mean), variables are nouns (user_data); no dots in names except S3 methods (print.myclass).

1. Indentation — 2 spaces, never tabs. One argument per line for long

calls; one verb per line in a pipe chain.

Worked examples

Each pair shows the base model's wrong default (BEFORE) and the conforming form (AFTER).

Rule 1 — assignment

r
# BEFORE
total = sum(x)
# AFTER
total <- sum(x)

Rule 2 — native pipe

r
# BEFORE
sales %>% filter(region == "west") %>% summarise(n = n())
# AFTER
sales |> filter(region == "west") |> summarise(n = n())

Rule 3 — .by grouping

r
# BEFORE
sales |>
  group_by(region) |>
  summarise(avg = mean(revenue)) |>
  ungroup()
# AFTER
sales |>
  summarise(avg = mean(revenue), .by = region)

Rule 4 — embracing

r
# BEFORE
filter_above <- function(data, column, threshold) {
  data[data[[column]] > threshold, ]
}
# AFTER
filter_above <- function(data, column, threshold) {
  data |> filter({{ column }} > threshold)
}

Rule 5 — type-stable iteration

r
# BEFORE
r2 <- sapply(models, function(m) summary(m)$r.squared)
# AFTER
r2 <- map_dbl(models, \(m) summary(m)$r.squared)

Rule 6 — cli errors

r
# BEFORE
validate_input <- function(x) {
  if (!is.numeric(x)) stop("x must be numeric, not ", typeof(x))
}
# AFTER
validate_input <- function(x) {
  if (!is.numeric(x)) {
    cli::cli_abort(c(
      "{.arg x} must be numeric.",
      x = "You supplied {.cls {class(x)}}.",
      i = "Convert with {.fn as.numeric} first."
    ))
  }
}

Rule 7 — readr I/O

r
# BEFORE
df <- read.csv("data/input.csv")
write.csv(out, "data/output.csv")
# AFTER
df <- read_csv("data/input.csv")
write_csv(out, "data/output.csv")

Rule 8 — stringr

r
# BEFORE
people$name <- trimws(tolower(people$name))
df <- df[grepl("@stanford.edu", df$email), ]
# AFTER
people |> mutate(name = str_trim(str_to_lower(name)))
df |> filter(str_detect(email, "@stanford.edu"))

Rule 9 — full logicals

r
# BEFORE
read_csv(path, show_col_types = F)
# AFTER
read_csv(path, show_col_types = FALSE)

Rule 10 — NULL-guarded options

r
# BEFORE
range_filter <- function(df, min_value = -Inf, max_value = Inf) {
  df |> filter(value >= min_value, value <= max_value)
}
# AFTER
range_filter <- function(df, min_value = NULL, max_value = NULL) {
  if (!is.null(min_value)) df <- df |> filter(value >= min_value)
  if (!is.null(max_value)) df <- df |> filter(value <= max_value)
  df
}

Rule 11 — data-first signature

r
# BEFORE
my_transform <- function(threshold, data) { ... }
# AFTER
my_transform <- function(data, threshold = 0.5) { ... }

Rule 12 — names

r
# BEFORE
CalculateMean <- function(DataFrame) { ... }   # camel/Pascal, noun verb
# AFTER
calculate_mean <- function(data) { ... }       # snake_case, verb

Edge cases & exceptions

• = is correct inside calls. summarise(avg = mean(x)) and

f(na.rm = TRUE) keep = — the <- rule is only for object assignment.

• Bare map() is correct when each element is a list/data frame/model

(map(paths, read_csv) returns a list of tibbles). Only switch to map_*() when the per-element result is a single atomic value.

• Single grouping key needs no c(). .by = region, but

.by = c(store, month) for two or more.

• %>% is acceptable only if the code must run on R < 4.1 (no native pipe).

Assume a modern R; emit |>.

• Dots in names are allowed for S3 methods (summary.lm, print.tbl) and

for the conventional tidyverse meta-args (.by, .data, .before). Do not use dots as a word separator elsewhere.

• cli::cli_abort() first element is unnamed (the headline); only the

follow-up bullets are named x = / i = / !=. Putting a name on the first element silently turns it into a bullet with no headline.

• Early return() is fine for guard clauses (if (is.null(x)) return(NULL));

prefer implicit return of the last expression for the normal path.

Do / Don't

• Never library(magrittr) for %>%; always use the built-in |>.
• Never group_by() |> ... |> ungroup(); always .by = inside the verb.
• Never df[[col]] / a string column; always embrace with {{ col }}.
• Never sapply(); always the typed map_dbl/chr/lgl/int().
• Never stop("..."); always cli::cli_abort(c(headline, x = ..., i = ...)).
• Never read.csv()/write.csv(); always read_csv()/write_csv().
• Never tolower()/grepl()/gsub()/trimws(); always the str_*() form.
• Never T/F; always TRUE/FALSE.
• Never default a bound to NA/Inf; always NULL + if (!is.null()).
• Never put the data frame after other args; always data-first.

Common mistakes

• Reaching for %>% out of habit — it is the single most common base default.
• Writing the group_by() + summarise() + ungroup() triple instead of .by =.
• Accepting a column name as a string and indexing with [[ ]], instead of

embracing the bare name with {{ }}.

• Using sapply() (whose return type is unpredictable) instead of map_dbl().
• Calling stop() with paste()-style string concatenation rather than a

structured cli::cli_abort() bullet list.

• Mixing base string/IO functions (gsub, read.csv) into otherwise-tidy code.
• Abbreviating TRUE/FALSE to T/F.
• Defaulting optional bounds to -Inf/Inf/NA instead of NULL.

Quick checklist

<- not = · |> not %>% · .by = not group_by() · {{ }} not strings · map_dbl/chr/lgl/int() not sapply() · cli::cli_abort(c(...)) not stop() · read_csv/write_csv not base · str_*() not base · TRUE/FALSE not T/F · NULL + if (!is.null()) for options · data-first signature · snake_case · 2-space indent.