Complete documentation updates for 0.7.1 release.

R/calibrate_ambient_carbon_gainoffset.R

@@ -6,13 +6,13 @@ calibrate_ambient_carbon_Bowling2003 <- function(...) {
 
 #' Calibrate ambient carbon isotope data using gain-and-offset method
 #'
-#' @author Rich Fiorella \email{rfiorella@@lanl.gov}
-#'
 #' Function called by `calibrate_carbon_bymonth()` to apply
 #' gain and offset parameters to the ambient datasets (000_0x0_09m and
 #' 000_0x0_30m). This function should generally not be used independently,
 #' but should be used in coordination with
 #' `calibrate_carbon_bymonth()`.
+#' 
+#' @author Rich Fiorella \email{rfiorella@@lanl.gov}
 #'
 #' @param amb_data_list List containing an ambient d13C dataset.
 #'                      Will include all variables in 000_0x0_xxm. (character)

R/calibrate_ambient_carbon_linreg.R

@@ -1,12 +1,12 @@
 #' Calibrate ambient carbon isotope data using linear regression
 #'
-#' @author Rich Fiorella \email{rfiorella@@lanl.gov}
-#'
 #' Function called by `calibrate_ambient_carbon_linreg` to apply
 #' gain and offset parameters to the ambient datasets (000_0x0_09m and
 #' 000_0x0_30m). This function should generally not be used independently,
 #' but should be used with `calibrate_ambient_carbon_linreg`.
 #'
+#' @author Rich Fiorella \email{rfiorella@@lanl.gov}
+#'
 #' @param amb_data_list List containing an ambient d13C dataset.
 #'             Will include all variables in 000_0x0_xxm. (character)
 #' @param caldf Calibration data frame containing gain and offset values for

R/calibrate_ambient_water_isotopes.R

@@ -1,14 +1,14 @@
 #' calibrate_ambient_water_isotopes
 #'
-#' @author Rich Fiorella \email{rfiorella@@lanl.gov}
-#'
 #' Function called by `calibrate_ambient_water_linreg` to apply
 #' slope and intercept parameters to the ambient datasets (000_0x0_09m and
 #' 000_0x0_30m) to correct to the VSMOW scale.
 #' This function should generally not be used independently,
 #' but should be used with `calibrate_ambient_water_linreg`.
 #' Note that in this version *NO CORRECTION FOR HUMIDITY* is performed.
 #' Use with caution.
+#' 
+#' @author Rich Fiorella \email{rfiorella@@lanl.gov}
 #'
 #' @param amb_data_list List containing ambient d18O/d2H datasets.
 #'             Will include all variables in 000_0x0_xxm. (character)

R/output_functions.R

@@ -60,6 +60,10 @@ setup_output_file <- function(inname, outname, site, analyte) {
 #######################################
 #' Write carbon calibrations to file
 #'
+#' Write a `data.frame` with slope, intercepts, and error estimates of 
+#' calibrations for carbon isotope system. If `gainoffset` method was used
+#' the slopes/intercepts are called gain/offsets for each isotopologue.
+#'
 #' @author Rich Fiorella \email{rfiorella@@lanl.gov}
 #'
 #' @param outname Output file name.
@@ -171,8 +175,11 @@ write_carbon_ambient_data <- function(outname,
 #######################################
 ### FUNCTIONS THAT WORK ON ONLY H2O ###
 #######################################
-#' Write carbon calibration parameters to file
+#' Write water calibration parameters to file
 #'
+#' Write a `data.frame` with slope, intercepts, and error estimates of 
+#' calibrations for water isotope system.
+#' 
 #' @author Rich Fiorella \email{rfiorella@@lanl.gov}
 #'
 #' @param outname Output file name.

R/reference_data_regression.R

@@ -1,8 +1,8 @@
 #' Leave-one-out cross validation
 #'
-#' @author Rich Fiorella \email{rfiorella@@lanl.gov}
+#' Calculate analytic leave-one-out cross variance error estimate
 #'
-#' helper function for the leave-one-out cross variance
+#' @author Rich Fiorella \email{rfiorella@@lanl.gov}
 #'
 #' @param mod Fitted model to estimate leave-one-out CV on.
 #'
@@ -14,6 +14,14 @@ loocv <- function(mod) {
 
 #' Produce estimates of the calibration error.
 #'
+#' Estimate calibration error using a 5-fold cross-validation. A 5-fold
+#' cross-validation was chosen as each calibration window should have
+#' at least 6 data points (e.g., if only daily validation data are used for the
+#' calibration) and therefore this ensures that the cross-validation should
+#' always run. Model is fit using \code{lm} and the \code{caret} package, with
+#' root-mean-square error (RMSE), the R-squared value, and mean-absolute
+#' error (MAE) extracted from the cross-validation.
+#'
 #' @author Rich Fiorella \email{rfiorella@@lanl.gov}
 #'
 #' @param data Data frame to perform cross-validation on.
@@ -40,10 +48,17 @@ estimate_calibration_error <- function(formula, data) {
 
 #' Estimate slope/intercept of carbon isotope calibration regression
 #'
+#' Performs regression between measured and known carbon isotope and mole
+#' fractions to generate a transfer function and associated uncertainty
+#' estimates using both 5-fold and leave-one-out cross-validation methods.
+#' Regression occurs either on 12CO2/13CO2 mole fractions (gainoffset method)
+#' or on the CO2 and d13C values (linreg). 
+#'
 #' @author Rich Fiorella \email{rfiorella@@lanl.gov}
 #'
-#' @param method Are we using the Bowling et al. 2003 method
-#'              ("Bowling_2003") or direct linear regression of
+#' @param method Are we using the gain-and-offset method
+#'              ("gainoffset"), formerly called the Bowling et al. 2003 method
+#'              in this package, or direct linear regression of
 #'              d13C and CO2 mole fractions ("linreg")?
 #' @param calibration_half_width Determines the period (in days)
 #'        from which reference data are selected (period
@@ -421,6 +436,11 @@ fit_carbon_regression <- function(ref_data, method, calibration_half_width,
 
 #' Estimate slope/intercept of water isotope calibration regression
 #'
+#' Performs regression between measured and known carbon isotope and mole
+#' fractions to generate a transfer function and associated uncertainty
+#' estimates using both 5-fold and leave-one-out cross-validation methods.
+#' Regression occurs on d18O and d2H values. 
+#' 
 #' @param ref_data Reference data.frame from which to estimate
 #'        calibration parameters.
 #' @param calibration_half_width Determines the period (in days)
@@ -438,7 +458,6 @@ fit_carbon_regression <- function(ref_data, method, calibration_half_width,
 #' @param min_nobs Minimum number of high-frequency observations to
 #'                 define a peak.
 #'
-
 #' @return Returns a data.frame of calibration parameters.
 #'        Output data.frame includes slope, intercept, and r^2 values
 #'        for d13C and CO2 values.

R/restructure_data.R

@@ -2,6 +2,11 @@
 #==============================
 #' Ingest and stack variables needed in calibration.
 #'
+#' Opens and stacks isotope ratio and water/carbon dioxide mole fraction
+#' variables from monthly HDF5 files. If a new enough version of `neonUtilities`
+#' is available, this function will try to use `fasttime` in order to accelerate
+#' data stacking.
+#'
 #' @author Rich Fiorella \email{rfiorella@@lanl.gov}
 #'
 #' @param inname A file (or list of files) to extract data from for calibration.
@@ -351,6 +356,9 @@ restructure_variables <- function(dataframe,
 #-----------------------------------------
 #' Restructure ingested variables for the carbon isotope system.
 #'
+#' Restructures carbon isotope measurement system variables and shortens names 
+#' to simplify referencing variables elsewhere in calibration code.
+#'
 #' @param varname Which variable are we applying this function to? There's
 #'                a list of ~10 common ones to write to the hdf5 file.
 #' @param dataframe Input data.frame, from `neonUtilities::stackEddy`
@@ -459,6 +467,9 @@ restructure_carbon_variables <- function(dataframe,
 #-----------------------------------------
 #' Restructure ingested variables for the water isotope system.
 #'
+#' Restructures water isotope measurement system variables and shortens names 
+#' to simplify referencing variables elsewhere in calibration code.
+#' 
 #' @param varname Which variable are we applying this function to? There's
 #'                a list of ~10 common ones to write to the hdf5 file.
 #' @param dataframe Input data.frame, from `neonUtilities::stackEddy`

R/standard_corrections.R

@@ -132,6 +132,9 @@ correct_carbon_ref_cval <- function(std_frame,
 
 #' Correct carbon ref output
 #'
+#' Corrects known mismatches in the database where standard values do not
+#' actually match what they should in data files per calVal measurements.
+#'
 #' @author Rich Fiorella \email{rfiorella@@lanl.gov}
 #'
 #' @param std_list List containing reference/validation gas measurements.
@@ -167,19 +170,19 @@ correct_carbon_ref_output <- function(std_list,
   if (omit_already_corrected) {
     carb_red <- subset(carb,
                        carb$co2_repairedRaw == FALSE |
-                         carb$d13C_repairedRaw == FALSE)
+                       carb$d13C_repairedRaw == FALSE)
   } else {
     carb_red <- carb
   }
 
   # strip off time indices
-  carb_red <- carb_red[carb_red$site == site &
+  carb_red <- carb_red[carb_red$site == site &&
                          carb_red$ref_gas == substr(ref_gas,
                                                     1,
                                                     nchar(ref_gas) - 4), ]
 
   # check to see if site is in carb$site, otherwise, we can skip.
-  if (nrow(carb_red) > 0 & (site %in% unique(carb$site))) {
+  if (nrow(carb_red) > 0 && (site %in% unique(carb$site))) {
 
     # check name of list to see if any corrections are needed for this standard
     for (z in 1:nrow(carb_red)) {