R/readCLASSfile.R

In CentreForHydrology/CRHMr: Pre- and post- processing for CRHM

#' Reads forcing data from CLASS formatted file
#' @description Reads data from files created for CLASS into a stanard \pkg{CRHMr} obs data frame.
#' @param CLASSfile Required. File of meteorological data in CLASS format.
#' @param timezone Required. The name of the timezone of the data as a character string. This should be the timezone of your data, but omitting daylight savings time. Note that the timezone code is specific to your OS. To avoid problems, you should use a timezone without daylight savings time. Under Linux, you can use \option{CST} and \option{MST} for Central Standard or Mountain Standard time, respectively. Under Windows or OSX, you can use \option{etc/GMT+6} or \option{etc/GMT+7} for Central Standard and Mountain Standard time. DO NOT use \option{America/Regina} as the time zone, as it includes historical changes between standard and daylight savings time.
#' @param convertNames Optional. If \code{TRUE}, then the CLASS variables will be converted to \code{Qsi.1}, \code{Qli.1}, \code{p.1}, \code{t.1}, \code{ea.1}, \code{u.1}, and \code{AirPressure.1}. Otherwise, the CLASS names \code{SWin}, \code{LWin}, \code{Prec}, \code{T}, \code{qa}, \code{U}, and \code{P} will be used.
#' @param quiet Optional. Suppresses display of messages, except for errors. If you are calling this function in an \R script, you will usually leave \code{quiet=TRUE} (i.e. the default). If you are working interactively, you will probably want to set \code{quiet=FALSE}.
#' @param logfile Optional. Name of the file to be used for logging the action. Normally not used.
#'
#' @return If successful, returns a \pkg{CRHMr} data frame. If unsuccessful, returns the value \code{FALSE}.
#' @author Kevin Shook, with assistance from Andrew Ireson.
#' @export
#'
#' @examples \dontrun{
#' class <- readCLASSfile('driv.met', timezone='Etc/GMT+7')}
readCLASSfile <- function(CLASSfile='', timezone='', convertNames=TRUE, quiet=TRUE, logfile=''){
  if (CLASSfile == ''){
    cat('Error: must specify file name\n')
    return(FALSE)
  }
  
  if (timezone == ''){
    cat('Error: must specify a timezone\n')
    return(FALSE)
  }
  
  CLASS <- read.table(file=CLASSfile, header=FALSE, stringsAsFactors = FALSE)
  names(CLASS) <- c('hour', 'min', 'daynum', 'year','Qsi', 'Qli', 'Prec', 'T', 'qa', 'U', 'P')

  # convert to datetime
  datetime <- paste(CLASS$year,'-', CLASS$daynum,' ', CLASS$hour,':', CLASS$min, sep='')
  datetime <- as.POSIXct(datetime, format='%Y-%j %H:%M',tz=timezone)
  
  CLASS <- CLASS[,c(5:11)]
  CLASS <- cbind(datetime, CLASS)
  
  if(convertNames)
    names(CLASS)[2:8] <- c('Qsi.1', 'Qli.1', 'p.1', 't.1', 'ea.1', 'u.1', 'AirPressure.1')
  
  # output info to screen (if req'd) and write to log file
  file.info <- CRHM_summary(CLASS)
  if (!quiet)
    print(file.info)
  
  comment <- paste('readCLASSfile CLASSfile:',CLASSfile, ' timezone:', timezone, sep='')
  result <- logAction(comment, logfile)
  
  if(result)
    return(CLASS)
  else
    return(result)
}