%% Next 2 lines needed for non-Sweave vignettes
%\VignetteEngine{knitr::knitr} 
%\VignetteIndexEntry{Data processing for volumetric BMP measurements}

\documentclass{article}

%%\usepackage[version=3]{mhchem} %chemical formulas
\usepackage[colorlinks = true, urlcolor = blue]{hyperref} % Must be loaded as the last package

<<include=FALSE, cache=FALSE>>=
library(knitr)
#opts_chunk$set(cache=FALSE,tidy=FALSE,highlight=FALSE)
opts_chunk$set(cache = FALSE, tidy = FALSE, fig.align = "center")

library(biogas)
options(width=65)
@

\title{Data processing for volumetric BMP measurements}
\author{Nanna L\o jborg and Sasha D. Hafner}

\begin{document}
\maketitle

\section{Introduction}
Volumetric methods are commonly used for measuring cumulative biogas and methane production in order to determine methane potential and anaerobic biodegradability of a given substrate. In volumetric methods, biogas volumes are measured under constant pressure using different methods such as liquid displacement and syringe methods \cite{rozzi_environmental_2004}. In the liquid displacement method, the biogas is transferred to an external system measuring the volume. As biogas is produced it is collected in the external liquid displacement system displacing an amount of the barrier liquid equivalent to the biogas volume. In the syringe method, lubricated syringes are manually inserted into the bottle of interest. Here, the pressure increase resulting from biogas production forces the piston inwards the syringe until the pressure equilibrates the surrounding pressure (most commonly atmospheric). Produced biogas volume is equivalent to the displacement of the piston and can be read directly of the syringe \cite{filer_BMP_2019}. 

Determination of CH$_4$ volume from volumetric measurements requires data processing. 
The \texttt{calcBgVol()} function was developed to process volumetric data. 
A newly developed biogas package (available for the R environment since 2015) address issues with time-consuming calculations and lack of reproducible among laboratories for obtaining BMP \cite{softwarex}. The biogas package consists of ten functions including \texttt{cumBg()}, which are used for processing volumetric, manometric, gravimetric, and gas density measurements. The resulting biogas and methane production and production rates can be further used to calculate BMP using the \texttt{summBg()} function. 

This document describes how to process volumetric biogas measurements using the \texttt{calcBgVol()} function. 
We assumed that readers are familiar with biogas data collection and R.

\section{Overview of the Function}
\texttt{calcBgVol()} is a ``high-level'' function within the biogas package. The purpose of \texttt{calcBgVol()} is to convert volume data collected in the laboratory to cumulative biogas and CH$_4$ production and production rates. Typically, these vaues will then be used for calculation of BMP, e.g. using the \texttt{summBg()} function. \texttt{calcBgVol()} can handle data from multiple bottles and accepts three different data structures. For simple operations (e.g. interpolation and standardization of biogas volume) \texttt{calcBgVol()} is supported by calls to external ``low-level'' functions (refer to Section~\ref{function_internals}, Table \ref{tab:externalfunctionsummary}).

Two methods are commonly used to calculate methane production from volume and composition measurements. Method 1 is based on normalized CH$_4$ concentrations, whereas method 2 accounts for the actual CH$_4$ in the bottle headspace. Both methods are available through \texttt{calcBgVol()} and results are expected to be virtual identical. The examples below describe cumulative biogas calculation from three datasets of different structures (\texttt{``wide''}, \texttt{``long''}, and \texttt{``longcombo''}) using volumetric method 1. For method 2 examples, refer to vignette for manometric cumBg function (\texttt{cumBgMan\_function.Rnw}). 

\subsection{Function Arguments}
The arguments for the function are:
\begin{verbatim}
## function (dat, comp = NULL, temp = NULL, pres = NULL, 
##           interval = TRUE, data.struct = "longcombo", 
##           id.name = "id", time.name = "time", 
##           vol.name = "vol", comp.name = "xCH4", 
##           headspace = NULL, vol.hs.name = "vol.hs", 
##           cmethod = "removed", imethod = "linear", 
##           extrap = FALSE, addt0 = TRUE, showt0 = TRUE, 
##           dry = FALSE, empty.name = NULL,  
##           std.message = !quiet, check = TRUE, 
##           temp.std = getOption("temp.std", as.numeric(NA)), 
##           pres.std = getOption("pres.std", as.numeric(NA)), 
##           unit.temp = getOption("unit.temp", "C"), 
##           unit.pres = getOption("unit.pres", "atm"),
##           quiet = FALSE) 
## NULL
\end{verbatim}

