set_variable: Set values, units, and categories for a column in a table
In PhotoGEA: Photosynthetic Gas Exchange Analysis

set_variable

R Documentation

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
  )

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.

Value

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

Examples

# 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])

PhotoGEA documentation built on Aug. 25, 2025, 5:13 p.m.