R/factorChange.R

In lwTools/agriTrf: Agricultural Transformation Package: data management, depiction and modelling

#' factorChange
#' @param dfData a data.frame object to be used. Note that this is not a character string but the data.frame object itself. The parameter passed to the function should be without quotes (" ").
#' @param dfColNameVec a string or a vector of class character indicating the name(s) of the column(s) to be handled. All these columns belong to the class factor.
#' @param levelList an object of class list containing character vectors of the ordered levels for the columns in dfColNameVec. If a list with only one vector is provided, that vector is used for the levels reference of all columns in dfColNameVec. It is important that an object of class list is passed, even if it contains only one vector. Passing a single vector of class character gives incorrect results.
#' @param orderList a list object containing the order of the levels of the columns in \code{dfColNameVec}. If nothing is specified (i.e. missing \code{orderList}) then the default ordering (1:n) is used.
#' @param outputFormat a character string (default: "beside") indicating whether to insert the new columns right after the respective columns (outputFormat: "beside") or append them at the end of the data.frame object \code{dfData}. 
#' @param suffix a string (default: "M") of class character indicating the suffix to be added to the original column name to obtain the column name for the new column with updated factors. 
#' @param envir a variable (default: .GlobalEnv) indicating the environment where the output data.frame object should be saved.
#' @return factorChange returns the modified data.frame object with updated entries for the columns in \code{dfColNameVec}. The function changes the levels of these columns to the values specified in the list \code{levelList}.
#' @description factorChange takes as input a data.frame object (\code{dfData}), a vector of column names (\code{dfColNameVec}), a list of vectors of ordered levels (\code{levelList}) one for each column in \code{dfColNameVec} and modifies the nomenclature and order of the levels of column(s) in the data.frame object \code{dfData}. For this function, first the user needs to check the levels of each column in \code{colNameVec} and then decide the new values that are to be used and choose an ordering scheme for the levels of each column. E.g. if the original levels are ("A","B","C"), and the user wants to order them as ("C","A","B"), then the user needs to specify orderList = c(3,1,2).
#' @examples
#' factorChange(dfData,c("col1","col2"),c("low","medium", "high"))
#' factorChange(iris,"Species",list(c("species-A","species-B","species-C")), list(c(1,3,2)))
#' factorChange(iris,"Species",list(c("species-A","species-B","species-C")),list(c(3,1,2)))
#' @export
factorChange<-function(dfData,dfColNameVec,levelList,orderList,outputFormat="beside",suffix="M",envir=.GlobalEnv)
{
  dfName<-deparse(substitute(dfData))
  
  if(length(levelList)==1)
  {
    levelList<-rep(levelList,length(dfColNameVec))
  }
 
 
  if(missing(orderList))
  {
    orderList<-list(c(1:length(unique(levelList[[1]]))))
  }
  
  if(length(orderList)==1)
  {
    orderList<-rep(orderList,length(dfColNameVec))
  }
   
  for (i in 1:length(dfColNameVec))
  {
    dfCol<-levelList[[i]][match(dfData[,dfColNameVec[i]],levels(dfData[,dfColNameVec[i]]))]
    dfCol<-factor(dfCol,unique(levelList[[i]])[match((1:length(unique(levelList[[i]]))),orderList[[i]])])
    dfCol<-as.data.frame(dfCol)
    names(dfCol)<-paste(dfColNameVec[i],suffix,sep="")
    
    
    if( outputFormat=="beside")
    {
      dfData<-as.data.frame(append(dfData,dfCol,after=loc.col(dfData,dfColNameVec[i])[[2]]))
    }else
    {
      dfData<-cbind(dfData,dfCol)
    }
  }
  
  assign(dfName,dfData,envir=envir)
}