Most of the arguments have default values, but to calculate CH$_4$ production we must provide values for at least  \texttt{dat} (data frame with response variable - here volume measurements), \texttt{comp} (data frame with methane concentration),  \texttt{pres} (biogas pressure), and \texttt{temp} (biogas temperature)\footnote{.      
  By default, temperature is in $^\circ$C and pressure in atm, but these can be changed in the function call with the \texttt{temp.unit} and \texttt{pres.unit} arguments, or globally with \texttt{options}. The same default values apply for temperature and pressure for presentation of biogas and methane, but these can be changed in the function call with the \texttt{temp.std} and \texttt{pres.std} argurments.} along with the names of a few columns in the input data frames. If \texttt{temp} and/or \texttt{pres} arguments are not provided, biogas volumes will not be standardized.

By default \texttt{interval = TRUE} and \texttt{data.struct} is set as \texttt{``longcombo''}. \texttt{``wide''} and \texttt{``long''} structured data will be restructured to \texttt{``longcombo''} internally by \texttt{cumBgDataPrep()}, when specified by the \texttt{data.struct} argument (refer to Section~\ref{structures}). When data are cumulative, the interval argument should be set to FALSE. When data are mixed interval and cumulative response variables (\texttt{empty.name != TRUE}), the interval argument is ignored.

Similarly, there is an \texttt{id.name} argument for the bottle identification code (ID) column (default is \texttt{``id''}). The default value is \texttt{``id''}. For \texttt{data.struct = ``wide''}, there is no ID column. Instead data for each bottle, have individual columns and column names, which are used as ID codes. Here, the name of the column containing the response variables (\texttt{vol.name}), is set as the name of the first column with response variables. All following columns are assumed to have measurement data. 

Furthermore, we need to specify the name of the time column containing time data using the \texttt{time.name} argument (default is \texttt{``time''}).
If separate data frames are used for \texttt{dat} and \texttt{comp}, the name must match. Time data may be POSIXct objects, but then t0 will not be added to rows by the \texttt{calcBgVol()} function. In addition the \texttt{addt0} argument is used to add row with ``time zero'' (\texttt{time.name = 0}) for each bottle in order to calculate production rates for the first observation (default is TRUE). \texttt{showt0} determines if the ``time zero'' should be returned in the output (default is TRUE if time.name is numeric and contains 0 and otherwise FALSE). The use of t0 output is for plotting. 

The \texttt{comp.name} argument is used to indicate which column within the \texttt{comp} data frame contains the CH$_4$ content. Default is \texttt{``xCH4''}. The \texttt{comp} argument may be a single value instead of a data frame or column. When providing a single value for \texttt{comp}, this value is applied to all observations, and the \texttt{comp.name} argument is not needed. Note that if the \texttt{comp} argument is not provided, \texttt{calcBgVol()} will return results for biogas only and not CH$_4$. The definition of \texttt{``xCH4''} depends on the cmethod argument.
By default (\texttt{cmethod = ``removed''}) the function calculates volumes following \cite{richards_methods_1991} as the product of standardized volume of biogas removed and normalized CH$_4$ content (as mole fraction in dry biogas, normalized so the sum of mole fractions of CH$_4$ and CO$_2$ sum to unity). If results should be based on the sum of methane removed and methane remaining in the bottle headspace, \texttt{cmethod} should be set to \texttt{``total''}. When \texttt{cmethod = ``total''}, CH$_4$ concentration is expressed relative to all biogas components except water (CH$_4$, CO$_2$, N$_2$, H$_2$S, etc.) instead of CH$_4$ and CO$_2$ only.

