data_rename: Rename columns and variable names

In easystats/datawizard: Easy Data Wrangling and Statistical Transformations

Rename columns and variable names

Description

Safe and intuitive functions to rename variables or rows in data frames. data_rename() will rename column names, i.e. it facilitates renaming variables. data_rename_rows() is a convenient shortcut to add or rename row names of a data frame, but unlike row.names(), its input and output is a data frame, thus, integrating smoothly into a possible pipe-workflow.

Usage

data_rename(
  data,
  select = NULL,
  replacement = NULL,
  safe = TRUE,
  verbose = TRUE,
  pattern = NULL,
  ...
)

data_rename_rows(data, rows = NULL)

Arguments

data	A data frame.
select	Variables that will be included when performing the required tasks. Can be either a variable specified as a literal variable name (e.g., column_name), a string with the variable name (e.g., "column_name"), a character vector of variable names (e.g., c("col1", "col2", "col3")), or a character vector of variable names including ranges specified via : (e.g., c("col1:col3", "col5")), for some functions, like data_select() or data_rename(), select can be a named character vector. In this case, the names are used to rename the columns in the output data frame. See 'Details' in the related functions to see where this option applies. a formula with variable names (e.g., ~column_1 + column_2), a vector of positive integers, giving the positions counting from the left (e.g. 1 or c(1, 3, 5)), a vector of negative integers, giving the positions counting from the right (e.g., -1 or -1:-3), one of the following select-helpers: starts_with(), ends_with(), contains(), a range using :, or regex(). starts_with(), ends_with(), and contains() accept several patterns, e.g starts_with("Sep", "Petal"). regex() can be used to define regular expression patterns. a function testing for logical conditions, e.g. is.numeric() (or is.numeric), or any user-defined function that selects the variables for which the function returns TRUE (like: foo <- function(x) mean(x) > 3), ranges specified via literal variable names, select-helpers (except regex()) and (user-defined) functions can be negated, i.e. return non-matching elements, when prefixed with a -, e.g. -ends_with(), -is.numeric or -(Sepal.Width:Petal.Length). Note: Negation means that matches are excluded, and thus, the exclude argument can be used alternatively. For instance, select=-ends_with("Length") (with -) is equivalent to exclude=ends_with("Length") (no -). In case negation should not work as expected, use the exclude argument instead. If NULL, selects all columns. Patterns that found no matches are silently ignored, e.g. extract_column_names(iris, select = c("Species", "Test")) will just return "Species".
replacement	Character vector. Can be one of the following: A character vector that indicates the new names of the columns selected in select. select and replacement must be of the same length. A string (i.e. character vector of length 1) with a "glue" styled pattern. Currently supported tokens are: {col} which will be replaced by the column name, i.e. the corresponding value in select. {n} will be replaced by the number of the variable that is replaced. {letter} will be replaced by alphabetical letters in sequential order. If more than 26 letters are required, letters are repeated, but have sequential numeric indices (e.g., a1 to z1, followed by a2 to z2). Finally, the name of a user-defined object that is available in the environment can be used. Note that the object's name is not allowed to be one of the pre-defined tokens, "col", "n" and "letter". An example for the use of tokens is... data_rename( mtcars, select = c("am", "vs"), replacement = "new_name_from_{col}" ) ... which would return new column names new_name_from_am and new_name_from_vs. See 'Examples'. If select is a named vector, replacement is ignored.
safe	Deprecated. Passing unknown column names now always errors.
verbose	Toggle warnings.
pattern	Deprecated. Use select instead.
...	Other arguments passed to or from other functions.
rows	Vector of row names.

Details

select can also be a named character vector. In this case, the names are used to rename the columns in the output data frame. If you have a named list, use unlist() to convert it to a named vector. See 'Examples'.

Value

A modified data frame.

See Also

• Add a prefix or suffix to column names: data_addprefix(), data_addsuffix()

• Functions to reorder or remove columns: data_reorder(), data_relocate(), data_remove()

• Functions to reshape, pivot or rotate data frames: data_to_long(), data_to_wide(), data_rotate()

• Functions to recode data: rescale(), reverse(), categorize(), recode_values(), slide()

• Functions to standardize, normalize, rank-transform: center(), standardize(), normalize(), ranktransform(), winsorize()

• Split and merge data frames: data_partition(), data_merge()

• Functions to find or select columns: data_select(), extract_column_names()

• Functions to filter rows: data_match(), data_filter()

Examples

# Rename columns
head(data_rename(iris, "Sepal.Length", "length"))

# Use named vector to rename
head(data_rename(iris, c(length = "Sepal.Length", width = "Sepal.Width")))

# Change all
head(data_rename(iris, replacement = paste0("Var", 1:5)))

# Use glue-styled patterns
head(data_rename(mtcars[1:3], c("mpg", "cyl", "disp"), "formerly_{col}"))
head(data_rename(mtcars[1:3], c("mpg", "cyl", "disp"), "{col}_is_column_{n}"))
head(data_rename(mtcars[1:3], c("mpg", "cyl", "disp"), "new_{letter}"))

# User-defined glue-styled patterns from objects in environment
x <- c("hi", "there", "!")
head(data_rename(mtcars[1:3], c("mpg", "cyl", "disp"), "col_{x}"))

easystats/datawizard documentation built on April 17, 2025, 5:32 a.m.