R/changeFMDBNames.R

In droglenc/fishWiDNR: Support for Wisconsin DNR Fisheries Analyses

#' @title Change type of variable names in Wi Fish Management Data
#' 
#' @description Change type of variable names in Wi Fish Management Data.
#' 
#' @details This function can change variable names in a data frame consisting of Wi Fish Management Data.  The three formats allowed are as follows:
#' \itemize{
#'   \item \code{"DNR"} -- \dQuote{long} names directly from the FM database.  These variable names have spaces as would appear when the database output is read into R with \code{read.table} or \code{read.csv} using \code{check.names=FALSE}.
#'   \item \code{"RDNR"} -- \dQuote{long} names as from the FM database but with spaces replaced by periods.  These variable names would appear when the database output is read into R with \code{read.table} or \code{read.csv} using \code{check.names=TRUE} (the default of those functions).
#'   \item \code{"R"} -- \dQuote{short} names for ease of use in R scripts.
#' }
#' 
#' @param df The data.frame that contains the Wi Fish Management Data (likely directly from the FM database).
#' @param from A single string that indicates the variable name type that currently exists in \code{df} (and the user wants to convert \dQuote{from}).
#' @param to A single string that indicates the variable name type that the user wantes to convert the variable names in \code{df} \dQuote{to}.
#' @param check.names A single logical that indicates whether the resulting names should be checked to ensure that they are syntactically valid variable names (for R).  If necessary they will be adjusted (by \code{make.names}) so that they are syntactically correct, and also to ensure that there are no duplicate variable names.
#' @param \dots Not yet implemented.
#' 
#' @return A data.frame exactly as in \code{df} but with new names.
#' 
#' @author Derek H. Ogle, \email{dogle@@northland.edu}
#' 
#' @keywords manip
#'
#' @examples
#' \dontrun{
#' ftmp <- system.file("extdata", "FMDB_ex.csv",package="fishWiDNR")
#' ## Read in datafile (note periods in names) ... this is RDNR type of data
#' df <- read.csv(ftmp,stringsAsFactors=FALSE,na.strings="-")
#' df <- setFMDBClasses(df,type="RDNR")
#' str(df)
#' 
#' ## test from RDNR to R (these are the defaults)
#' dfR <- changeFMDBNames(df)
#' data.frame(names(df),names(dfR))
#' 
#' ## test from R back to RDNR
#' dfRDNR <- changeFMDBNames(dfR,from="R",to="RDNR")
#' data.frame(names(df),names(dfR),names(dfRDNR))
#' all(names(df)==names(dfRDNR))
#' 
#' ## test from RDNR to DNR
#' dfDNR <- changeFMDBNames(df,from="RDNR",to="DNR")
#' data.frame(names(df),names(dfDNR))
#' 
#' ## Check names (same as changing to RDNR)
#' dfRDNR1 <- changeFMDBNames(dfR,from="R",to="DNR",check.names=TRUE)
#' data.frame(names(dfR),names(dfRDNR),names(dfRDNR1))
#' all(names(dfRDNR)==names(dfRDNR1))
#' 
#' ## test from partial list of RDNR names to R
#' df2 <- df[,-c(1,4,7,10,16,32:47)]
#' df2R <- changeFMDBNames(df2)
#' data.frame(names(df2),names(df2R))
#' ## ... and back ...
#' df2RDNR <- changeFMDBNames(df2R,from="R",to="RDNR")
#' data.frame(names(df2),names(df2R),names(df2RDNR))
#' all(names(df2)==names(df2RDNR))
#' 
#' ## test from variables not in VarLookup of RDNR names to R
#' ## variables at the end
#' df3 <- df
#' df3$junk <- 7
#' df3$junk2 <- "Derek"
#' df3R <- changeFMDBNames(df3)
#' data.frame(names(df3),names(df3R))
#' 
#' ## variables at the beginning
#' nc <- ncol(df3)
#' df4 <- df3[,c(nc-1,nc,1:(nc-2))]
#' df4R <- changeFMDBNames(df4)
#' data.frame(names(df4),names(df4R))
#' 
#' ## variables in the middle and separated
#' df5 <- df3[,c(1:10,nc-1,11:20,nc,21:(nc-2))]
#' df5R <- changeFMDBNames(df5)
#' data.frame(names(df5),names(df5R))
#'
#' ## Read in datafile (use check.names to allow spaces in names) ... this is DNR type of data
#' df1 <- read.csv(ftmp,stringsAsFactors=FALSE,check.names=FALSE,na.strings="-")
#' df1 <- setFMDBClasses(df1,type="DNR")
#' str(df1)
#' 
#' ## test from DNR to R
#' df1R <- changeFMDBNames(df1,from="DNR")
#' data.frame(names(df1),names(df1R))
#' 
#' ## test from R back to DNR
#' df1DNR <- changeFMDBNames(df1R,from="R",to="DNR")
#' data.frame(names(df1),names(df1R),names(df1DNR))
#' all(names(df1)==names(df1DNR))
#' }
#' 
#' ## Check error message
#' \dontrun{
#' dfbad <- changeFMDBNames(df2,from="R",to="R")
#' }
#' 
#' @export changeDBNames
#' @rdname changeFMDBNames
changeDBNames <- function(df,from=c("RDNR","R","DNR"),to=c("R","RDNR","DNR"),check.names=FALSE,...) {
  warning("'changeDBNames()' is deprecated.  Use 'changeFMDBNames()' instead.",call.=FALSE)
  changeFMDBNames(df,from,to,check.names,...)
}

#' @export changeFMDBNames
#' @rdname changeFMDBNames
changeFMDBNames <- function(df,from=c("RDNR","R","DNR"),
                            to=c("R","RDNR","DNR"),check.names=FALSE,...) {
  # match arguments and do some error checking
  from <- match.arg(from)
  to <- match.arg(to)
  if (from==to) stop("The 'from' and 'to' values can NOT be the same.",call.=FALSE)
  # load VarLookup data frame into this function's environment
  # the data/get combination are used to avoid the "no global binding" note at CHECK
  VarLookup <- get(utils::data("VarLookup", envir = environment()), envir = environment())
  # find which rows in VarLookup 'from' column match names in the df
  #  may contain some NAs if df has variables not in VarLookup ... remove the NAs
  #  unique() is used because some R values map to multiple RDNR or DNR values
  tmp <- match(names(df),VarLookup[,from])
  tmp <- unique(tmp[!is.na(tmp)])
  # replace the df names with the rows from the 'to' column that matched above
  #  first find which rows in df actually appeared in VarLookup
  tmp2 <- match(VarLookup[,from],names(df))
  tmp2 <- unique(tmp2[!is.na(tmp2)])
  names(df)[tmp2] <- as.character(VarLookup[tmp,to])
  # check names if asked to do so
  if (check.names) names(df) <- make.names(names(df),unique=TRUE)
  # return the data frame with the new names
  df
}