If any CH$_4$ measurements are missing, \texttt{``xCH4''} is interpolated by the external ``low-level'' function \texttt{interp()}. Here, the \texttt{imethod} argument can be used to define interpolation method (default is \texttt{``linear''}), which is passed to \texttt{interp()}.   
Similar, an \texttt{extrap} argument is passed to \texttt{interp()} (default is FALSE). The \texttt{extrap} argument is used to indicate if composition data (\texttt{comp.name}) should be extrapolated (e.g. in the case of missing initial composition values). Extrapolation is constant (the value of the nearest observation is taken).   
In general, extrapolation and extensive interpolation should be avoided.

Additionally, a data frame containing headspace volumes is required if \texttt{cmethod = ``total''} and should contain at least a headspace volume column (\texttt{vol.hs.name}) and a bottle identification column, with the same column name as in \texttt{dat} and \texttt{comp} data frames. The headspace volume column can be set using the \texttt{vol.hs.name} argument (default is \texttt{``vol.hs''}).

By default biogas is assumed to be saturated with water vapor. If biogas volumes are already standardized to dry conditions (as with AMPTS II data) we need to set \texttt{dry = TRUE}.

\subsection{Data Structures}
\label{structures}
Input data may be structured in one of three ways: \texttt{``longcombo''}, \texttt{``long''}, and \texttt{``wide''} Default is \texttt{``longcombo''}, where the composition column is in the \texttt{dat} data frame and no separate composition data frame is required. In the following examples all three data structures will be addressed. For more details about each of the three data structure see \texttt{biogas\_quick\_start} vignette.

\newpage
\section{Examples: Calculation of Cumulative Production of Biogas and CH$_4$ and Production Rates from Volumetric Measurements}
Calculation of cumulative biogas and CH$_4$ production and production rates, typically requires two data frames: Biogas volume measurements and biogas composition (CH$_4$ concentration).

\subsection{\texttt{``longcombo''} Data Structure}
\label{longcombo}
In this example, we will use a \texttt{``longcombo''} example dataset included in the biogas package: \texttt{s3lcombo} for both biogas volumes and composition.
These data are from an experiment carried out with municipal wastewater sludge.
Only three bottles, all with inoculum and substrate, were included: D, E, and F.
300 mL glass serum bottles with butyl rubber septa and screw caps were used. 
Volume was measured using syringes.
Methane and carbon dioxide contents were determined by gas chromatography using a thermal conductivity detector and normalized so methane and carbon dioxide sum to 1.0.
This is a small dataset, with versions available for all three different data structures. 
It cannot be used to calculate BMP, because no inoculum-only bottles were included.

<<>>=  
data("s3lcombo")

dim(s3lcombo)

s3lcombo

summary(s3lcombo)
@

