Tidyverse Style Guide

https://style.tidyverse.org/
Admin
The Tidyverse style guide provides consistent coding practices for R, aiming to make code easier to...
Tokens:20,701
Snippets:103
Trust Score:9.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### R: NEWS File - Breaking Changes Example

Source: https://style.tidyverse.org/news

Provides an example of how to document breaking API changes in an R package's NEWS file. Each entry details the change, its symptoms, and the necessary fix, often including version conditions.

```R
## Breaking changes

* `separate()` now correctly uses -1 to refer to the far right position,
  instead of -2. If you depended on this behaviour, you'll need to condition
  on `packageVersion("tidyr") > "0.7.2"`.
```

--------------------------------

### R Error Hinting Examples

Source: https://style.tidyverse.org/errors

Illustrates how to provide helpful hints for R errors, guiding users towards potential solutions. This includes suggesting correct syntax or identifying common mistakes.

```R
dplyr::filter(iris, Species = "setosa")
#> Error:
#> ! Filter specifications must be named.
#> ℹ Did you mean `Species == "setosa"`?
```

```R
ggplot2::ggplot(ggplot2::aes())
#> Error:
#> ! Can't plot data with class "uneval".
#> ℹ Did you accidentally provide the results of aes() to the `data` argument?
```

```R
mtcars |> ggplot() |> geom_point()
#> Error in `validate_mapping()`:
#> ! `mapping` must be created by `aes()`.
#> ℹ Did you use `%>%` or `|>` instead of `+`?
```

```R
mean[[1]]
#> Error:
#> ! Can't subset a function.
```

```R
mean[[1]]
#> Error:
#> ! Can't subset a function.
#> ℹ Have you forgotten to define a variable named `mean`?
```

--------------------------------

### R Package NEWS.md Entry Examples

Source: https://style.tidyverse.org/news

Illustrates how to format entries in a package's NEWS.md file, including referencing issues and contributors, and adhering to style guidelines for clarity and conciseness.

```Markdown
# haven (development version)

* Second update.
* First update.
```

```Markdown
# Good
* `ggsave()` now uses full argument names to avoid partial match warnings (@wch, #2355).

# Bad
* `ggsave()` now uses full argument names to avoid partial match warnings.

* `ggsave()` now uses full argument names to avoid partial match warnings. (@wch, #2355)
```

```Markdown
# Good
* `ggsave()` now uses full argument names to avoid partial match warning (#2355).

# Bad
* Fixed partial argument matches in `ggsave()` (#2355).
```

```Markdown
# Good
* `ggsave()` now uses full argument names to avoid partial match warnings (#2355).

# Bad
* `ggsave()` no longer partially matches argument names (#2355).
```

```Markdown
# Good
* In `stat_bin()`, `binwidth` now also takes functions.
```

--------------------------------

### R Error Message Examples with cli::cli_abort()

Source: https://style.tidyverse.org/errors

Demonstrates how to use cli::cli_abort() to generate informative error messages in R. It shows examples of specifying expected vs. actual types/lengths and handling cases where the expected value cannot be determined.

```R
dplyr::nth(1:10, "x")
#> Error:
#> ! `n` must be a numeric vector, not a character vector.

dplyr::nth(1:10, 1:2)
#> Error:
#> ! `n` must have length 1, not length 2.
```

```R
mtcars |> pull(b)
#> Error:
#> ! Can't find column `b` in `.data`.

as_vector(environment())
#> Error:
#> ! Can't coerce `.x` to a vector.

purrr::modify_depth(list(list(x = 1)), 3, ~ . + 1)
#> Error:
#> ! Can't find specified `.depth` in `.x`.
```

--------------------------------

### R: NEWS File Structure - Basic Release

Source: https://style.tidyverse.org/news

Example of a basic NEWS file structure for an R package release, including a level 1 heading with package name and version, followed by a list of changes.

```R
# modelr 0.1.2

* `data_grid()` no longer fails with modern tidyr (#58).

* New `mape()` and `rsae()` model quality statistics (@paulponcet, #33).

* `rsquare()` use more robust calculation 1 - SS_res / SS_tot rather
  than SS_reg / SS_tot (#37).

* `typical()` gains `ordered` and `integer` methods (@jrnold, #44), 
  and `...` argument (@jrnold, #42).
```

--------------------------------

### R: NEWS File - Common Patterns: New Function

Source: https://style.tidyverse.org/news

