Check response curve data for common issues — check_response_curve

Checks to make sure an exdf object representing multiple response curves meets basic expectations.

Usage

check_response_curve_data(
    licor_exdf,
    identifier_columns,
    expected_npts = 0,
    driving_column = NULL,
    driving_column_tolerance = 1.0,
    col_to_ignore_for_inf = 'gmc',
    error_on_failure = TRUE,
    print_information = TRUE
  )

Arguments

licor_exdf: An exdf object representing data from a Licor gas exchange measurement system.
identifier_columns: A vector or list of strings representing the names of columns in licor_exdf that, taken together, uniquely identify each curve. This often includes names like plot, event, replicate, etc.
expected_npts: The number of points that should be in each response curve. If expected_npts is set to 0, then all response curves are expected to have the same (unspecified) number of points. If expected_npts is set to a negative number, then this check will be skipped.
driving_column: The name of a column that is systematically varied to produce each curve; for example, in a light response curve, this would typically by Qin. If driving_column is NULL, then this check will be skipped.
driving_column_tolerance: An absolute tolerance for the deviation of each value of driving_column away from its mean across all the curves; the driving_column_tolerance can be set to Inf to disable this check.
col_to_ignore_for_inf: Any columns to ignore while checking for infinite values. Mesophyll conductance (gmc) is often set to infinity intentionally so should be ignored when performing this check. To completely disable this check, set col_to_ignore_for_inf to NULL.
error_on_failure: A logical value indicating whether to send an error message when an issue is detected. See details below.
print_information: A logical value indicating whether to print additional information to the R terminal when an issue is detected. See details below.

Details

This function makes a few basic checks to ensure that the Licor data includes the expected information and does not include any mistakes. If no problems are detected, this function will be silent with no return value. If a problem is detected and error_on_failure is TRUE, then this function will throw an error with a short message; if error_on_failure is FALSE, then this function will throw a warning instead. If a problem is detected and print_information is TRUE, additional information about the problem will be printed to the R terminal.

This function will perform the following checks, some of which are optional:

If col_to_ignore_for_inf is not NULL, no numeric columns in licor_exdf should have infinite values, with the exception of columns designated in col_to_ignore_for_inf.
All elements of identifier_columns should be present as columns in licor_exdf. If driving_column is not NULL, it should also be present as a column in licor_exdf.
licor_exdf will be split into chunks according to the values of its identifier_columns. If this exdf file represents response curves, then each chunk should represent a single curve and a few additional checks can be performed:
- If expected_npts >= 0, then each chunk should have the same number of points. If expected_npts > 0, then each chunk should have expected_npts points.
- If driving_column is not NULL, then each code chunk should have the same sequence of values in this column. To allow for small variations, a nonzero driving_column_tolerance can be specified.

Using check_response_curve_data is not strictly necessary, but it can be helpful both to you and to anyone else reading your analysis code. Here are a few typical use cases:

Average response curves: It is common to calculate and plot average response curves, either manually or by using xyplot_avg_rc. But, it only makes sense to do this if each curve followed the same sequence of the driving variable. In this case, check_response_curve_data can be used to confirm that each curve used the same values of CO2_r_sp (for an A-Ci curve) or Qin (for an A-Q curve).
Removing recovery points: It is common to wish to remove one or more recovery points from a set of curves. The safest way to do this is to confirm that all the curves use the same sequence of setpoints; then you can be sure that, for example, points 9 and 10 are the recovery points in every curve.
Making a statement of expectations: If you measured a set of A-Ci curves where each curve has 16 points and used the same sequence of CO2_r setpoints, you could record this somewhere in your notes. But it would be even more meaningful to use check_response_curve_data in your script with expected_npts set to 16. If this check passes, then it means not only that your claim is correct, but also that the identifier columns are being interpreted properly.

Sometimes the response curves in a large data set were not all measured with the same sequence of setpoints. If only a few different sequences were used, it is possible to split them into groups and separately run check_response_curve_data on each group. This scenario is discussed in the Frequently Asked Questions vignette.

Even if none of the above situations are relevant to you, it may still be helpful to run run check_response_curve_data but with expected_npts set to 0 and error_on_failure set to FALSE. With these settings, if there are curves with different numbers of points, the function will print the number of points in each curve to the R terminal, but won't stop the rest of the script from running. This can be useful for detecting problems with the curve_identifier column. For example, if the longest curves in the set are known to have 17 points, but check_response_curve_data identifies a curve with 34 points, it is clear that the same identifier was accidentally used for two different curves.

Value

The check_response_curve_data function does not return anything.

Examples

# Read an example Licor file included in the PhotoGEA package and check it.
# This file includes several 7-point light-response curves that can be uniquely
# identified by the values of its 'species' and 'plot' columns. Since these are
# light-response curves, each one follows a pre-set sequence of `Qin` values.
licor_file <- read_gasex_file(
  PhotoGEA_example_file_path('ball_berry_1.xlsx')
)

# Make sure there are no infinite values and that all curves have the same
# number of points
check_response_curve_data(licor_file, c('species', 'plot'))

# Make sure there are no inifinite values and that all curves have 7 points
check_response_curve_data(licor_file, c('species', 'plot'), 7)

# Make sure there are no infinite values, that all curves have 7 points, and
# that the values of the `Qin` column follow the same sequence in all curves
# (to within 1.0 micromol / m^2 / s)
check_response_curve_data(licor_file, c('species', 'plot'), 7, 'Qin', 1.0)