R help files can contain diverse information: some are only a few lines long while others contain dozens of pages of information. Not all R help files include all possible sections, but there are a few core sections that tend to show up pretty consistently due to their general usefulness.
Description
R: Order rows using column values
Description
arrange() orders the rows of a data frame by the values of selected columns.
Unlike other dplyr verbs, arrange() largely ignores grouping; you need to explicitly mention grouping
variables (or use .by_group = TRUE) in order to group by them, and functions of variables are
evaluated once per data frame, not once per group.
As the name implies, the Description section provides a brief, human-readable description of the functions purpose.
Usage
R: Order rows using column values
Usage
arrange(.data, ..., .by_group = FALSE)
## S3 method for class 'data.frame'
arrange(.data, ..., .by_group = FALSE, .locale = NULL)
The Usage section shows the fully parameterized function call. In other words, how to call the function. In particular, this section provides several crucial pieces of information.
The name used to call the function
The name of all the function arguments
The order of the function arguments
Any default values defined for function arguments
Arguments
R: Order rows using column values
Arguments
.data
A data frame, data frame extension (e.g. a tibble), or a lazy data frame (e.g. from dbplyr or dtplyr). See Methods, below, for more details.
...
<data-masking> Variables, or functions of variables. Use desc() to sort a variable in descending order.
.by_group
If TRUE, will sort first by grouping variable. Applies togrouped data frames only.
.locale
The locale to sort character vectors in.
If NULL, the default, uses the "C" locale unless the dplyr.legacy_locale global option escape hatch is active. See the dplyr-locale help page for more details.
If a single string from stringi::stri_locale_list() is supplied, then this will be used as the locale to sort with. For example, "en" will sort with the American English locale. This requires the stringi package.
If "C" is supplied, then character vectors will always be sorted in the C locale. This does not require stringi and is often much faster than supplying a locale identifier.
The C locale is not the same as English locales, such as "en", particularly when it comes to data containing a mix of upper and lower case letters. This is explained in more detail on the locale help page under the Default locale section.
The Arguments section briefly explains each function argument. As you might suspect, the arguments section will probably be the one you reference most frequently since the information contained herein explains the purpose or each function argument and what type of values you are able to specify for each argument.
Details
R: Order rows using column values
Details
Missing values
Unlike base sorting with sort(), NA are:
always sorted to the end for local data, even when wrapped with desc().
treated differently for remote data, depending on the backend.
The Details section expands on the information listed in the Arguments section to provide additional details of function arguments or the functions behavior
Value
R: Order rows using column values
Value
An object of the same type as .data. The output has the following properties:
All rows appear in the output, but (usually) in a different place.
Columns are not modified.
Groups are not modified.
Data frame attributes are preserved.
The Value section describes the type of object returned by the function.
Examples
R: Order rows using column values
Examples
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))
The Examples section contains executable R code that demonstrates the function’s primary use-cases.
Practice
Run the first line of example code from the Examples section of the arrange() documentation shown above.