Shows examples of documenting new functions in an R package's NEWS file, including `position_dodge2()` for enhanced dodging and `stat_qq_line()` for adding Q-Q plot lines.

```R
* New `position_dodge2()` provides enhanced dogding for boxplots...

* New `stat_qq_line()` makes it easy to add a simple line to a Q-Q plot.
  This line makes it easier to judge the fit of the theoretical distribution
  (@nicksolomon).
```

--------------------------------

### Format Long Function Calls in R

Source: https://style.tidyverse.org/syntax

Demonstrates the correct and incorrect ways to format long function calls in R according to the Tidyverse style guide. The 'Good' example shows proper line breaks for readability, while the 'Bad' example illustrates a less readable format.

```R
# Good
do_something_very_complicated(
  something = "that",
  requires = many,
  arguments = "some of which may be long"
)

# Bad
do_something_very_complicated("that", requires, many, arguments,
                              "some of which may be long"
                              )
```

--------------------------------

### tibble tribble error example

Source: https://style.tidyverse.org/errors

Illustrates an error in tibble::tribble when column names are not supplied, and presents the correct syntax.

```R
tibble::tribble("x", "y")
#> BEFORE: ! Expected at least one column name; e.g. `~name`
#>  AFTER: ! Must supply at least one column name, e.g. `~name`.
```

--------------------------------

### Cross-linking Related Functions in R Documentation

Source: https://style.tidyverse.org/documentation

Demonstrates how to use `@seealso` to link to related R functions. It shows examples for linking a single function and a bulleted list of multiple functions, emphasizing clarity and context for external resources.

```R
#' @seealso [fct_lump()] to automatically convert the rarest (or most common)
#'   levels to "other".
```

```R
#' @seealso
#' * [tibble()] constructs from individual columns.
#' * [enframe()] converts a named vector into a two-column tibble (names and
#'   values).
#' * [name-repair] documents the details of name repair.
```

--------------------------------

### Roxygen Parameter Documentation Style

Source: https://style.tidyverse.org/documentation

Defines the standard style for documenting parameters using roxygen tags like '@param'. It specifies that the description should be a sentence, starting with a capital letter and ending with a period.

```R
#' @param key The bare (unquoted) name of the column whose values will be used
#'   as column headings.
```

--------------------------------

### R Commenting Best Practices

Source: https://style.tidyverse.org/syntax

Provides guidance on writing effective comments in R code. It emphasizes starting each comment line with `# ` and using comments to explain findings or decisions, rather than basic code operations. Suggests R Markdown for extensive explanations.

```R
# Each line of a comment should begin with the comment symbol and a single space: #
# In data analysis code, use comments to record important findings and analysis decisions.
# If you need comments to explain what your code is doing, consider rewriting your code to be clearer.
# If you discover that you have more comments than code, consider switching to [R Markdown](https://rmarkdown.rstudio.org/).
```

--------------------------------

### Roxygen Indentation for Multi-line Tags (Examples, Description, Section)

Source: https://style.tidyverse.org/documentation

Illustrates an alternative indentation style for roxygen tags like '@examples', '@description', and '@section' that span multiple lines. In this style, the tag can be on its own line, and subsequent lines do not require extra indentation.

```R
#' @examples
#' 1 + 1
#' sin(pi)
```

--------------------------------

### Pull Request Best Practices

Source: https://style.tidyverse.org/git

Recommendations for creating clear and informative pull request titles and descriptions, including issue linking.

```APIDOC
Pull Request Format:
  Title: Briefly describe the changes. Should be standalone, do not include issue numbers.
  Description: For simple changes, can be left blank. For complex changes, provide an overview. Include 'Fixes #<issue-number>' in the description if the PR addresses an issue.
```

--------------------------------

### R Package File Organization: Bad Example

Source: https://style.tidyverse.org/package-files

Demonstrates an incorrect way to organize functions in an R package file. A private function is placed before a public function and its documentation.

```R
# Bad
help_compute <- function() {
  # ... Lots of code ...
}

#' My public function
#'
#' This is where the documentation of my function begins.
#' ...
#' @export
do_something_cool <- function() {
  # ... even more code ...
  help_compute()
}
```

--------------------------------

### Internal Script Structure (R)

Source: https://style.tidyverse.org/files

Illustrates how to use commented lines to break R scripts into readable chunks and the best practice for loading packages.

