R/support_data_import.R

In bgfanalyzer: Analyze Microbial Biogas Fermentation Data

#' Supportive data import functions
#'
#' A set of internal functions that bridge the data import and object creation when using [from_AMPTSV2_report] or [from_standard_record] to create an `BGF`.
#' These functions are not meant for direct user interaction.
#'
#' The function `add_bmp_mesurement` is called by [from_AMPTSV2_report].
#' It imports a `.csv`-file created by the AMPTS II (BioProcess Control; Lund; Sweden) from a location on the system specified in `path` and adds it to a `BGF` specified in `x`.
#'
#' Internally, `add_bmp_mesurement` calls `read_raw_AMPTSV2_report` to import the external file to a list and then it calls `add_ExpPara`, `add_ExpSetup` and `sort_AMPTSV2_reactors` to transfer the data to the `BGF`.
#'
#' @param x a `BGF`
#' @param path a `path` pointing to an external data file. Either a `.csv`-file generated by the AMPTS II (BioProcess Control; Lund; Sweden), or a text-file with at least biogas production (cumulative volume) and time data.
#' @param mode the mode `add_bmp_measurement` treats the imported data at path. Currently only 'auto' and 'AMPTSV2' are the only implemented options.
#' @param feedback `logic`; if `TRUE` the function will print a textual feedback to the console
#'
#' @returns a `BGF`
#'
#' @examples
#' # create an example BGF
#' myBGF <- BGF(ReactorLayout = c("2*Blank","Cellulose","3*neg ctrl","3*FR1","3*FR2","3*FR3"),
#'               name = "myBGF",
#'               ProcessTemp = 52,
#'               MeasurementType = "AMPTSV2")
#'
#' myBGF # print the BGF
#'
#' # add data from external files
#' myBGF <- add_bmp_measurement(
#'         x = myBGF,
#'         path = base::system.file("extdata","AMPTSV2.csv",package = "bgfanalyzer"))
#'
#' myBGF # print the BGF
#'
#' @export

# add_bmp_measurement() ####
add_bmp_measurement=function(x,path,mode="auto",feedback=FALSE){
  if(isFALSE(class(x)=="BGF")){ # check if 'x' is class BGF
    stop("'x' must be class 'BGF'!",
         call. = FALSE)
  }

  if(mode %in%c("auto","AMPTSV2")){ # check if 'MeasurmentType' is "auto" or "AMPTSV2"
    if(isFALSE(file.exists(path))){ # if true checks if the file  in 'path' exists
      stop("The file specified in argumnet 'path' does not exist!\nCheck 'path' and 'mode' arguments!\nType '?add_measurement' to get additional information.",
           call. = FALSE)
    }

    rawReport=read_raw_AMPTSV2_report(path) # create a rawReport form the file in 'path'

    x<-add_ExpPara(x,rawReport,feedback = FALSE) # apply 'add_ExpPara()'

    x<-add_ExpSetup(x,rawReport,feedback = FALSE) # apply 'add_ExpSetup()'

    x<-sort_AMPTSV2_reactors(x,rawReport,feedback = feedback) # apply 'sort_AMPTSV2_reactors()'

    # give feedback
    if(isTRUE(feedback)){

      m1 <- paste0("Imported data from '",basename(path),"' and added it to ",x$ExpParam$name,"...")

      message(m1)
    }

  }



  return(x) # return an BGF created from the report specified via 'path'
}