Calculating cumulative biogas and CH$_4$ production and production rates, is a common first step in processing data from a BMP test. Subsequently, BMP can be calculated by the ``high-level'' function \texttt{summBg()} included in the biogas package.
Cumulative biogas and CH$_4$ production and production rates from volumetric data with \texttt{s3lcombo} data frame as the only input, can be calculated from {\texttt{calcBgVol()}.

To calculate CH$_4$ production from these \texttt{``longcombo''} data, we must provide values for at least \texttt{dat} and \texttt{comp}, which is in a combined data frame (we will use \texttt{s3lcombo}), \texttt{temp} (biogas temperature), and \texttt{pres} (biogas pressure) along with the names of a few columns in our input data frame.

We can use the default values \texttt{``longcombo''}, \texttt{``id''}, and \texttt{``xCH4''} for the \texttt{data.struct}, \texttt{id.name}, and \texttt{comp.name} arguments, respectively. Whereas, the \texttt{vol.name} argument needs to be specified as \texttt{``vol.ml''}.
Similar, default values can be used for \texttt{cmethod = ``removed''}, evaluating CH$_4$ concentration based on normalized CH$_4$ and CO$_2$ values and for \texttt{imethod = ``linear''}, resulting in internal linear interpolation of \texttt{xCH4} by calling the \texttt{interp} function. 
Furthermore, initial composition (\texttt{xCH4}) values are missing in the \texttt{s3lcombo} data frame. Therefore, we set \texttt{extrap = TRUE} for extrapolation of these initial CH$_4$ values

By default biogas is assumed to be saturated with water vapor (\texttt{dry = FALSE}). Biogas volumes have not been standardized to dry conditions and hence, default value for the \texttt{dry} argument matches requirements for making an proper evaluation of the dataset.
  
<<>>=
cum.prod.lc <- calcBgVol(s3lcombo, temp = 25, pres = 1, 
                         time.name = 'time.d', vol.name = 'vol.ml', 
                         comp.name = 'xCH4',
                         extrap = TRUE)
@

The output becomes:

<<>>=
head(cum.prod.lc)

dim(cum.prod.lc)
@

The returned data frame has maintained the \texttt{``longcombo''} structure with all the original columns in \texttt{s3lcombo}, plus additional columns from volumetric biogas calculations. 

In these columns, \texttt{v} stands for (standardized) volume, \texttt{cv} (standardized) cumulative volume, \texttt{rv} stands for (standardized) volume production rate, and \texttt{Bg} and \texttt{CH4} for biogas and methane.
\texttt{cvBg} contains standardized cumulative biogas production and \texttt{cvCH4} contains standardized cumulative CH$_4$ production.

Plotting results is recommended for easier understanding, and it can be used to catch strange responses.
Here we will use the \texttt{ggplot} function from the \texttt{ggplot2} package to plot it.

<<fig.width=6, fig.height=4, fig.align="center">>=
library(ggplot2)

ggplot(cum.prod.lc, aes(time.d, cvCH4, colour = factor(id))) + 
  geom_point() +
  geom_line(aes(group = id)) +
  labs(x = "Time [d]", y = "Cumulative methane production  [mL]", colour = "Bottle ID")  + 
  theme_bw() 
@

\subsection{\texttt{``wide''} Data Structure}
In this example, we will use a \texttt{``wide''} structured example dataset included in the biogas package, having the data frame \texttt{feedVol} for biogas volumes and \texttt{feedSetup} for bottle identification and substrate and inoculum masses. The \texttt{feedsetup} data frame is not relevant for \texttt{calcBgVol()}, but is required subsequently for \texttt{summBg()} to calculate BMP.
BMP measurement data are from a batch test carried out on animal feed ingredients along with cellulose as a control. 
The experiment included 12 batch bottles:
\begin{itemize}
  \item Three bottles with inoculum only (BK)
  \item Three bottles with cellulose and inoculum (CEL)
  \item Three bottles with animal feed ingredient 1 and inoculum (SC)
  \item Three bottles with animal feed ingredient 2 and inoculum (SD)
\end{itemize}

A typical automated volumetric method called AMPTS II was used to measure biogas production: an online, standardized lab-measurement platform for BMP tests. Applying AMPTS II, the measured volumes are standardized, and the composition is 100\% methane. Therefore, the \texttt{comp} argument is set to 1 when calling the \texttt{calcBgVol()} function. Furthermore, pressure is set to a fixed value (1 atm or 101.325 kPa) and temperature to 0$^\circ$C. 
<<>>=  
data("feedVol")

dim(feedVol)

head(feedVol)

summary(feedVol)
@

As with the \texttt{``longcombo''} data, cumulative production of CH$_4$ is needed in order to calculate BMP.
Again, we can calculate these with the \texttt{calcBgVol()} function, using the \texttt{feedVol} data frame and the \texttt{comp = 1} argument as inputs.
For this particular example, standardized, cumulative CH$_4$ volume is present in the input data frame (as with all AMPTS II datasets) and the function only restructures the data and calculates interval volumes and rates.
In other cases (see \texttt{s3volw} for example), volume standardization and other steps (e.g. interpolation or summing interval values to get cumulative) are needed.

To calculate CH$_4$ production from these \texttt{``wide''} structured data, we must provide values for at least \texttt{dat}, \texttt{comp}, \texttt{temp}, and \texttt{pres} along with the names of a few columns in our input data frame. The \texttt{dat} argument is set as the \texttt{feedVol} data frame, whereas \texttt{comp}, \texttt{temp}, and \texttt{pres} are set as single values of 1 (mole fraction), 0 (degree C), and 1 (atm), respectively. Since a single value is provided for \texttt{comp}, the \texttt{comp.name} argument is not required.

For \texttt{data.struct != ``longcombo''} the data structure needs to be specified. Here we set \texttt{data.struct = ``wide''}.
Furthermore, we need to specify the name of the time column in \texttt{feedVol} using the \texttt{time.name} argument. 

As mentioned, there are no ID columns for \texttt{data.struct = ``wide''}. Instead column name of the first column with response variables (volume measurements) is used as ID code.  
In this example observations are numbered 1 to 12 and hence, the \texttt{vol.name} argument is set to 1. All following columns are assumed to also contain response variables. 
By default (\texttt{cmethod = ``removed''}) CH$_4$ concentrations are evaluated based on normalized CH$_4$ and CO$_2$ values. 
Similar, default values can be used for \texttt{imethod = ``linear''}, resulting in internal linear interpolation of xCH4 by calling the \texttt{interp()} function, and \texttt{extrap = FALSE} as all composition data are provided (set to 1 for all observations). 

By default biogas is assumed to be saturated with water vapor. For AMPTS II data, biogas volume are already standardized to dry conditions. Therefore, we set \texttt{dry = TRUE}. 
Additionally, the response variables are cumulative data and hence, we set \texttt{interval = FALSE}. 

<<>>=
cum.prod.w <- calcBgVol(feedVol, comp = 1, temp = 0, pres = 1,
                       data.struct = "wide",
                       time.name = "time.d", vol.name = "1",
                       dry = TRUE,
                       interval = FALSE)
@

Note the message about standard temperature and pressure--it is important to make sure these values are correct, therefore users are reminded by a message\footnote{
  Remember that standard conditions can be set in the function call with \texttt{temp.std} and \texttt{pres.std}, or globally with \texttt{options()}. 
}. Also, note the message about applying single composition value to all observations. When defining pressure as a single value, pressure is assumed to be constant and the same for all observations.  

The output becomes:

<<>>=
head(cum.prod.w)

dim(cum.prod.w)
@

The data frame that is returned has been sorted and restructured to \texttt{``longcombo''} structure and has all the original columns in \texttt{feedVol}, plus additional columns from the volumetric calculation method (refer to Section~\ref{longcombo}). 

As with the \texttt{``longcombo''} data example, the results may be easier to understand graphically using the \texttt{ggplot} function from the \texttt{ggplot2} package.

<<fig.width=6, fig.height=4, fig.align="center">>=
ggplot(cum.prod.w, aes(time.d, cvCH4, colour = factor(id))) + 
       geom_point() +
       geom_line(aes(group = id)) +
       labs(x = "Time [d]", y = "Cumulative methane production  [mL]", colour = "Bottle ID")  + 
       theme_bw() 
@

\subsection{\texttt{``long''} Data Structure}
In this example, we will use long structured example datasets included with the biogas package: \texttt{vol} for biogas volumes and \texttt{comp} for composition.
These data are from a BMP test carried out on two different substrates A and B, and cellulose included as a "control".
The experiment included 12 batch bottles:
\begin{itemize}
  \item 3 bottles with substrate A and inoculum
  \item 3 bottles with substrate B and inoculum
  \item 3 bottles with cellulose and inoculum
  \item 3 bottles with inoculum only
\end{itemize}
Bottles consisted of 500 mL or 1.0 L glass bottles, and were sealed with a butyl rubber septum and a screw cap.
Initial substrate and inoculum masses were determined.
A typical volumetric method was used to measure biogas production: accumulated biogas was measured and removed intermittently using syringes, and composition was measured for some of these samples. 

<<>>=  
data("vol")

dim(vol)

head(vol)

summary(vol)
@

<<>>=
data("comp")

dim(comp)

head(comp)

summary(comp)
@

To calculate CH$_4$ production from these \texttt{``long''} structured data, we must provide values for at least \texttt{dat} (we will use \texttt{vol}), \texttt{comp} (we will use \texttt{comp}), \texttt{temp}, and \texttt{pres}.
For \texttt{data.struct != ``longcombo''} the data structure needs to be specified. Here we set \texttt{data.struct = ``long''}.
Furthermore, we need to specify the name of the time column in \texttt{feedVol} using the \texttt{time.name} argument. 

We can use default values \texttt{``id''}, \texttt{``vol''}, and \texttt{``xCH4''} for the \texttt{id.name}, \texttt{vol.name} and \texttt{comp.name} arguments, respectively.
Similar, default values can be used for \texttt{cmethod = ``removed''}, evaluating CH$_4$ concentration based on normalized CH$_4$ and CO$_2$ values, for \texttt{imethod = ``linear''}, resulting in internal linear interpolation of \texttt{xCH4} by calling the \texttt{interp()} function, and for \texttt{dry = TRUE} assuming biogas to be saturated with water vapor.
Additionally, the response variables are interval data only and hence, we can use the default \texttt{interval = TRUE}.

In addition to interpolation for later observations, an extrapolation argument (\texttt{extrap}) can be provided if required. We do not have initial biogas composition (compare the heads of the \texttt{vol} and \texttt{comp} data frames) so extrapolation is needed, in addition to interpolation. Therefore, we set \texttt{extrap = TRUE}.
  
<<>>=
cum.prod.l <- calcBgVol(vol, comp = comp, temp = 35, pres = 1,
                       data.struct = "long",
                       time.name = "days", vol.name = "vol", comp.name = "xCH4", 
                       extrap = TRUE)
@

The output becomes:

<<>>=
head(cum.prod.l)

dim(cum.prod.l)
@

The returned data frame has been restructured to \texttt{``longcombo''} structure and contains all the original columns in \texttt{vol}, plus additional columns from volumetric biogas calculations (refer to Section~\ref{longcombo}). 

As with the \texttt{``longcombo''} data example, the results may be easier to understand graphically using the \texttt{ggplot} function from the \texttt{ggplot2} package.

<<fig.width=6, fig.height=4, fig.align="center">>=
ggplot(cum.prod.l, aes(days, cvCH4, colour = factor(id))) + 
      geom_point() +
      geom_line(aes(group = id)) +
      labs(x = "Time [d]", y = "Cumulative methane production  [mL]", 
           colour = "Bottle ID")  + 
      theme_bw() 
@


\subsection{Other Arguments}
Instead of setting fixed single values for temperature and pressure arguments, these can be taken from columns within \texttt{dat}.
Fixed data were created by adding temperature and pressure data to the \texttt{vol} data frame used in the \texttt{``long''} data structure example. Temperature is set to a fixed value for all observations, whereas pressure is set to vary between observations using \texttt{rnorm()} having a mean value of 1 atm and a standard deviation of 0.001. It is possible to have both pressure and temperature values that varies between measurements. Though, the approach (function call) would be similar to the shown below.    
<<>>=  
data("vol")

dim(vol)

head(vol)

summary(vol)
@

<<>>=
data("comp")

dim(comp)

head(comp)

summary(comp)
@

Adding temperature and pressure to the \texttt{dat} data frame. 
<<>>=
vol$temp <- 35
vol$pres <- NA
vol$pres <- rnorm(vol$pres, mean = 1, sd = 0.001)

head(vol)
@

The arguments required to process these data using \texttt{calcBgVol()} are the same as in the \texttt{``long''} data structure example above, except from the \texttt{temp} and \texttt{pres} arguments. Instead of fixed values, we now need to call a column name from \texttt{vol}. Therefore, we set \texttt{temp = ``temp''} and \texttt{pres = ``pres''}
<<>>=
cum.prod <- calcBgVol(vol, comp = comp, temp = "temp", pres = "pres",
                       data.struct = "long",
                       time.name = "days", vol.name = "vol", comp.name = "xCH4", 
                       extrap = TRUE)
@

The returned data frame has been restructured to \texttt{``longcombo''} structure and contains all the original columns in \texttt{vol}, plus additional columns from volumetric biogas calculations.
In a similar matter, the \texttt{comp} argument can be set as a single value instead of a column or data frame.  

By default, time zero rows are added from the \texttt{addt0} argument. Time zero rows can be omitted by setting \texttt{showt0 = FALSE}.
<<>>=
cum.prod <- calcBgVol(vol, comp = comp, temp = "temp", pres = "pres",
                       data.struct = "long",
                       time.name = "days", vol.name = "vol", comp.name = "xCH4", 
                       extrap = TRUE, showt0 = FALSE)

head(cum.prod)
@

The results are shown graphically using the \texttt{ggplot} function from the \texttt{ggplot2} package.
<<fig.width=6, fig.height=4, fig.align="center">>=
ggplot(cum.prod, aes(days, cvCH4, colour = factor(id))) + 
      geom_point() +
      geom_line(aes(group = id)) +
      labs(x = "Time [d]", y = "Cumulative methane production  [mL]", 
           colour = "Bottle ID")  + 
      theme_bw() 
@

Note the lack of observations in time zero in the plot.

Furthermore, we can avoid adding the time zero values in the first place by setting \texttt{addt0 = FALSE}.
<<>>=
cum.prod <- calcBgVol(vol, comp = comp, temp = "temp", pres = "pres",
                       data.struct = "long",
                       time.name = "days", vol.name = "vol", comp.name = "xCH4", 
                       extrap = TRUE, addt0 = FALSE)

head(cum.prod)
@

Note how rates are not calculated for the first observations when \texttt{addt0 = FALSE}, in contrary to \texttt{showt0 = FALSE} where initial rates are calculated. In both cases, cumulative production values for the first observations are omitted from the plot.  

<<fig.width=6, fig.height=4, fig.align="center">>=
ggplot(cum.prod, aes(days, cvCH4, colour = factor(id))) + 
      geom_point() +
      geom_line(aes(group = id)) +
      labs(x = "Time [d]", y = "Cumulative methane production  [mL]", 
           colour = "Bottle ID")  + 
      theme_bw() 
@


By default, input data are checked for unreasonable values using the \texttt{check} argument. If \texttt{check = TRUE}, the input values of xCH4 in biogas are checked. If data seems unreasonable (0 \textgreater \texttt{xCH4} \textgreater 1), a warning is returned. In the example below, a single methane value in the composition data frame \texttt{comp} has been set to 1.5 for the purpose of demonstrating the function of the \texttt{check} argument. 
<<>>=
data("vol")
data("comp")

comp[10,"xCH4"] <- 1.5
cum.prod <- calcBgVol(vol, comp = comp, temp = 35, pres = 1,
                       data.struct = "long",
                       time.name = "days", vol.name = "vol", comp.name = "xCH4", 
                       extrap = TRUE)
@

Note the warning about methane concentration being outside the range 0 - 1 (exceeding 1 mol/mol) for at least one observation. By default it is assumed to be a percentage and corrected. If this warning is not provided (\texttt{check= TRUE}), we are not made aware of this default correction of the observation.   
<<>>=
cum.prod <- calcBgVol(vol, comp = comp, temp = 35, pres = 1,
                       data.struct = "long",
                       time.name = "days", vol.name = "vol", comp.name = "xCH4", 
                       extrap = TRUE, check = FALSE)
@


By default, the unit of temperature and pressure values are set as degree celsius and atm, respectively. As stated above, these can be set using the \texttt{unit.temp} and \texttt{unit.pres} arguments. For the purpose of demonstrating the function of the unit arguments, the already fixed pressure and temperature values in \texttt{vol} have been manipulated to be \texttt{K} and \texttt{kPa}, respectively.
<<>>=
vol$temp <- 35 + 273.15
vol$pres <- NA
vol$pres <- rnorm(vol$pres, mean = 101.325, sd = 0.101325)

head(vol)
@
<<>>=
cum.prod <- calcBgVol(vol, comp = comp, temp = "temp", pres = "pres",
                       data.struct = "long",
                       time.name = "days", vol.name = "vol", comp.name = "xCH4", 
                       extrap = TRUE)
@

Note the warnings regarding temperature and pressure range. These warnings are a result of the default settings for pressure and temperature units. If we manually set the correct units, these warnings are avoided. 
<<>>=
cum.prod <- calcBgVol(vol, comp = comp, temp = "temp", pres = "pres",
                       data.struct = "long",
                       time.name = "days", vol.name = "vol", comp.name = "xCH4", 
                       extrap = TRUE,
                       unit.pres = "kPa", unit.temp = "K")
@


\section{Continuing With the \texttt{calcBgVol()} Function}
The \texttt{calcBgVol()} function is one of several \texttt{cumBg*()} functions within the biogas package. The results from the \texttt{cumBg*()} functions can be used directly in the \texttt{summBg()} function from the biogas package to calculate BMP for the data in question. Though, this operation often requires additional setup information (e.g. inoculum and substrate mass), which is most commonly provided in an external data frame (\texttt{setup}).   

\section{Function Internals}
\label{function_internals}
In general, \texttt{cumBg*()} functions consist of four sections: argument checks, restructure and sorting data, interpolation if needed, and biogas standardization and calculations. Restructuring and sorting data and interpolation are handled by the external functions \texttt{cumBgDataPrep()} and \texttt{interp()}, respectively. From \texttt{interp()} gas composition, cumulative biogas production, and other variables can be interpolated to a specified time if required. From \texttt{cumBgDataPrep()} \texttt{``wide''} and \texttt{``long''} data structure are restructured to \texttt{``longcombo''} data, which is required for \texttt{calcBgVol()} to process data. Additionally, data are sorted, headspace is added if provided, and composition data is corrected if it seems to be a percentage. If data of interest are mixed (interval and cumulative, \texttt{empty.name = TRUE}), these will be sorted and biogas volume standardized within \texttt{cumBgDataPrep()} to obtain interval data only. Subsequently, the restructured and sorted data is standardized in \texttt{calcBgVol()} by the external function \texttt{stdVol()}, if not already standardized. 

\texttt{calcBgVol()} accepts all data structures, but the volumetric calculation methods within \texttt{calcBgVol()} only process \texttt{``longcombo''} data. \texttt{``wide''} and \texttt{``long''} data are restructured internally by the ``low-level'' function \texttt{cumBgDataPrep()}. \texttt{cumBgDataPrep()} sorts and restructures biogas data for further calculation of cumulative biogas and methane production and production rates. The \texttt{data.struct} argument is internally passed to \texttt{cumBgDataPrep()} and restructured to \texttt{``longcombo''} structure prior to being processed by volumetric calculation methods.

\begin{table}[h!]
  \begin{center}
  \caption{Operations done with the ``low-level'' functions in \texttt{calcBgVol()}. All functions are vectorized. See help files for more details.}
  \label{tab:externalfunctionsummary}
  \vspace{3pt}
  
  \begin{tabular}{ll}
    \hline
    Operation                                    &   Function \\
    \hline
    Standardize gas volume                       &   \texttt{stdVol()} \\
    Interpolate composition etc.                 &   \texttt{interp()} \\
    Structurize and sort data                    &   \texttt{cumBgDataPrep()} \\   
		\hline
  \end{tabular}
  \end{center}
\end{table}

 
\bibliographystyle{plain}  
\begin{thebibliography}{1}

\bibitem{rozzi_environmental_2004}
B.K.~Richards, R.J.~Cummings, T.E.~White, and W.J.~Jewell.
\newblock Methods of assessing microbial activity and inhibition under anaerobic conditions: a literature review.
\newblock {\em Rev Environ Sci Biotechnol}, 3: 93-115, 2004.

\bibitem{filer_BMP_2019}
J. Filer, H.~H. Ding and S. Chang
\newblock Biochemical Methane Potential (BMP) Assay Method for Anaerobic Digestion Research.
\newblock {\em Water}, 11, 921, 2019.

\bibitem{softwarex}
Hafner, S.D., Koch, K., Carrere, H., Astals, S., Weinrich, S., Rennuit, C.
  \newblock{2018}
  \newblock{Software for biogas research: Tools for measurement and prediction of methane production}. 
  \newblock{SoftwareX} 7: 205-210

\bibitem{richards_methods_1991}
B.K.~Richards, R.J.~Cummings, T.E.~White, and W.J.~Jewell.
\newblock Methods for kinetic-analysis of methane fermentation in high solids
  biomass digesters.
\newblock {\em Biomass \& Bioenergy}, 1(2):65--73, 1991.
  

\end{thebibliography}
\end{document}