```R
# Load data ---------------------------


# Plot data ---------------------------
```

--------------------------------

### R Loops: For, While, Repeat Syntax

Source: https://style.tidyverse.org/syntax

Demonstrates the correct syntax for R's looping constructs: for, while, and repeat. Emphasizes the requirement for braced expressions for loop bodies and provides examples of good and bad practices.

```R
for (i in seq) {
  x[i] <- x[i] + 1
}

while (waiting_for_something()) {
  cat("Still waiting...")
}
```

```R
# Bad examples:
# for (i in seq) x[i] <- x[i] + 1
# while (waiting_for_something()) cat("Still waiting...")
```

--------------------------------

### R: Infix Operator Spacing

Source: https://style.tidyverse.org/syntax

Illustrates the standard practice of surrounding most infix operators in R with spaces for improved readability. Includes examples of correct and incorrect spacing.

```R
height <- (feet * 12) + inches
mean(x, na.rm = TRUE)
```

--------------------------------

### Package Name Formatting in R Documentation

Source: https://style.tidyverse.org/documentation

Details the correct way to reference package names in R documentation. It advises against using code font and suggests disambiguating with 'package' or curly braces `{}` when necessary, and maintaining sentence case for package names at the start of a sentence.

```R
Use the glue package to flexibly interpolate values into strings.
Use {glue} to flexibly interpolate values into strings.
```

```R
dplyr provides a grammar of data manipulation, providing a consistent set of verbs that help you solve the most common data manipulation challenges.
```

--------------------------------

### R Package File Organization: Good Example

Source: https://style.tidyverse.org/package-files

Illustrates the recommended way to organize functions in an R package file. Public functions with shared documentation are grouped together after the documentation block, followed by private functions.

```R
# Good
#' Lots of functions for doing something cool
#'
#' ... Complete documentation ...
#' @name something-cool
NULL

#' @describeIn something-cool Get the mean
#' @export
get_cool_mean <- function(x) {
  # ...
}

#' @describeIn something-cool Get the sum
#' @export
get_cool_sum <- function(x) {
  # ...
}
```

--------------------------------

### R Code Styling and Linting Tools

Source: https://style.tidyverse.org/index

This snippet details two R packages that support the Tidyverse style guide. 'styler' helps in restyling code, offering an RStudio add-in for easy application. 'lintr' automates style checks to ensure adherence to the guide's conventions.

```R
styler::style_text("x <- 1 + 2")
# or use the RStudio add-in

lintr::lint("my_script.R")
```

--------------------------------

### Roxygen Formatting for Sections with Line Breaks

Source: https://style.tidyverse.org/documentation

Shows how to format roxygen documentation for sections, including the use of line breaks before and after section titles. This example demonstrates documenting a 'Tidy data' section and a 'Scoped filtering' section, with explanations and references to other functions.

```R
#' @section Tidy data:
#' When applied to a data frame, row names are silently dropped. To preserve,
#' convert to an explicit variable with [tibble::rownames_to_column()].
```

```R
#' @section Scoped filtering:
#' The three [scoped] variants ([filter_all()], [filter_if()] and
#' [filter_at()]) make it easy to apply a filtering condition to a
#' selection of variables.
```

--------------------------------

### dplyr arrange error example

Source: https://style.tidyverse.org/errors

Demonstrates an error in dplyr::arrange when attempting to sort by a non-existent column, and provides the correct usage.

```R
dplyr::arrange(mtcars, xxx)
#> BEFORE: ! Evaluation error: object 'xxx' not found.
#>  AFTER: ! Can't find column `xxx` in `.data`.
```

--------------------------------

### R: Help Operator Spacing

Source: https://style.tidyverse.org/syntax

Illustrates the correct usage of the R help operator `?` and `package?`, which should not be surrounded by spaces when accessing documentation.

```R
package?stats
?mean
```

--------------------------------

### Formatting Multiple Unnamed Arguments in R

Source: https://style.tidyverse.org/syntax

Shows how to format function calls in R when multiple unnamed arguments are closely related, such as in string concatenation with `paste0`. The 'Good' example aligns one line of code with one line of output for clarity.

```R
# Good
paste0(
  "Requirement: ", requires, "\n",
  "Result: ", result, "\n"
)

# Bad
paste0(
  "Requirement: ", requires,
  "\n", "Result: ",
  result, "\n")
```

--------------------------------

### R: NEWS File Structure - ggplot2 Example