#' @rdname add_bmp_measurement
#'
#' @details
#' The function `add_standard_record` is similar to `add_bmp_measurement`, put in this case `path` must point to an external text file with a matrix like data structure.
#' This matrix must have at least two columns, one with information on when the measurement was recorded (`time_col`), the other with a cumulative biogas volume measurement (`product_col`).
#' Additional columns can be present and will be imported as well.
#'
#' Internally, `add_standard_record` calls [import_standard_record] to import the data and next it calls [calc_FR_time] to calculate a standardized fermentation time for the imported data set.
#' Finally, it calls `sort_standardReport` to transfer the imported data to the BGF
#' The function will not remove empty rows resulting from object creation within the BGF.
#' Thus, it is advised to use [update_BGF] to ensure the integrity of the `BGF`.
#'
#' @param header `logic`; does the matrix like structure at `path` has a `header`
#' @param dec a single `character` specifying the decimal separator
#' @param sep a single `character` specifying the column separator
#' @param units the desired unit of the time difference calculated by `calc_FR_time`
#' @param time_col a `character` specifying the name of the column with time information in the external data file
#' @param RName a `character` specifying the reactor name of the biogas fermentation to be added. Defaults to 'R1'
#' @param product_col a `character` specifying the name of the column with the cumulative biogas volume data in the external data file
#'
#' @examples
#' # create another example BGF
#' myBGF2 <- BGF("A")
#'
#' myBGF2 # print the BGF
#'
#' # add data from an external file (standard record)
#' myBGF2 <- add_standard_record(
#'         x = myBGF2,
#'         path = base::system.file("extdata","Fermentation_B.tsv",package = "bgfanalyzer"),
#'         RName = "R1",
#'         time_col = "UTC",
#'         product_col = "GCounter..ml.")
#'
#' myBGF2 # print the BGF
#'
#' @export
#'


# add_standard_record() ####
add_standard_record=function(x,path,header=TRUE,dec=".",sep="\t",units="hours",time_col="time",RName="R1",product_col="GCounter..ml.", feedback=TRUE){
  if(isFALSE(class(x)=="BGF")){ # check if 'x' is class BGF
    stop("'x' must be class 'BGF'!",
         call. = FALSE)
  }

  rawReport<-import_standard_record(path,header=header,dec=dec,sep=sep) # create a rawReport form the file in 'path'

  if(isTRUE(feedback)){

    m1 <- paste0("Standard record imported from '",path,"'...")

    message(m1)

    }

  rawReport <- calc_FR_time(rawReport,time_col=time_col,units=units)

  x <- sort_standardReport(x,rawReport,RName,product_col)

  return(x)
}

#' @rdname add_bmp_measurement
#'
#' @details
#' The function `add_ExpPara` is called by `add_bmp_measurement` and acts as a wrapper for [add_ExpParam] to transfer experimental meta data to a `BGF` object.
#' It expects a `list` created by [read_raw_AMPTSV2_report] as a second argument.
#'
#' @param rawReport either a `list` or a `data.frame` created by `read_raw_AMPTSV2_report` or `import_standard_record`, respectively.
#'
#' @examples
#' # create an additional example BGF
#' myBGF3 <- BGF(c("2*Blank","Cellulose","3*neg ctrl","3*FR1","3*FR2","3*FR3"))
#'
#' myBGF3 # print the BGF
#'
#' # import standard record
#' rawReport <- read_raw_AMPTSV2_report(
#'         path = base::system.file("extdata","AMPTSV2.csv",package = "bgfanalyzer"))
#'
#' # add experimental meta data to BGF
#' myBGF3 <- add_ExpPara(myBGF3,rawReport,TRUE)
#'
#' myBGF3 # print the BGF
#'
#'@export
#'

# add_ExpPara() ####
add_ExpPara=function(x,rawReport,feedback = FALSE){
  if(isFALSE(class(x)=="BGF")){ # check if 'x' is class BGF
    stop("'x' must be class 'BGF'!",
         call. = FALSE)
  }

  for(i in c(1:length(names(rawReport[["ExpPara"]])))){ # copies the elements of "ExpPara" of rawReport to x$ExpParam
    name=names(rawReport[["ExpPara"]])[i] # get the name of the new ExpParam entry
    value=rawReport[["ExpPara"]][i] # get the value of the new ExpParam entry
    names(value)=name # build a name value pair

    x<-add_ExpParam(x,what = value,feedback = feedback) # apply add_ExpParam
  }

  validate_BGF(x) # check integrity of x

  return(x) # return modified x

}

#' @rdname add_bmp_measurement
#'
#' @details
#' Similarly,the function `add_ExpSetup` is also called by `add_bmp_measurement`, but acts as a wrapper for [add_metaData] to transfer fermentation meta data to a `BGF` object.
#' Consequently it also expects a `list` created by [read_raw_AMPTSV2_report] as a second argument.
#'
#' @examples
#' # add fermentation meta data to BGF
#' myBGF3 <- add_ExpSetup(myBGF3,rawReport,TRUE)
#'
#'myBGF3 # print the BGF
#'
#'@export
#'

