R/data_import.R

In bgfanalyzer: Analyze Microbial Biogas Fermentation Data

#' Data import functions
#'
#' The `bgfanalyzer` package has three data import functions.
#' Two are called internally by the helper functions [from_standard_report][bgfanalyzer::BGF] or [from_AMPTV2_report][bgfanalyzer::BGF] when creating a new `BGF` object.
#' The third allows to import a `BGF` object, that was previously exported from R.
#'
#' Two of the three data import functions, `import_standard_record` and `read_raw_AMPTSV2_report` are unlikely to be directly called by a package user.
#' Instead, they are called by `from_standard_record` or `from_AMPTSV2_report`, respectively, when importing an external data file.
#'
#' The first import function `import_standard_record` is more than a wrapper for [read.table] with the arguments dec=".", sep="\\t" and header=TRUE pre-set.
#' It furthermore allows to calculate a fermentation time directly when importing the data.
#' To this end, `mkFRTime` must be a `character` string representing a date in the format %y-%m-%d %H:%M:%S, `FRTime_col` an `integer` specifying the position of the time stamp within the data, and `units` must be a `character` specifying the desired [units][difftime] of the calculated fermentation time.
#'
#' In case of `import_standard_record` a `data.frame` is returned.
#'
#'@param ipath,path a path pointing to an external file
#'@param mkFRTime NULL by default. Can be a character string representing a start date (%y-%m-%d %H:%M:%S) for the calculation of the fermentation time
#'@param FRTime_col NULL by default. Can be a character string with the name, or an integer representing the position of the date column after the input file was read via read.table.
#'@inheritParams utils::read.table
#'@inheritParams base::difftime
#'
#'@returns Either a data.frame, a list or a BGF
#'
#'@examples
#'# import biogas fermentation from a .tsv file
#' stRep <- import_standard_record(
#'       ipath = base::system.file("extdata","Fermentation_B.tsv",package ="bgfanalyzer"),
#'       header=TRUE,
#'       dec=".",
#'       sep="\t")
#'
#'# calculate a fermentation time while importing the data
#' stRep_frt <- import_standard_record(
#'         ipath = base::system.file("extdata","Fermentation_B.tsv",package ="bgfanalyzer"),
#'         header=TRUE,
#'         dec=".",
#'         sep="\t",
#'         mkFRTime = "2026-01-29 23:00:00",
#'         FRTime_col = 2,
#'         units = "hours")
#'
#'@export
#'

# import_standard_record() ####
import_standard_record=function(ipath,dec=".",sep="\t",header=TRUE,mkFRTime=NULL,FRTime_col=NULL,units=NULL,...){

  df<-utils::read.table(ipath,dec = dec,sep = sep,header = header,...)

  if(isFALSE(is.null(mkFRTime))){
    mkFRTime <- as.POSIXct(mkFRTime)
    df[,"time"]=difftime(df[,{{FRTime_col}}],mkFRTime,units = units)
  }

  return(df)
}

#'@rdname import_standard_record
#'
#'@details
#' The function `read_raw_AMPTSV2_report` calls [readLines] and expects a relative `path` to a `report_yyyy-mm-dd_HHMM.csv`-file generated by the AMPTS II web interface (Login > Download report > Generate report > Download generated report as raw text file (CSV)).
#' **The function expects the original file generated by the AMPTS II**, NOT a .CSV version previously opened and saved by other software as this will replace the original AMPTS II-generated formatting the downstream function is build on.
#' The argument `sub` is used in a call to [gsub], which is needed to eliminate an artifact character introduced by calling `readLines`.
#' Upon artifact elimination the raw data is converted into a `list` of three:
#'
#' **ExpPara**: A `list`. Information concerning the all reactors part of the AMPTS II experiment. Serves as template for `ExpParam` of a `BGF`
#'
#' **ExpSetup**: A `data.frame`. Information on individual reactors being part of the AMPTS II experiment. All information collected here will be added to metaData of a BGF
#'
#' **ExpData**: A `data.frame`. Biogas volumes and flow data of the AMPTS II experiment. This data will be moved to `BioGasData` of a `BGF`
#'
#' This list is returned by `read_raw_AMPTSV2_report`.
#'
#'@param sub a `character`, which will be eliminated from the read in text connection
#'
#'@examples
#'
#'# create a list that can be used as a template to build a BGF
#' RawReport <- read_raw_AMPTSV2_report(
#'         path = base::system.file("extdata","AMPTSV2.csv",package ="bgfanalyzer"))
#'
#' @export
#'