Source: https://style.tidyverse.org/news

Shows a detailed NEWS file structure for a large R package (ggplot2), utilizing multiple levels of headings to categorize changes within 'New features' and 'Minor bug fixes and improvements'.

```R
# ggplot 2.3.0
## Breaking changes
## New features
### Tidy evaluation
### sf
### Layers: geoms, stats, and position adjustments
### Scales and guides
### Margins
## Extension points
## Minor bug fixes and improvements
### Facetting
### Scales
### Layers
### Coords
### Themes
### Guides
### Other
```

--------------------------------

### R: NEWS File - Common Patterns: New Argument

Source: https://style.tidyverse.org/news

Demonstrates how to document the addition of a new argument to an existing function in an R package's NEWS file, using `geom_segment()` gaining a `linejoin` parameter as an example.

```R
* `geom_segment()` gains a `linejoin` parameter.
```

--------------------------------

### R: Embracing Operator Spacing

Source: https://style.tidyverse.org/syntax

Demonstrates the correct usage of inner spaces around the embracing operator `{}` in R functions to emphasize its special behavior. Contrasts good and bad examples.

```R
max_by <- function(data, var, by) {
  data |> 
    group_by({{ by }}) |> 
    summarise(maximum = max({{ var }}, na.rm = TRUE))
}
```

--------------------------------

### R Syntax: Assignment, Data, and Comments

Source: https://style.tidyverse.org/syntax

This part of the Tidyverse style guide focuses on assignment operators, the representation of data (character and logical vectors), and the conventions for writing comments in R code. It promotes clarity and maintainability through consistent commenting and data handling.

```R
# Tidyverse Style Guide - Syntax

# 2.8 Assignment
# Use the "left-assignment" operator (<-).

# 2.9 Data
# Use "" for character strings.
# Use TRUE and FALSE for logical values.

# 2.10 Comments
# Use # for comments.
# Write comments that explain the 'why', not the 'what'.
```

--------------------------------

### dplyr rename error example

Source: https://style.tidyverse.org/errors

Highlights an error in dplyr::rename when the target column name does not exist, and shows the correct way to rename columns.

```R
dplyr::rename(mtcars, cyl = xxx)
#> BEFORE: ! `xxx` contains unknown variables
#>  AFTER: ! Can't find column `xxx` in `.data`.
```

--------------------------------

### R: Formatting Short Pipes

Source: https://style.tidyverse.org/pipes

Illustrates how to format short pipe operations in R. While single-line pipes are acceptable, the guide recommends the multi-line format for consistency and future scalability.

```R
iris |> 
  subset(Species == "virginica") |>
  _$Sepal.Length
```

```R
iris |> 
  summarise(width = Sepal.Width, .by = Species) |>
  arrange(width)
```

--------------------------------

### R Error Message Examples

Source: https://style.tidyverse.org/errors

Demonstrates common error messages encountered in R, such as incompatible lengths for vectors and the presence of NA values. It also shows how to format error messages for clarity.

```R
#> ! `.x` and `.y` must have compatible lengths: `.x` has length 4 and
#> `.y` has length 2
```

```R
#> Error: NAs found at 1,000,000 locations: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ...
```

--------------------------------

### R: NEWS File - Common Patterns: Function Changes Behaviour

Source: https://style.tidyverse.org/news

Shows examples of documenting changes in function behavior in an R package's NEWS file, including how `map()` and `modify()` now work with calls and pairlists, and error handling for `flatten_dfr()` and `flatten_dfc()`.

```R
* `map()` and `modify()` now work with calls and pairlists (#412).

* `flatten_dfr()` and `flatten_dfc()` now aborts with informative
   message if dplyr is not installed (#454).

* `reduce()` now throws an error if `.x` is empty and `.init` is not
  supplied.
```

--------------------------------

### File Naming Conventions (R)

Source: https://style.tidyverse.org/files

Demonstrates good and bad practices for naming R files to ensure machine readability, human readability, and proper sorting.

```R
# Good
fit_models.R
utility_functions.R
exploratory-data-analysis.R

# Bad
fit models.R
foo.r
ExploratoryDataAnaylsis.r
```

```R
# good
report-draft-notes.txt

# bad
temp.r
```

```R
# good
fig-eda.png
fig-model-3.png

# bad
figure eda.PNG
fig model three.png
```

