simulate_error function

Simulate gas exchange data with measurement error

Description

simulate_error(
  ph_out,
  chamber_pars,
  n = 1L,
  use_tealeaves = ("T_air" %in% colnames(ph_out))
)

Arguments

• ph_out: A data frame of output from photo() or photosynthesis()

  with units.

• chamber_pars: A data frame with a single row of chamber parameters. See Note below for table of required parameters.

• n: Integer. Number of replicated simulations per row of ph_out.

• use_tealeaves: Flag. The tealeaves package uses a slightly different equation to calculate the saturating water content of air as a function temperature and pressure than LI-COR. If FALSE, the function uses LI-COR's equation in the LI6800 manual. If TRUE, it uses the tealeaves

  function for internal consistency. The function attempts to guess whether ph_out was run with tealeaves , but this can be manually overridden by providing a value for the argument.

Returns

A data frame with n * nrow(ph_out) rows. It contains all the original output in ph_out as well as a column .rep indicating replicate number from 1 to n. Other new columns are assumed or measured chamber parameters and 'measured' values estimated from synthetic data with measurement error:

column name	assumed or derived?	description
flow	assumed	chamber flow rate
leaf_area	assumed	leaf area in chamber
sigma_CO2_r	assumed	standard deviation of measurement error in CO2_r
sigma_CO2_s	assumed	standard deviation of measurement error in CO2_s
sigma_H2O_r	assumed	standard deviation of measurement error in H2O_r
sigma_H2O_s	assumed	standard deviation of measurement error in H2O_s
c_0	derived	CO $_2$ concentration before entering chamber [ $\mu$ mol / mol]
w_i	derived	Water vapor concentration within leaf [mmol / mol]
w_a	derived	Water vapor concentration in chamber [mmol / mol]
w_0	derived	Water vapor concentration before entering chamber [mmol / mol]
g_tw	derived	Leaf conductance to water vapor [mol/m $^2$ /s]
E_area	derived	Evaporation rate per area [mmol/m $^2$ /s]
E	derived	Total evaporation rate [mmol/s]
CO2_r	derived	CO $_2$ concentration before entering chamber with measurement error [ $\mu$ mol / mol]
CO2_s	derived	CO $_2$ concentration in chamber with measurement error [ $\mu$ mol / mol]
H2O_s	derived	Water vapor concentration in chamber with measurement error [mmol / mol]
H2O_r	derived	Water vapor concentration before entering chamber with measurement error [mmol / mol]
E_meas	derived	Total evaporation rate (measured) [mmol/s]
E_area_meas	derived	Evaporation rate per area (measured) [mmol/m $^2$ /s]
g_tw_meas	derived	Leaf conductance to water vapor (measured) [mol/m $^2$ /s]
g_sc_meas	derived	Stomatal conductance to CO $_2$ (measured) [mol/m $^2$ /s]
g_tc_meas	derived	Leaf conductance to CO $_2$ (measured) [mol/m $^2$ /s]
A_meas	derived	Net photosynthetic CO $_2$ assimilation (measured) [ $\mu$ mol/m $^2$ /s]
C_i	derived	Intercellular CO $_2$ concentration (measured) [ $\mu$ mol/mol]

Note

The required parameters for the chamber_pars argument are:

• flow [$\mu$mol / s]: chamber flow rate
• leaf_area [cm ^ 2]: leaf area in chamber
• sigma_CO2_s [$\mu$mol / mol]: standard deviation of sample [CO$_2$] measurement error
• sigma_CO2_r [$\mu$mol / mol]: standard deviation of reference [CO$_2$]
• sigma_H2O_s [mmol / mol]: standard deviation of sample [H$_2$O] measurement error
• sigma_H2O_r [mmol / mol]: standard deviation of sample [H$_2$O] measurement error

Units for flow and leaf_area should be provided; units are implied for sigma's but not necessary to specify because rnorm() drop units.

To evaluate the accuracy and precision of parameter estimation methods, it may be useful to simulate data with realistic measurement error. This function takes output from from photo() or photosynthesis() models, adds measurement error in CO$_2$ and H$_2$O concentrations, and calculates parameter estimates with synthetic data. Currently, the function assumes a simplified 1-dimensional CO$_2$ and H$_2$O conductance model: zero cuticular conductance, infinite boundary layer conductance, and infinite airspace conductance. Other assumptions include:

• chamber flow rate, leaf area, leaf temperature, and air pressure are known without error
• measurement error is normally distributed mean 0 and standard deviation specified in chamber_pars

This function was designed with the LI-COR LI6800 instrument in mind, but in principle applies to any open path gas exchange system.

Examples

library(photosynthesis)

# Use photosynthesis() to simulate 'real' values
# `replace = ...` sets parameters to meet assumptions of `simulate_error()`
lp = make_leafpar(replace = list(
  g_sc = set_units(0.1, mol/m^2/s),
  g_uc = set_units(0, mol/m^2/s),
  k_mc = set_units(0, 1),
  k_sc = set_units(0, 1),
  k_uc = set_units(0, 1)
  ),
  use_tealeaves = FALSE)
   
 ep = make_enviropar(replace = list(
   wind = set_units(Inf, m/s)
 ), use_tealeaves = FALSE) 
 bp = make_bakepar()
 cs = make_constants(use_tealeaves = FALSE)
 
 chamber_pars = data.frame(
   flow = set_units(600, umol / s),
   leaf_area = set_units(6, cm ^ 2),
   sigma_CO2_s = 0.1,
   sigma_CO2_r = 0.1,
   sigma_H2O_s = 0.1,
   sigma_H2O_r = 0.1
 )
   
ph = photosynthesis(lp, ep, bp, cs, use_tealeaves = FALSE, quiet = TRUE) |>
  simulate_error(chamber_pars, n = 1L)