Rename columns in a data frame and tibble based on a dictionary

dta_rename() renames columns in a data frame dat using a dictionary dict. The dictionary specifies the old column names and their corresponding new names.

Usage

dta_rename(dat, dict = NULL, .oldnames, .newnames)

Arguments

dat: A data frame whose columns are to be renamed.
dict: A data frame serving as the dictionary, containing the old and new variable names.
.oldnames: A column in dict specifying the old variable names.
.newnames: A column in dict specifying the new variable names.

Value

A tibble with renamed columns.

Details

The function checks the following:

Both dat and dict are data frames or tibbles.
Columns specified in .oldnames exist in dict.
The new variable names .newnames are unique.
There is no overlap between .oldnames and .newnames to avoid conflicts.

If any issues are detected, an error or warning is raised to ensure proper processing.

Examples

data("data_bmi")
dta_gtable(data_bmi)


  id
      age
      height
      weight
    
STM/4921
50
1.64
59
STM/4396
34
1.98
57
STM/7908
50
1.95
84
STM/7243
39
1.52
63
STM/4801
52
1.69
65
STM/5134
50
1.71
73
STM/7138
35
1.73
46
STM/6802
72
1.98
70
STM/4420
42
1.62
103
STM/6351
40
1.89
96
STM/4933
38
1.91
67
STM/4303
37
1.56
75
STM/7465
45
1.62
44
STM/4587
67
1.38
51
STM/5320
44
1.37
63

# Rename the columns `age` and `weight` to `age_in_years`
# and `weight_in_kgs`

result <- dta_rename(
  dat = data_bmi,
  .oldnames = c("age", "weight"),
  .newnames = c("age_in_years", "weight_in_kgs")
)

dta_gtable(result)


  id
      age_in_years
      height
      weight_in_kgs
    
STM/4921
50
1.64
59
STM/4396
34
1.98
57
STM/7908
50
1.95
84
STM/7243
39
1.52
63
STM/4801
52
1.69
65
STM/5134
50
1.71
73
STM/7138
35
1.73
46
STM/6802
72
1.98
70
STM/4420
42
1.62
103
STM/6351
40
1.89
96
STM/4933
38
1.91
67
STM/4303
37
1.56
75
STM/7465
45
1.62
44
STM/4587
67
1.38
51
STM/5320
44
1.37
63

# Rename all columns to `unique_id`, `age_in_years`,
# `height_in_meters` and `weight_in_kgs`. In this case,

new_names <- c(
  "unique_id",
  "age_in_years",
  "height_in_meters",
  "weight_in_kgs"
)
result2 <- dta_rename(
  dat = data_bmi,
  .oldnames = NA,
  .newnames = new_names
)

dta_gtable(result2)


  unique_id
      age_in_years
      height_in_meters
      weight_in_kgs
    
STM/4921
50
1.64
59
STM/4396
34
1.98
57
STM/7908
50
1.95
84
STM/7243
39
1.52
63
STM/4801
52
1.69
65
STM/5134
50
1.71
73
STM/7138
35
1.73
46
STM/6802
72
1.98
70
STM/4420
42
1.62
103
STM/6351
40
1.89
96
STM/4933
38
1.91
67
STM/4303
37
1.56
75
STM/7465
45
1.62
44
STM/4587
67
1.38
51
STM/5320
44
1.37
63

# Rename from a dictionary - Begin by loading the dataset
# with columns to be renamed.

data("data_rename")
dta_gtable(head(data_rename))


  uniqueidentifier
      where_from
      age
      height
      weight
      group
      maritalstatus
      highesteducationlevel
      employed
      socioeconomicstatus
    
STM/4921
North East
50
1.64
59
AB
Married
Bachelors
Yes
High
STM/4396
Central
34
1.98
57
A
Married
Masters
Yes
Low
STM/7908
West
50
1.95
84
A
Married
Bachelors
Yes
Low
STM/7243
Central
39
1.52
63
O
Single
Masters
Yes
High
STM/4801
Central
52
1.69
65
AB
Single
Doctorate
No
Low
STM/5134
West
50
1.71
73
AB
Married
Doctorate
No
Middle

# The dictionary with the columns `oldnames` and
# `newnames` representing the old and new variable names
# respectively

data("dict_rename")
dta_gtable(dict_rename)


  old
      new
    
uniqueidentifier
id
where_from
region
age
age_years
height
height_meters
weight
weight_kg
group
age_group
maritalstatus
marital_status
highesteducationlevel
education_level
employed
employment_status
socioeconomicstatus
ses

# Perform the renaming

result3 <- dta_rename(
  dat = data_rename,
  dict = dict_rename,
  .oldnames = old,
  .newnames = new
)

dta_gtable(result3)


  id
      region
      age_years
      height_meters
      weight_kg
      age_group
      marital_status
      education_level
      employment_status
      ses
    
STM/4921
North East
50
1.64
59
AB
Married
Bachelors
Yes
High
STM/4396
Central
34
1.98
57
A
Married
Masters
Yes
Low
STM/7908
West
50
1.95
84
A
Married
Bachelors
Yes
Low
STM/7243
Central
39
1.52
63
O
Single
Masters
Yes
High
STM/4801
Central
52
1.69
65
AB
Single
Doctorate
No
Low
STM/5134
West
50
1.71
73
AB
Married
Doctorate
No
Middle
STM/7138
West
35
1.73
46
A
Single
Bachelors
No
High
STM/6802
West
72
1.98
70
B
Single
Doctorate
No
Low
STM/4420
West
42
1.62
103
AB
Single
Masters
No
Middle
STM/6351
North East
40
1.89
96
A
Other
Doctorate
Yes
High
STM/4933
West
38
1.91
67
B
Married
Bachelors
Yes
High
STM/4303
West
37
1.56
75
A
Single
Bachelors
No
Low
STM/7465
South
45
1.62
44
AB
Married
Bachelors
Yes
Low
STM/4587
Central
67
1.38
51
O
Married
Bachelors
No
Low
STM/5320
South
44
1.37
63
AB
Married
Bachelors
No
Middle

id	age	height	weight
STM/4921	50	1.64	59
STM/4396	34	1.98	57
STM/7908	50	1.95	84
STM/7243	39	1.52	63
STM/4801	52	1.69	65
STM/5134	50	1.71	73
STM/7138	35	1.73	46
STM/6802	72	1.98	70
STM/4420	42	1.62	103
STM/6351	40	1.89	96
STM/4933	38	1.91	67
STM/4303	37	1.56	75
STM/7465	45	1.62	44
STM/4587	67	1.38	51
STM/5320	44	1.37	63

uniqueidentifier	where_from	age	height	weight	group	maritalstatus	highesteducationlevel	employed	socioeconomicstatus
STM/4921	North East	50	1.64	59	AB	Married	Bachelors	Yes	High
STM/4396	Central	34	1.98	57	A	Married	Masters	Yes	Low
STM/7908	West	50	1.95	84	A	Married	Bachelors	Yes	Low
STM/7243	Central	39	1.52	63	O	Single	Masters	Yes	High
STM/4801	Central	52	1.69	65	AB	Single	Doctorate	No	Low
STM/5134	West	50	1.71	73	AB	Married	Doctorate	No	Middle

old	new
uniqueidentifier	id
where_from	region
age	age_years
height	height_meters
weight	weight_kg
group	age_group
maritalstatus	marital_status
highesteducationlevel	education_level
employed	employment_status
socioeconomicstatus	ses