Select variables.

These functions power select() and rename().

select_vars(vars, ..., include = character(), exclude = character())

rename_vars(vars, ..., strict = TRUE)

Arguments

vars	A character vector of existing column names.
..., args	Expressions to compute These arguments are automatically quoted and evaluated in a context where elements of vars are objects representing their positions within vars. They support unquoting and splicing. See vignette("programming") for an introduction to these concepts. Note that except for :, - and c(), all complex expressions are evaluated outside that context. This is to prevent accidental matching to vars elements when you refer to variables from the calling context.
include, exclude	Character vector of column names to always include/exclude.
strict	If TRUE, will throw an error if you attempt to rename a variable that doesn't exist.

Value

A named character vector. Values are existing column names, names are new names.

Details

For historic reasons, the vars and include arguments are not prefixed with .. This means that any argument starting with v might partial-match on vars if it is not explicitly named. Also ... cannot accept arguments named exclude or include. You can enquose and splice the dots to work around these limitations (see examples).

See also

select_var()

Examples

# Keep variables
select_vars(names(iris), everything())
#>   Sepal.Length    Sepal.Width   Petal.Length    Petal.Width        Species 
#> "Sepal.Length"  "Sepal.Width" "Petal.Length"  "Petal.Width"      "Species" 
select_vars(names(iris), starts_with("Petal"))
#>   Petal.Length    Petal.Width 
#> "Petal.Length"  "Petal.Width" 
select_vars(names(iris), ends_with("Width"))
#>   Sepal.Width   Petal.Width 
#> "Sepal.Width" "Petal.Width" 
select_vars(names(iris), contains("etal"))
#>   Petal.Length    Petal.Width 
#> "Petal.Length"  "Petal.Width" 
select_vars(names(iris), matches(".t."))
#>   Sepal.Length    Sepal.Width   Petal.Length    Petal.Width 
#> "Sepal.Length"  "Sepal.Width" "Petal.Length"  "Petal.Width" 
select_vars(names(iris), Petal.Length, Petal.Width)
#>   Petal.Length    Petal.Width 
#> "Petal.Length"  "Petal.Width" 
select_vars(names(iris), one_of("Petal.Length", "Petal.Width"))
#>   Petal.Length    Petal.Width 
#> "Petal.Length"  "Petal.Width" 

df <- as.data.frame(matrix(runif(100), nrow = 10))
df <- df[c(3, 4, 7, 1, 9, 8, 5, 2, 6, 10)]
select_vars(names(df), num_range("V", 4:6))
#>   V4   V5   V6 
#> "V4" "V5" "V6" 

# Drop variables
select_vars(names(iris), -starts_with("Petal"))
#>   Sepal.Length    Sepal.Width        Species 
#> "Sepal.Length"  "Sepal.Width"      "Species" 
select_vars(names(iris), -ends_with("Width"))
#>   Sepal.Length   Petal.Length        Species 
#> "Sepal.Length" "Petal.Length"      "Species" 
select_vars(names(iris), -contains("etal"))
#>   Sepal.Length    Sepal.Width        Species 
#> "Sepal.Length"  "Sepal.Width"      "Species" 
select_vars(names(iris), -matches(".t."))
#>   Species 
#> "Species" 
select_vars(names(iris), -Petal.Length, -Petal.Width)
#>   Sepal.Length    Sepal.Width        Species 
#> "Sepal.Length"  "Sepal.Width"      "Species" 

# Rename variables
select_vars(names(iris), petal_length = Petal.Length)
#>   petal_length 
#> "Petal.Length" 
select_vars(names(iris), petal = starts_with("Petal"))
#>         petal1         petal2 
#> "Petal.Length"  "Petal.Width" 

# Rename variables preserving all existing
rename_vars(names(iris), petal_length = Petal.Length)
#>   Sepal.Length    Sepal.Width   petal_length    Petal.Width        Species 
#> "Sepal.Length"  "Sepal.Width" "Petal.Length"  "Petal.Width"      "Species" 

# You can unquote names or formulas (or lists of)
select_vars(names(iris), !!! list(quo(Petal.Length)))
#>   Petal.Length 
#> "Petal.Length" 
select_vars(names(iris), !! quote(Petal.Length))
#>   Petal.Length 
#> "Petal.Length" 

# The .data pronoun is available:
select_vars(names(mtcars), .data$cyl)
#>   cyl 
#> "cyl" 
select_vars(names(mtcars), .data$mpg : .data$disp)
#>    mpg    cyl   disp 
#>  "mpg"  "cyl" "disp" 

# However it isn't available within calls since those are evaluated
# outside of the data context. This would fail if run:
# select_vars(names(mtcars), identical(.data$cyl))


# If you're writing a wrapper around select_vars(), pass the dots
# via splicing to avoid matching dotted arguments to select_vars()
# named arguments (`vars`, `include` and `exclude`):
wrapper <- function(...) {
  select_vars(names(mtcars), !!! quos(...))
}

# This won't partial-match on `vars`:
wrapper(var = cyl)
#>   var 
#> "cyl" 

# This won't match on `include`:
wrapper(include = cyl)
#> include 
#>   "cyl"