R/helper.R

In bgfanalyzer: Analyze Microbial Biogas Fermentation Data

#' Helper to set up a `BGF` object
#'
#' Three helper functions exist that allows users to set up `BGF` objects either from scratch or from external data files.
#'
#' All three helper functions internally call `new_BGF()` with distinct parameters arguments pre-set.
#' The easiest way to generate a `BGF` object is the `BGF()` function. It only needs the `ReaktorLayout` argument to be specified by the user and will subsequently create a object of class `BGF`.
#'
#' @inheritParams new_BGF
#'
#' @returns A `BGF` object
#'
#'@examples
#'# create a simple BGF without data
#' BGF(LETTERS[c(1:5)])
#'
#' @export

# helper for a class "BGF" object ####
BGF <- function(ReactorLayout,
                     BlankLabel="Blank",name="new_BGF",
                     ProcessTemp=NA,InocToSubRatio=2,MeasurementType=NA) {

  ReactorLayout <- correct_RLayout(ReactorLayout) # correct 'ReactorLayout'

  InocToSubRatio <- as.numeric(InocToSubRatio) # convert 'InocToSubRatio' to numeric

  out<-new_BGF(name = name,MeasurementType = MeasurementType,
                    ProcessTemp = ProcessTemp,InocToSubRatio = InocToSubRatio,
                    ReactorLayout = ReactorLayout,BlankLabel = BlankLabel) # generate the BGF object

  validate_BGF(out) # validate the BGF_object

  return(out) # return out
}

#'@rdname BGF
#'
#'@details
#' If `from_AMPTSV2_report` is used, `path` must point to the `report_yyyy-mm-dd_HHMM.csv`-file created by an AMPTS II (BioProcess Control; Lund; Sweden).
#' This special feature was included as the AMPTS II is widely distributed among biogas labs and several R tutorials exist online, that also refer on this system.
#'
#'@param path A path pointing an external data input file must be. Must be in a tidy format for from_standard_record or a report generated by an AMPTS II (see Details)
#'@param feedback `Logical` if `TRUE` the function prints a summary to the R console
#'
#'@examples
#'# create a BGF based on the report of an AMPTS II
#' from_AMPTSV2_report(
#'         ReactorLayout = c("2*Blank","Cellulose","3*neg ctrl","3*FR1","3*FR2","3*FR3"),
#'         BlankLabel = "Blank",
#'         name = "Test",
#'         InocToSubRatio=2,
#'         ProcessTemp = 52,
#'         path = base::system.file("extdata","AMPTSV2.csv",package = "bgfanalyzer"))
#'
#'@export

# helper for "AMPTSV2" type BGF ####
from_AMPTSV2_report=function(ReactorLayout,BlankLabel="Blank",name="new_BGF",ProcessTemp,InocToSubRatio,path,feedback=FALSE){

  out <- BGF(ReactorLayout=ReactorLayout,BlankLabel=BlankLabel,name=name,ProcessTemp=ProcessTemp,InocToSubRatio=InocToSubRatio,MeasurementType="AMPTSV2")
  # create an empty BGF of MeasurementType 'AMPTSV2'

  if(isTRUE(feedback)){ 
    m1 <- paste0("New BGF (",name,") initialized...")
    
    message(m1)
    }

  out <- add_bmp_measurement(x = out, path = path, mode = out$ExpParam$MeasurementType,feedback = feedback) # import raw report and extract the data;
  # fills imported data into empty BGF

  out <- cols_to_numeric(out) # convert BioGasData columns to numerics

  out <- close_gaps(out,feedback = feedback) # close gaps in imported volume data

  out$BioGasData$production[grep(TRUE,is.na(out$BioGasData$production))] <- 0 # close gaps in imported flow data

  # give feedback
  if(isTRUE(feedback)){ 
    m1<-paste0("Closed gaps in imported flow data (",name,")...")
  
    message(m1)
         }
  

  out <- netGas(out,feedback = feedback) # subtract blank gas volume (mean) from sample gas volume;
  # thereby correcting blank gas volume based on the mas balance within the reactor

  out <- calc_yield(out,feedback = feedback) # calculate bmp's

  out <- relative_production(out,feedback = feedback) # calculate relative production

  out <- summarize_yield(out,feedback = feedback) # summarize calculated bmp's

  # give feedback
  if(isTRUE(feedback)){ 
    m1 <- paste0("A new BGF (MeasurementType = 'AMPTSV2') was sucessfully created (",name,")!")
  
    message(m1)
    }

  return(out) # return out

}

#'@rdname BGF
#'
#'@param time_col numeric. Indicates the position of the time stamp column in the imported report
#'@param product_col numeric. Indicates the position of the product column (e.g. cumulative biogas volume) in the imported report
#'@inheritParams base::difftime
#'@param RName character. Label to be added to the data of the imported report. Should match a value of `ReactorLayout`
#'@param ... further arguments passed to read.table
#'
#'@details
#' When `from_standard_record` is used to create the `BGF` object any text file storing biogas fermentation data could serve as a template.
#' It is a wrapper to call `read.table` with certain arguments pre-set.
#' These are: dec=".", sep="\\t" and header=TRUE.
#'
#' Such a text file must have a matrix like structure in which each row represents a unique observation.
#' It must have at least two columns. One with the time stamp of the observation (format: `%y-%m-%d %H:%M:%S`).
#' The other one must be an accumulating volume measurement of exhaust gas (biogas) at this moment.
#' Further columns providing additional information (such as pH, temperature or RedOx potential) can be present and will be imported as well.
#'
#'@examples
#'# create a BGF from a minimal external data file
#' from_standard_record(ReactorLayout = "A",
#'         ProcessTemp = 80,
#'         InocToSubRatio = .1,
#'         path = base::system.file("extdata","Fermentation_A.tsv",package = "bgfanalyzer"),
#'         time_col = 1,
#'         product_col = 3)
#'
#'@export

# from_standard_record() ####
from_standard_record=function(ReactorLayout,ProcessTemp,InocToSubRatio,path,time_col,product_col,BlankLabel="Blank",name="new_BGF",units="hours",RName="R1",feedback=FALSE,...){

  out <- BGF(ReactorLayout=ReactorLayout,
                  BlankLabel=BlankLabel,
                  name=name,
                  ProcessTemp=ProcessTemp,
                  InocToSubRatio=InocToSubRatio,
                  MeasurementType="std. report format")
  # create an empty BGF of MeasurementType 'manual'

  if(isTRUE(feedback)){
    m1 <- paste0("New BGF (",name,") initialized...")
    
    message(m1)
    }

  record<-import_standard_record(path,...) # imports standard reoprt

  if(isTRUE(feedback)){ 
    m1 <- paste0("Standard record imported from '",path,"'...")
  
    message(m1)
    }

  record<-calc_FR_time(record,time_col = time_col,units=units) # calculates FR Time

  if(isTRUE(feedback)) {
    m1 <- paste0("Fermentation time in '",units,"' calculated...")
  
    message(m1)
    }
  
  

  out<-sort_standardReport(x = out,rawReport = record,RName=RName,product_col = product_col) # Sorts the imported data into the output object

  if(isTRUE(feedback)) {
    m1 <- paste0("Standard record added to '",name,"'...")
    
    message(m1)
    }

  out<-update_BGF(out)

  return(out)


}