```R
# good
01-load-data.R
02-exploratory-analysis.R
03-model-approach-1.R
04-model-approach-2.R
2025-01-01-report.Rmd
2025-02-01.report.Rmd

# bad
alternative model.R
code for exploratory analysis.r
feb 01 report.Rmd
jan 01 report.Rmd
model_first_try.R
run-first.r
```

```R
# good
report-2022-03-20.qmd
report-2022-04-02.qmd

# bad
finalreport.qmd
FinalReport-2.qmd
```

--------------------------------

### R Syntax: Object Names and Spacing

Source: https://style.tidyverse.org/syntax

This section of the Tidyverse style guide outlines best practices for naming R objects and managing spacing within code for improved readability. It covers conventions for variable, function, and file names, as well as rules for spaces around operators, commas, and parentheses.

```R
# Tidyverse Style Guide - Syntax

# 2.1 Object names
# Use snake_case for all objects.
# Avoid abbreviations.

# 2.2 Spacing
# Use spaces around all operators (except for assignment).
# Use spaces after commas.
# Do not use spaces inside parentheses.
# Use spaces around infix operators.
# Avoid extra spaces at the end of lines.
```

--------------------------------

### Git Commit Message Best Practices

Source: https://style.tidyverse.org/git

Guidelines for crafting effective Git commit messages, including subject line length, body content, and issue referencing.

```APIDOC
Commit Message Format:
  Subject: Summarize changes in under 50 characters. Use sentence case, no trailing period.
  Body: Add a blank line after the subject, then provide detailed explanation and context.
  Issue Fix: Include 'Fixes #<issue-number>' to automatically close GitHub issues upon merge.
```

--------------------------------

### R Base Pipe vs. Magrittr Pipe

Source: https://style.tidyverse.org/pipes

Compares the usage of the base R pipe (|>) with the magrittr pipe (%>%), recommending the base pipe for its comprehensive features available since R 4.3.0.

```R
# Good
iris |>
  summarise(width = Sepal.Width, .by = Species) |>
  arrange(width)
```

```R
# Bad
iris %>% 
  summarise(width = Sepal.Width, .by = Species) %>% 
  arrange(width)
```

--------------------------------

### R Quoting Conventions for Character Vectors

Source: https://style.tidyverse.org/syntax

Demonstrates the preferred use of double quotes (`"`) for character strings in R. It shows examples of correct usage, including strings with internal double quotes, and incorrect usage of single quotes.

```R
# Good
"Text"
'Text with "quotes"'
'<a href="http://style.tidyverse.org">A link</a>'

# Bad
'Text'
'Text with "double" and 'single' quotes'
```

--------------------------------

### R: Early Return with return()

Source: https://style.tidyverse.org/functions

Demonstrates the correct usage of return() for early exits in R functions. It shows how to return a value when a condition is met, and otherwise let the last expression be the return value.

```R
find_abs <- function(x) {
  if (x > 0) {
    return(x)
  }
  x * -1
}
add_two <- function(x, y) {
  x + y
}
```

--------------------------------

### R Comments: Good vs. Bad

Source: https://style.tidyverse.org/functions

Demonstrates the correct and incorrect ways to write comments in R code according to the Tidyverse style guide. Good comments explain the purpose, while bad comments are redundant or unclear.

```R
# Good
# Objects like data frames are treated as leaves
x <- map_if(x, is_bare_list, recurse)
```

```R
# Bad
# Recurse only with bare lists
x <- map_if(x, is_bare_list, recurse)
```

--------------------------------

### R: NEWS File - Common Patterns: Argument Changes Behaviour

Source: https://style.tidyverse.org/news

Provides an example of documenting changes in function argument behavior within an R package's NEWS file, illustrating how `col = -1` in `separate()` now correctly refers to the far-right position.

```R
* In `separate()`, `col = -1` now refers to the far right position.
  Previously, and incorrectly, `col = -2` referred to the far-right
  position.
```

--------------------------------

### R Empty Braced Expressions - Good Practice

Source: https://style.tidyverse.org/syntax

Shows the correct way to write empty braced expressions in R according to the tidyverse style guide, with no intervening space.

```R
function(...) {}
```

--------------------------------

### R Error Message Formatting: Singular vs. Plural

Source: https://style.tidyverse.org/errors

Demonstrates the preferred style for R error messages, emphasizing singular problem statements and correct coercibility to integers. Includes examples of 'Good' and 'Bad' error message phrasing.