# add_ExpSetup() ####
add_ExpSetup=function(x,rawReport,feedback=FALSE){
  if(isFALSE(class(x)=="BGF")){ # check if 'x' is class BGF
    stop("'x' must be class 'BGF'!",
         call. = FALSE)
  }

  for (i in c(1:length(rawReport[["ExpSetup"]]))) { # apply 'add_metaData()' to each element of "ExpSetup"
    x <- add_metaData(x = x,what = rawReport[["ExpSetup"]][,i],lab = names(rawReport[["ExpSetup"]])[i],feedback = feedback)
  }

  validate_BGF(x) # check integrity of x

  return(x) # return modified x
}

#' @rdname add_bmp_measurement
#'
#' @details
#' In addition, `sort_AMPTSV2_reactors` is also called by `add_bmp_measurement` and acts as a wrapper for [add_BG_measurement] and [alter_BG_measurement] to transfer cumulative biogas volume and biogas flow data to a `BGF`.
#' Like the former two functions, it expects a `list` generated via `read_raw_AMPTSV2_report` as second argument
#'
#' @examples
#' # add biogas volume and flow data
#' myBGF3 <- sort_AMPTSV2_reactors(myBGF3,rawReport)
#'
#'myBGF3 # print the BGF
#'
#'@export
#'

# sort_AMPTSV2_reactors() ####
sort_AMPTSV2_reactors=function(x,rawReport,feedback=FALSE){
  if(isFALSE(class(x)=="BGF")){ # check if 'x' is class BGF
    stop("'x' must be class 'BGF'!",
         call. = FALSE)
  }

  ExpData<-as.data.frame(rawReport[["ExpData"]]) # extract "ExpData"
  nc_Exp<-ncol(ExpData) # get the nr of columns in "ExpData"
  nr_Exp<-nrow(ExpData) # get the nr of rows in "ExpData"

  for(i in c(1:nr_Exp)){ # for each row in "ExpData"
    for(j in c(1:((nc_Exp-1)/2))){ # take a sample gas column of "ExpData"
      R_name=paste0("R",j) # generate a suited reactor name
      x<-add_BG_measurement(x,R_name,ExpData[i,1],"product",ExpData[i,j+1],feedback = feedback) # add the measurement to x$BioGasData
      x<-alter_BG_measurement(x,R_name,ExpData[i,1],"production",ExpData[i,j+16],feedback = feedback) # alter the respective x$BioGasData$flow
    }}

  x$BioGasData$reactor = factor(x$BioGasData$reactor,levels = rownames(x$metaData))

  return(x) # return modified  x

}

#' @rdname add_bmp_measurement
#'
#' @details
#' Additional details...
#'
#' @examples
#' # create an empty example BGF
#' myBGF4 <- BGF("myBGF4")
#'
#' myBGF4 # print the BGF
#'
#' # import a standard record
#' rawReport2 <- import_standard_record(
#'         ipath = base::system.file("extdata","Fermentation_B.tsv",package = "bgfanalyzer"))
#'
#' # calculate a fermentaion/ observation time
#' rawReport2<-calc_FR_time(rawReport2,1,units="hours")
#'
#' # add imported data to BGF
#' myBGF4 <- sort_standardReport(myBGF4,rawReport2,"R1",3)
#'
#' myBGF4 # print BGF
#'
#'@export
#'

# sort_standardReport() ####
sort_standardReport=function(x,rawReport,RName,product_col){
  x$BioGasData$reactor=as.character(x$BioGasData$reactor)

  rep_time=grep("time",colnames(rawReport))
  if(is.character(product_col)) product_col=grep(product_col,colnames(rawReport))

  further_cols=colnames(rawReport)[-c(rep_time,product_col)]
  x$BioGasData[,subset(further_cols,further_cols%in%colnames(x$BioGasData)==FALSE)]=NA


  for(i in c(1:nrow(rawReport))){
    x$BioGasData[nrow(x$BioGasData)+1,c("reactor","time","product")]=c(RName,rawReport[i,c(rep_time,product_col)])

    x$BioGasData[nrow(x$BioGasData),further_cols]=rawReport[i,further_cols]
  }

  x$BioGasData$reactor=as.factor(x$BioGasData$reactor)

  return(x)
}