# read_raw_AMPTSV2_report() ####
read_raw_AMPTSV2_report=function(path,sub="\\\""){
  rawFile <- readLines(path) # read the report file line by line

  rawFile <- gsub(sub,"",rawFile) # correct read vector

  tmp<-NULL # create tmp vector
  tmp_name<-NULL # create tmp_name vector

  for (i in c(1:6)) { # Extract 'ExpPara' from AMPTS report
    tmp<-c(tmp,strsplit(rawFile[1:6],",")[[i]][2])
    tmp_name<-c(tmp_name,strsplit(rawFile[1:6],",")[[i]][1])
  }

  names(tmp)<-tmp_name # link tmp and tmp_name

  out<-list("ExpPara"=tmp) # add extracted data (tmp) to output list

  out[["ExpSetup"]]=as.data.frame(matrix(unlist(strsplit(rawFile[8:14],",")),ncol  = 7)) # Extract 'ExpSetup' from AMPTS report
  colnames(out[["ExpSetup"]])<-out[["ExpSetup"]][1,] # adjust colnames
  out[["ExpSetup"]]=out[["ExpSetup"]][-1,] # remove namings from data
  rownames(out[["ExpSetup"]])<-paste0("R",c(1:length(rownames(out[["ExpSetup"]])))) # adjust row names

  out[["ExpData"]]=as.data.frame(t(matrix(unlist(t(strsplit(rawFile[16:length(rawFile)],","))),ncol = length(rawFile[16:length(rawFile)])))) # Extract 'ExpSData' from AMPTS report
  colnames(out[["ExpData"]])<-out[["ExpData"]][1,] # adjust colnames
  out[["ExpData"]]=out[["ExpData"]][-1,] # remove colnames form data

  out[["ExpPara"]]<-c(out[["ExpPara"]],"timeScale"=colnames(out[["ExpData"]])[1]) # add 'timeScale' to 'ExpPara'

  return(out) # return output
}

#' @rdname import_standard_record
#'
#' @details
    #' The third data import function, `import_BGF_object` allows to import a `BGF` from either an [.RDS-file][saveRDS] or an .csv-file as produced by [save_BGF].
#' A detailed format description of the .csv-file this function can read can be found [elsewhere][save_BGF].
#' The function expects a `path` to a file as a single argument.
#' It will check the ending of the file path.
#' If it's '.csv', a `BGF` is rebuild based on the read in data.
#' Else the function  serves as a wrapper to `readRDS`.
#' Consequently, a `BGF` is returned.
#'
#'@examples
#'
#'
#'# import a BGF from a '.csv'-file
#' BGF_csv <- import_BGF_object(
#'       path = base::system.file("extdata","importable_BGF_object.csv",package = "bgfanalyzer"))
#'
#'# import a BGF from a '.RDS'-file
#' BGF_rds <- import_BGF_object(
#'       path = base::system.file("extdata","importable_BGF_object.RDS",package = "bgfanalyzer"))
#'
#' @export
#'

# import_BGF_object() ####
import_BGF_object=function(path){
  if(endsWith(path,".csv")){

    raw<-readLines(path)
    sections<-grep("BioGasFermentation",raw)

  ExpPara=raw[c((sections[1]+2):(sections[2]-2))]

  ExpSetup=raw[c((sections[2]+2):(sections[3]-2))]

  ExpData=raw[c((sections[3]+2):length(raw))]

  data<-list("ExpPara"=list(),
             "ExpSetup"=data.frame(matrix(nrow =as.numeric(strsplit(raw[sections[2]],",")[[1]][2]),
                                          ncol = length(strsplit(ExpSetup[1],",")[[1]])-1)),
             "ExpData"=data.frame(matrix(nrow =as.numeric(strsplit(raw[sections[3]],",")[[1]][2]),
                                         ncol = length(strsplit(ExpData[1],",")[[1]])-1)))

  colnames(data[["ExpSetup"]])<-subset(strsplit(ExpSetup[1],",")[[1]],strsplit(ExpSetup[1],",")[[1]]!="Row")
  colnames(data[["ExpData"]])<-subset(strsplit(ExpData[1],",")[[1]],strsplit(ExpData[1],",")[[1]]!="Row")


  for(i in ExpPara){
    a=strsplit({{i}},",")[[1]][1]
    b=strsplit({{i}},",")[[1]][2]

    data[["ExpPara"]][[{{a}}]]={{b}}
  }

  for(i in c(2:length(ExpSetup))){
  a=strsplit(ExpSetup[{{i}}],",")[[1]]
  b=a[1]
  c=a[2:length(a)]
  data$ExpSetup[b,]=c
  data$ExpSetup=stats::na.omit(data$ExpSetup)
  }

  for(i in c(2:length(ExpData))){
    a=strsplit(ExpData[{{i}}],",")[[1]]
    b=a[1]
    c=a[2:length(a)]
    data$ExpData[b,]=c
    data$ExpData=stats::na.omit(data$ExpData)
  }

  data$ExpData$reactor<-as.numeric(data$ExpData$reactor)
  data$ExpData$reactor<-as.factor(data$ExpData$reactor)

  levels(data$ExpData$reactor)=row.names(data$ExpSetup)

  for(i in c(1:length(row.names(data$ExpSetup)))){
    a=row.names(data$ExpSetup)[i]


  }

  names(data)<-c("ExpParam","metaData","BioGasData")
  class(data)="BGF"
  x<-update_BGF(data)

    }else{
    x<-readRDS(path)
  }

  return(x)
}