```R
# Good
map_int(1:2, ~ "a")
#> Error:
#> ! Each result must be coercible to a single integer.
#> ✖ Result 1 is a character vector.

# Bad
map_int(1:2, ~ "a")
#> Error:
#> ! Results must be coercible to single integers.
#> ✖ Result 1 is a character vector.
```

--------------------------------

### R Pipe Syntax and Placeholder Usage

Source: https://style.tidyverse.org/pipes

Demonstrates the standard R pipe operator `|>` for chaining functions and the use of the `_` placeholder with `gsub` for compatibility with older functions.

```R
strings |>
  str_replace("a", "b") |>
  str_replace("x", "y")

strings |>
  gsub("a", "b", x = _) |>
  gsub("x", "y", x = _)
```

--------------------------------

### R Function Naming Conventions

Source: https://style.tidyverse.org/functions

Follow general object naming advice and use verbs for function names. This promotes clarity and readability in R code.

```R
# Good
add_row()
permute()

# Bad
row_adder()
permutation()
```

--------------------------------

### R Error Message Formatting: Multiple Problems

Source: https://style.tidyverse.org/errors

Illustrates how to handle multiple errors in R by listing up to five distinct issues. This approach helps users address several problems efficiently without being overwhelmed. The example shows a case where multiple results are character vectors.

```R
# BETTER
map_int(1:10, ~ "a")
#> Error:
#> ! Each result must be coercible to a single integer.
#> ✖ Result 1 is a character vector
#> ✖ Result 2 is a character vector
#> ✖ Result 3 is a character vector
#> ✖ Result 4 is a character vector
#> ✖ Result 5 is a character vector
#> ... and 5 more problems
```

--------------------------------

### R Syntax: Vertical Space and Function Calls

Source: https://style.tidyverse.org/syntax

This guide covers the use of vertical space and the formatting of function calls in R according to Tidyverse conventions. It addresses spacing around braces, control flow statements, and best practices for long function calls and named arguments.

```R
# Tidyverse Style Guide - Syntax

# 2.3 Vertical space
# Use vertical space to separate logical blocks of code.

# 2.4 Function calls
# Place each argument on a new line if it makes the call longer than one line.
# Align arguments vertically.
# Use named arguments for clarity.
# Avoid long function calls by breaking them up.
```

--------------------------------

### R: Incorrect Return Statement Placement

Source: https://style.tidyverse.org/functions

Shows the incorrect way to write return statements in R by placing them on the same line as other code, which can obscure control flow and is discouraged by style guides.

```R
find_abs <- function(x) {
  if (x > 0) return(x)
  x * -1
}
```

--------------------------------

### R Pipe Whitespace and Indentation

Source: https://style.tidyverse.org/pipes

Illustrates correct whitespace and indentation for R pipes, emphasizing spaces before `|>` and new lines for readability, contrasting with incorrect formatting.

```R
# Good
iris |>
  summarize(across(where(is.numeric), mean), .by = Species) |>
  pivot_longer(!Species, names_to = "measure", values_to = "value") |>
  arrange(value)

# Bad
iris |> summarize(across(where(is.numeric), mean), .by = Species) |
pivot_longer(!Species, names_to = "measure", values_to = "value") |
arrange(value)
```

--------------------------------

### Roxygen Parameter Inheritance

Source: https://style.tidyverse.org/documentation

Demonstrates the use of the '@inheritParams' tag in roxygen for avoiding content duplication when multiple functions share the same parameters. This tag allows referencing the parameter documentation from another function.

```R
#' @inheritParams function_to_inherit_from
```

--------------------------------

### R: Formatting Long Pipes

Source: https://style.tidyverse.org/pipes

Demonstrates the recommended way to format long pipe operations in R, where each argument to a function is placed on its own line with proper indentation.

```R
iris |> 
  summarise(
    Sepal.Length = mean(Sepal.Length),
    Sepal.Width = mean(Sepal.Width),
    .by = Species
  )
```

--------------------------------

### R Switch Statement Syntax

Source: https://style.tidyverse.org/syntax

Illustrates the preferred style for R switch statements, emphasizing named elements, one element per line, and proper fall-through handling with error messages.

```R
# Good
switch(x,
  a = ,
  b = 1,
  c = 2,
  stop("Unknown `x`", call. = FALSE)
)

# Bad
switch(x,
  a =,
  b = 1,
  c = 2
)
switch(x,
  a = long_function_name1(), b = long_function_name2(),
  c = long_function_name2()
)
switch(y, 1, 2, 3)
```

