Documentation, vignette, parameter tweaks (#30)

R/models.R

@@ -97,8 +97,6 @@ wtf_normalize_time <- function(time, normalize = TRUE) {
 #' pass NULL to run with no grouping
 #' @param time_column Name of the time column in \code{data}, character
 #' @param conc_column Name of the gas concentration column in \code{data}, character
-#' @param volume XXX
-#' @param area XXX
 #' @param dead_band Length of dead band, the equilibration period at the
 #' beginning of the time series during which data are ignore, in seconds (numeric)
 #' @param normalize_time Normalize the values so that first is zero? Logical
@@ -120,8 +118,6 @@ wtf_compute_fluxes <- function(data,
                                group_column,
                                time_column,
                                conc_column,
-                               volume,
-                               area,
                                dead_band = 0,
                                normalize_time = TRUE,
                                fit_function = wtf_fit_models,

inst/extdata/TG10-01087-metadata.csv

@@ -5,3 +5,4 @@ Date,Start_time,Plot,Volume,Area,Obs_length
 2022-10-27,10:40:30,D,,,60
 2022-10-27,10:42:00,E,,,60
 2022-10-27,10:43:30,F,,,60
+2022-10-27,11:00:00,G,,,60

tests/testthat/test-models.R

@@ -31,7 +31,7 @@ test_that("wtf_compute_fluxes works", {
   ff <- function(a, b) data.frame(x = 1) # dummy fit function
 
   # Normalize times
-  out <- wtf_compute_fluxes(x, "Plot", "time", "conc", 1, 1,
+  out <- wtf_compute_fluxes(x, "Plot", "time", "conc",
                             fit_function = ff, normalize_time = TRUE)
   expect_s3_class(out, "data.frame")
   expect_identical(out$Plot, plots) # one row per plot
@@ -40,15 +40,15 @@ test_that("wtf_compute_fluxes works", {
   expect_identical(out$time_max, rep(max(times), nrow(out))) # max of raw times
 
   # Raw times
-  out <- wtf_compute_fluxes(x, "Plot", "time", "conc", 1, 1,
+  out <- wtf_compute_fluxes(x, "Plot", "time", "conc",
                             fit_function = ff, normalize_time = FALSE)
   expect_identical(out$Plot, plots) # one row per plot
   expect_identical(out$time, rep(mean(times), nrow(out))) # mean of raw times
   expect_identical(out$time_min, rep(min(times), nrow(out))) # min of raw times
   expect_identical(out$time_max, rep(max(times), nrow(out))) # max of raw times
 
   # Passing NULL for the group column should return a single row
-  out <- wtf_compute_fluxes(x, NULL, "time", "conc", 1, 1,
+  out <- wtf_compute_fluxes(x, NULL, "time", "conc",
                             fit_function = ff, normalize_time = TRUE)
   expect_s3_class(out, "data.frame")
   expect_identical(nrow(out), 1L) # one row

vignettes/integrating-gasfluxes.Rmd

@@ -0,0 +1,19 @@
+---
+title: "Integrating with the gasfluxes package"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Integrating with the gasfluxes package}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+```{r setup}
+library(whattheflux)
+```

vignettes/intro-to-whattheflux.Rmd

@@ -27,7 +27,12 @@ library(whattheflux)
 # Data from a LI-7810
 f <- system.file("extdata/TG10-01087.data", package = "whattheflux")
 dat <- wtf_read_LI7810(f)
-dat[1:6, 1:9] # full raw dataset has 500+ rows and 25 columns
+
+# Note that the whattheflux read functions print some info after reading
+# Set "options(whattheflux.quiet = TRUE)" to suppress such messages
+
+# Look at a subset of the data; the full data frame has 500+ rows and 25 columns
+dat[1:6, 1:9]
 ```
 
 The data frame returned by `wtf_read_LI7810` is all data from the raw
@@ -54,8 +59,6 @@ how long they lasted, plot/treatment/collar information, etc.
 md <- system.file("extdata/TG10-01087-metadata.csv", package = "whattheflux")
 metadat <- read.csv(md)
 
-# Note: set "options(whattheflux.quiet = TRUE)" to suppress messages like these
-
 print(metadat)
 ```
 
@@ -75,6 +78,8 @@ dat$metadat_row <- wtf_metadata_match(
   start_times = metadat$Start_time,
   obs_lengths = metadat$Obs_length + 10) # 10 is expected dead band length
 
+# Note that wtf_metadata_match() warns us that one metadata row didn't match any data
+
 # Based on the row match information, add a "Plot" column to the data
 dat$Plot <- metadat$Plot[dat$metadat_row]
 metadat$metadat_row <- seq_len(nrow(metadat))
@@ -127,7 +132,7 @@ dat$CO2_umol <- wtf_ppm_to_umol(dat$CO2,
 # Note that because we didn't provide the 'atm' parameter, 
 # wtf_ppm_to_umol assumed standard pressure.
 
-# Also normalize by ground area (0.16 m2)
+# Also normalize by ground area (0.16 m2 in this example)
 dat$CO2_umol_m2 <- dat$CO2_umol / 0.16
 ```
 
@@ -156,7 +161,7 @@ fluxes <- wtf_compute_fluxes(dat,
 fluxes[c(1:2, 4, 14, 15, 20)]
 
 # The data frame also has columns TIMESTAMP_min and TIMESTAMP_max,
-# giving the entire period over which the flux was computed.
+# specifying the entire period over which each flux was computed.
 
 ggplot(fluxes, aes(Plot, slope_estimate, color = adj.r.squared)) +
   geom_point() +
@@ -181,3 +186,11 @@ The plot C (green) data have more scatter, and thus lower R<sup>2</sup> values a
 higher uncertainty on the computed flux,
 but there's no evidence of nonlinearity or outlier problems.
 
+## Conclusion
+
+This vignette covered `whattheflux` basics: loading data and metadata,
+matching the two, performing unit conversion, computing fluxes, and some
+basic QA/QC. The test data we worked above could be fit well by linear model,
+but for many reasons this might not always be true; see the vignette on
+[integrating with the gasfluxes package](integrating-gasfluxes.html) for
+guidance on using more sophisticated model-fitting routines.