add: Create, modify, and delete variables.

In bruceR: Broadly Useful Convenient and Efficient R Functions

Create, modify, and delete variables.

Description

Enhanced functions to create, modify, and/or delete variables. The functions integrate the advantages of base::within(), dplyr::mutate(), dplyr::transmute(), and data.table::let().

Usage

add(data, expr, when, by, drop = FALSE)

added(data, expr, when, by, drop = FALSE)

Arguments

data	A data.table (preferred).
expr	Passing to data.table: DT[ , let(expr), ] R expression(s) to compute variables. Execute each line of expression one by one, such that newly created variables are available immediately. This is an advantage of dplyr::mutate() and has been implemented here for data.table.
when	[Optional] Passing to data.table: DT[when, , ] Compute for which rows or rows meeting what condition(s)?
by	[Optional] Passing to data.table: DT[ , , by] Compute by what group(s)?
drop	Drop existing variables and return only new variables? Defaults to FALSE, which returns all variables.

Value

• add() returns a new data.table, with the raw data unchanged.

• added() returns nothing and has already changed the raw data.

Examples

## ====== Usage 1: add() ====== ##

d = as.data.table(within.1)
d$XYZ = 1:8
d

# add() does not change the raw data:
add(d, {B = 1; C = 2})
d

# new data should be assigned to an object:
d = d %>% add({
  ID = str_extract(ID, "\\d")  # modify a variable
  XYZ = NULL                   # delete a variable
  A = .mean("A", 1:4)          # create a new variable
  B = A * 4    # new variable is immediately available
  C = 1        # never need ,/; at the end of any line
})
d


## ====== Usage 2: added() ====== ##

d = as.data.table(within.1)
d$XYZ = 1:8
d

# added() has already changed the raw data:
added(d, {B = 1; C = 2})
d

# raw data has already become the new data:
added(d, {
  ID = str_extract(ID, "\\d")
  XYZ = NULL
  A = .mean("A", 1:4)
  B = A * 4
  C = 1
})
d


## ====== Using `when` and `by` ====== ##

d = as.data.table(between.2)
d

added(d, {SCORE2 = SCORE - mean(SCORE)},
      A == 1 & B %in% 1:2,  # `when`: for what conditions
      by=B)                 # `by`: by what groups
d
na.omit(d)


## ====== Return Only New Variables ====== ##

newvars = add(within.1, {
  ID = str_extract(ID, "\\d")
  A = .mean("A", 1:4)
}, drop=TRUE)
newvars


## ====== Better Than `base::within()` ====== ##

d = as.data.table(within.1)

# wrong order: C B A
within(d, {
  A = 4
  B = A + 1
  C = 6
})

# correct order: A B C
add(d, {
  A = 4
  B = A + 1
  C = 6
})

bruceR documentation built on Aug. 21, 2025, 5:38 p.m.