--------------------------------

### R Empty Braced Expressions - Bad Practices

Source: https://style.tidyverse.org/syntax

Demonstrates incorrect ways to write empty braced expressions in R, including unnecessary spaces or newlines.

```R
function(...) { }
function(...) {

}
```

--------------------------------

### Roxygen Indentation for Multi-line Parameters

Source: https://style.tidyverse.org/documentation

Demonstrates the correct indentation for multi-line roxygen tag descriptions, specifically for the '@param' tag. It shows that subsequent lines of a parameter description should be indented with two extra spaces.

```R
#' @param key The bare (unquoted) name of the column whose values will be used
#'   as column headings.
```

--------------------------------

### R: Aligning Operators with Extra Spaces

Source: https://style.tidyverse.org/syntax

Demonstrates the use of extra spaces to align assignment operators (`=`, `<-`) in R code for improved readability. This is considered good practice when it enhances alignment.

```R
list(
  total = a + b + c,
  mean  = (a + b + c) / n
)
```

```R
list(
  total = a + b + c,
  mean = (a + b + c) / n
)
```

--------------------------------

### R Anonymous Function Syntax

Source: https://style.tidyverse.org/functions

Use the lambda syntax `\(x) x + 1` for short, anonymous functions. Avoid the tilde `~` syntax and `\()` for multi-line or named functions.

```R
# Good
map(xs, \(x) mean((x + 5)^2))
map(xs, function(x) mean((x + 5)^2))

# Bad
map(xs, ~ mean((.x + 5)^2))
```

```R
# Good
map(xs, function(x) {
  mean((x + 5)^2)
})

# Bad
map(xs, \(x) {
  mean((x + 5)^2)
})
```

```R
# Good
cv <- function(x) {
  sd(x) / mean(x)
}

# Bad
cv <- \(x) sd(x) / mean(x)
```

--------------------------------

### R Braced Expressions - Bad Practices

Source: https://style.tidyverse.org/syntax

Illustrates incorrect usage of braced expressions in R that violate tidyverse style guidelines, such as incorrect brace placement and inconsistent indentation.

```R
if (y < 0 && debug) {
message("Y is negative")
}

if (y == 0)
{
    if (x > 0) {
      log(x)
    } else {
  message("x is negative or zero")
    }
} else { y ^ x }
```

--------------------------------

### ggplot2 geom_line error example

Source: https://style.tidyverse.org/errors

Shows an error in ggplot2::geom_line when the 'y' aesthetic is missing, and provides the corrected code.

```R
ggplot2::ggplot(data = diamonds) + ggplot2::geom_line(ggplot2::aes(x = cut))
#> BEFORE: ! geom_line requires the following missing aesthetics: y
#>  AFTER: ! `geom_line()` must have the following aesthetics: `y`.
```

--------------------------------

### dplyr filter error example

Source: https://style.tidyverse.org/errors

Demonstrates a common error in dplyr::filter where the condition does not evaluate to a logical vector, and shows the corrected usage.

```R
dplyr::filter(mtcars, cyl)
#> BEFORE:
#> ! Argument 2 filter condition does not evaluate to a logical vector.
#> 
#> AFTER:
#> ! Each argument must be a logical vector.
#> * Argument 2 (`cyl`) is an integer vector.
```

--------------------------------

### R: Infix Operators Without Spaces

Source: https://style.tidyverse.org/syntax

Provides examples of R operators that should not be surrounded by spaces due to high precedence, including `::`, `:::`, `$`, `@`, `[`, `[[`, `^`, unary `-`, unary `+`, and `:`. Shows correct and incorrect usage.

```R
sqrt(x^2 + y^2)
df$z
x <- 1:10
```

--------------------------------

### Roxygen Formatting for Details and Lists

Source: https://style.tidyverse.org/documentation

Outlines the conventions for documenting details and lists within roxygen comments. It emphasizes using sentence case for all list items and descriptions, ending each with a period, and using a colon before enumerations or bulleted lists. Function and package names should not be capitalized.

```R
#' @details
#' In the following, we present the bullets of the list:
#' * Four cats are few animals.
#' * forcats is a package.
```

--------------------------------

### R: NEWS File - Common Patterns: New Family of Functions

Source: https://style.tidyverse.org/news

