set_variable: Set values, units, and categories for a column in a table

Description

Sets the value, units, and/or category of a new or existing column of a table-like object.

Usage

set_variable(
    data_table,
    name,
    units = NULL,
    category = NULL,
    value = NA,
    id_column = NULL,
    value_table = NULL
  )

Value

An object based on data_table with new and/or modified columns.

Arguments

data_table: A table-like R object such as a data frame or an exdf.
name: The name of the column to be added to data_table.
units: The units of the column to be added to data_table.
category: The category of the column to be added to data_table.
value: The value of the column to be added to data_table.
id_column: The name of an identifier column in data_table.
value_table: A list of named elements, where the name of each element is a possible value of the id_column and the value of each element is the corresponding value that the name column should take.

Details

There are two main "modes" for setting the value of the new column: it can be set to a fixed value (using the value input argument), or it can be set according to the values of another column (using the id_column and value_table input arguments). The latter method is useful when different values must be specified for different treatments within the data set.

In greater detail, this function attempts to set the value of a new or existing column in an exdf object according to the following rules:

The value of the name column of data_table will be set to value; this assignment follows the usual rules; in other words, value could be a single value or a vector of length nrow(data_table).
If units and categories are both NULL, the units and category will not be specified. In this case, if the name column already exists, its units and category will remain the same; if the name column is new, it will be initialized with NA for its units and category.
If either units _or_ category is not NULL, the units and category for the name column _will_ be specified. In this case, if one of units or category _is_ NULL, its value will be set to NA.
If id_column is not NULL, then the value_table will be used to set different values of the name column for each specified value of id_column. For example, if id_column is species and value_table = list(soybean = 1, tobacco = 2), then the name column will be set to 1 when species is 'soybean' and 2 when species is 'tobacco'. For any other values of species (such as 'maize'), the value of name will still be value. **Note**: values of the id_column will be converted using as.character before making comparisons.

For other table-like objects, such as data frames, only the values will be set, and the units and categories will be ignored.

Examples

Run this code

# Create a simple exdf object with two columns (`A` and `B`) and default values
# for its units and categories.
simple_exdf <- exdf(data.frame(A = c(3, 2, 7, 9), B = c(4, 5, 1, 8)))

print(simple_exdf)

# Add a new column called 'C' with units 'u1' and category 'cat1' whose value is
# 1000.
simple_exdf <- set_variable(simple_exdf, 'C', 'u1', 'cat1', 1000)

# Set the value of the 'B' column to 2000 when 'A' is 3, to 3000 when 'A' is 9,
# and to 4000 for all other values of 'A'. Do not modify its units or category.
simple_exdf <- set_variable(
  simple_exdf,
  'B',
  value = 4000,
  id_column = 'A',
  value_table = list('3' = 2000, '9' = 3000)
)

print(simple_exdf)

# Take the same operations, but using a data frame instead
simple_df <- data.frame(A = c(3, 2, 7, 9), B = c(4, 5, 1, 8))

simple_df <- set_variable(simple_exdf$main_data, 'C', 'u1', 'cat1', 1000)

simple_df <- set_variable(
  simple_df,
  'B',
  value = 4000,
  id_column = 'A',
  value_table = list('3' = 2000, '9' = 3000)
)

print(simple_df)

# As a more realistic example, load a Licor file and set different values of
# mesophyll conductance for each species in the data set.
licor_file <- read_gasex_file(
  PhotoGEA_example_file_path('ball_berry_1.xlsx')
)

licor_file <- set_variable(
  licor_file,
  'gmc',
  'mol m^(-2) s^(-1) bar^(-1)',
  '',
  id_column = 'species',
  value_table = list(soybean = 0.9, tobacco = 1.1)
)

print(licor_file[, c('species', 'gmc'), TRUE])