dev/AQSearch.Parameters.R

In hutchr/LLSR: Data Analysis of Liquid-Liquid Systems using R

####################################################################################################################
#' @rdname AQSearch.Parameters
#' @name AQSearch.Parameters
#' @description This function allow the user to search the LLSR database to find any ATPS that matches the used criteria.
#' @export
####################################################################################################################
AQSearch.Parameters <- function(db = LLSR::llsr_data, db.ph = NULL, db.upper = NULL, db.lower = NULL,
                     db.temp = NULL, db.addtl = NULL, ...)
  UseMethod("AQSearch.Parameters")
####################################################################################################################
#' @rdname AQSearch.Parameters
#' @title Search function for ATPS Systems data
#' @description This function allow the user to search the package database to find any ATPS that matches the used criteria.
#' @details The function return the systems that matches the criteria submit by the user. 
#' @param db A highly structure db containing data from previously analised data. LLSR database is used by default but user may input his own db if formatted properly.
#' @param db.ph A numeric variable containing the pH to be searched within DB.
#' @param db.upper A String variable containing either the CAS, chemical formula or name of the upper phase enriched component..
#' @param db.lower A String variable containing either the CAS, chemical formula or name of the lower phase component.
#' @param db.temp A numeric variable containing the Temperature (in Kelvin) to be searched within DB.
#' @param db.addtl A String variable containing either the CAS, chemical formula or name of the additive component.
#' @param db.uid An Unique md5 hash Identification. User can retrieve data for a specific system if in possesion of its UID.
#' @param ... Additional optional arguments. None are used at present.
#' @method AQSearch Parameters
#' @export
#' @return Returns a data.frame containing system's parameters which match searched conditions
#' @examples
#' \dontrun{
#' AQSearch.Parameters(db.upper="Ammonium")
#'}
####################################################################################################################
AQSearch.Parameters <- function(db = LLSR::llsr_data, db.ph = NULL, db.upper = NULL, db.lower = NULL,
           db.temp = NULL, db.addtl = NULL, db.uid = NULL, ...) {
    # db <- LLSR::llsr_data
    # initialize db.ans
    db.ans <- list()
    db.uids <- NULL
    # create and initialise a list using the function's parameters
    db.params <- c(db.ph, db.upper, db.lower, db.temp, db.addtl, db.uid)
    # if all parameters are null, the search is not valid and it triggers an error (check AQSys.err.R for details)
    if (all(unlist(lapply(db.params, is.null))))
      AQSys.err("6")
    # each conditional will return a result set that excludes no match data.
    # search a system that matchs the upper-phase component, if search parameter is not null.
    for (modelName in AQSysList()){
      # output variable is initialised with data from db.
      db.grep <- db$db.sys[[modelName]]
      if (!is.null(db.upper)) {
          db.upper.altNames <- db$db.cas[grep(db.upper, db$db.cas$CHEM.COMMON, ignore.case = TRUE), "CHEM.NAME"]
          db.upper.cas <- db$db.cas[grep(db.upper, db$db.cas$CAS.CODE, ignore.case = TRUE), "CHEM.NAME"]
          db.grep <- db.grep[unique(c(grep(db.upper, db.grep$A, ignore.case = TRUE), 
                                           which(tolower(db.grep$A) %in% db.upper.altNames),
                                           which(tolower(db.grep$A) %in% db.upper.cas))),]
      }
      # search a system that matchs the lower-phase component, if search parameter is not null.
      if (!is.null(db.lower)) {
        db.lower.altNames <- db$db.cas[grep(db.lower, db$db.cas$CHEM.COMMON, ignore.case = TRUE), "CHEM.NAME"]
        db.lower.cas <- db$db.cas[grep(db.lower, db$db.cas$CAS.CODE, ignore.case = TRUE), "CHEM.NAME"]
        db.grep <- db.grep[unique(c(grep(db.lower, db.grep$B, ignore.case = TRUE), 
                                         which(tolower(db.grep$B) %in% db.lower.altNames),
                                         which(tolower(db.grep$B) %in% db.lower.cas))),]
      }
      # search a system that matchs the system's pH, if search parameter is not null.
      if (!is.null(db.ph)) {
        db.grep <- db.grep[grep(db.ph, db.grep[,4]),]
      }
      # search a system that matchs the additive component, if search parameter is not null.
      if (!is.null(db.addtl)) {
        db.addtl.altNames <- db$db.cas[grep(db.addtl, db$db.cas$CHEM.COMMON, ignore.case = TRUE), "CHEM.NAME"]
        db.addtl.cas <- db$db.cas[grep(db.addtl, db$db.cas$CAS.CODE, ignore.case = TRUE), "CHEM.NAME"]
        db.grep <- db.grep[unique(c(grep(db.addtl, db.grep$C, ignore.case = TRUE), 
                                         which(tolower(db.grep$C) %in% db.addtl.altNames),
                                         which(tolower(db.grep$C) %in% db.addtl.cas))),]
      }
      # search a system that matchs the system's temperature, if search parameter is not null.
      if (!is.null(db.temp)) {
        db.grep <- db.grep[grep(db.temp, db.grep[,7]),]
      }
      # search a system that matchs the system's UID, if search parameter is not null.
      if (!is.null(db.uid)) {
        db.grep <- db.grep[db.grep$UID == db.uid,]
      }
      if (nrow(db.grep) != 0) {
        # db.grep[, 1] <- as.data.frame(sapply(db.grep[, 1], undigest))
        # names(db.grep)[1] <- "REFERENCE"
        db.ans[["Parameters"]][[modelName]] <- db.grep
        db.uids <- rbind(db.uids, db.grep[, c("UID", "REF.MD5")])
        #
        print(paste("[", modelName, "] ", "Your search had [", nrow(db.grep), "] results.", sep = ""))
      } else {
        print(paste("[", modelName, "] ", "Your search had no results.", sep = ""))
      }
    }
    #
    db.ans.ext <- matchRefEntry(db, db.uids)
    #
    if (nrow(db.ans.ext$slopes)) {
      db.ans[["Slopes"]] <- db.ans.ext$slopes
    }
    if (nrow(db.ans.ext$tielines)) {
      db.ans[["Data"]][["TieLines"]] <- db.ans.ext$tielines
    }
    if (ncol(db.ans.ext$binodals)) {
      db.ans[["Data"]][["Binodals"]] <- db.ans.ext$binodals
    }
    # If search isn't null, evaluate data
    if (length(db.ans) != 0)  {
     invisible(db.ans)
      #
    }else{
      # Triggers an "no results" error
      AQSys.err("5")
    }

  }