Illustrates a common pattern for documenting a new family of functions in an R package's NEWS file, highlighting improvements in handling ordered factors and changes in interrupt handling for utility functions.

```R
* Support for ordered factors is improved. Ordered factors throw a warning
  when mapped to shape (unordered factors do not), and do not throw warnings
  when mapped to size or alpha (unordered factors do). Viridis is used as
  default colour and fill scale for ordered factors (@karawoo, #1526).

* `possibly()`, `safely()` and friends no longer capture interrupts: this
  means that you can now terminate a mapper using one of these with
  Escape or Ctrl + C (#314).
```

--------------------------------

### Handling Named vs. Unnamed Arguments in R

Source: https://style.tidyverse.org/syntax

Illustrates how to format function calls in R when dealing with a mix of named and unnamed arguments, especially when unnamed arguments are short and named arguments are long. It shows how to maintain consistent line lengths and readability.

```R
# Good
my_function(
  x,
  long_argument_name,
  extra_argument_a = 10,
  extra_argument_b = c(1, 43, 390, 210209)
)

# Also good
my_function(
  x = x,
  y = long_argument_name,
  extra_argument_a = 10,
  extra_argument_b = c(1, 43, 390, 210209)
)
```

--------------------------------

### R Braced Expressions - Good Practices

Source: https://style.tidyverse.org/syntax

Demonstrates correct usage of braced expressions in R, including nested if-else statements, function calls with test_that, and tryCatch blocks. Follows tidyverse style guidelines for readability.

```R
if (y < 0 && debug) {
  message("y is negative")
}

if (y == 0) {
  if (x > 0) {
    log(x)
  } else {
    message("x is negative or zero")
  }
} else {
  y^x
}

test_that("call1 returns an ordered factor", {
  expect_s3_class(call1(x, y), c("factor", "ordered"))
})

tryCatch(
  {
    x <- scan()
    cat("Total: ", sum(x), "\n", sep = "")
  },
  interrupt = function(e) {
    message("Aborted by user")
  }
)
```

--------------------------------

### R: NEWS File Structure - Advanced Release with Sections

Source: https://style.tidyverse.org/news

Demonstrates an advanced NEWS file structure for R packages with multiple release notes, using level 2 headings to group changes into categories like 'Breaking changes', 'New features', and 'Minor improvements and fixes'.

```R
# package 1.1.0

## Breaking changes

## New features

## Minor improvements and fixes
```

--------------------------------

### R: Return Statements on Own Line

Source: https://style.tidyverse.org/functions

Highlights the importance of placing R return statements on their own lines for clarity, especially when dealing with control flow. This improves readability and adherence to style guides.

```R
find_abs <- function(x) {
  if (x > 0) {
    return(x)
  }
  x * -1
}
```

--------------------------------

### Formatting R Code Elements

Source: https://style.tidyverse.org/documentation

Provides guidance on using backticks to format R code elements within documentation. This includes function arguments, values, literal code snippets, and class names, ensuring code is visually distinct and correctly interpreted.

```R
`na.rm`
```

```R
`TRUE`, `FALSE`, `NA`, `NaN`, `...`, `NULL`
```

```R
`mean(x, na.rm = TRUE)`
```

```R
`tbl_df`
```

```R
`tibble()`
```

--------------------------------

### R Documentation Title and Description

Source: https://style.tidyverse.org/documentation

Demonstrates how to write a concise title and description for R functions using roxygen2 comments. The title should be a single sentence in sentence case without a period. Descriptions can be multi-line and support markdown formatting for lists or complex structures.

```R
#' Combine values into a vector or list
#'
#' This is a generic function which combines its arguments.
#'

```

```R
#' Apply a function to each element of a vector
#'
#' @description
#' The map function transform the input, returning a vector the same length
#' as the input.
#'
#' * `map()` returns a list or a data frame
#' * `map_lgl()`, `map_int()`, `map_dbl()` and `map_chr()` return
#'    vectors of the corresponding type (or die trying);
#' * `map_dfr()` and `map_dfc()` return data frames created by row-binding
#'    and column-binding respectively. They require dplyr to be installed.

```

--------------------------------

### R Assignment Operator

Source: https://style.tidyverse.org/syntax

Highlights the Tidyverse standard of using the assignment operator `<-` instead of `=` in R.

```R
# Good
x <- 5

# Bad
x = 5
```
Tokens:
Raw