R/read.FMDB.R

In droglenc/fishWiDNR: Support for Wisconsin DNR Fisheries Analyses

#' @title Read CSV of WiDNR Fish Management Data.
#' 
#' @description Reads a CSV of WiDNR Fish Management Data, sets variable classes, and optionally adds some variables and expands fish counts.
#' 
#' @details This function is used to read a CSV created directly from the WiDNR Fish Management Database and appropriately set the class type (e.g., integer, factor, etc.) for the  variables.  Optionally, the user may add the month the fish was collected and change the species names so that only the first letters are capitalized (so as to work more easily with other functions).  Furthermore, the user may optionally choose to expand the counts of fish of the same lengths (often times no length was recorded, fish were just counted).
#' 
#' @param file The name of the external CSV file from the WiDNR Fisheries Management Database.
#' @param addSpecies A logical that indicates whether a new variable of species names where only the first word is capitalized should be added to the returned data.frame.
#' @param addMonth A logical that indicates whether a new variable of month of capture should be added to the returned data.frame.
#' @param expandCounts A logical that indicates whether counts of fish of the same length should be expanded to be individual fish in the returned data.frame or not.  See \code{\link[FSA]{expandCounts}} in \pkg{FSA}.
#' @param whichLengths A character string that indicates whether the expanded lengths, when \code{expandCounts=TRUE}, use the English (inches; \code{whichLengths="in"}) or metric (mm; \code{whichLengths="mm"}) units variable.
#' @param lprec	A single numeric that controls the precision to which the random lengths are recorded. See details in \code{\link[FSA]{expandCounts}} in \pkg{FSA}.
#' @param na.strings A vector of character strings that indicate what type of characters should be considered missing when reading the CSV file.  Likely does not need to be changed.
#' @param verbose A logical that indicates whether progress messages should be printed or not.
#' @param \dots Not yet implemented.
#' 
#' @return A data.frame.
#'
#' @seealso \code{\link{setFMDBClasses}}; \code{\link[FSA]{expandCounts}} in \pkg{FSA}.
#' 
#' @author Derek H. Ogle, \email{dogle@@northland.edu}
#' 
#' @keywords manip
#'
#' @examples
#' ## Get external file (as part of the package)
#' ftmp <- system.file("extdata", "FMDB_ex.csv",package="fishWiDNR")
#' 
#' ## Read file without expanding counts
#' df1 <- read.FMDB(ftmp)
#' str(df1)
#' 
#' ## Read file with expanding counts
#' df2 <- read.FMDB(ftmp,expandCounts=TRUE)
#' str(df2)
#' 
#' @export
read.FMDB <- function(file,addSpecies=TRUE,addMonth=TRUE,
                      expandCounts=FALSE,whichLengths=c("in","mm"),lprec=0.1,
                      na.strings=c("-","NA",""),verbose=TRUE) {
  d <- utils::read.csv(file,stringsAsFactors=FALSE,na.string=na.strings)
  if (verbose) message("Successfully read ",file,".",sep="")
  d <- setFMDBClasses(d,type="RDNR")
  if (verbose) message("Set variable classes.")
  if (addMonth) {
    d$Mon <- lubridate::month(d$Survey.Begin.Date,label=TRUE)
    if (verbose) message("Created months in 'Mon'.")
  }  
  if (addSpecies) {
    d$Species1 <- FSA::capFirst(d$Species)
    if (verbose) message("Renamed species in 'Species1'.\n")
  }
  if (expandCounts) {
    whichLengths <- match.arg(whichLengths)
    if (whichLengths=="in") {
      d <- FSA::expandCounts(d,~Number.of.Fish,~Length.or.Lower.Length.IN+Length.Upper.IN,
                             lprec=lprec,new.name="Len",verbose=verbose)
    } else {
      d <- FSA::expandCounts(d,~Number.of.Fish,~Length.or.Lower.Length.MM+Length.Upper.MM,
                             new.name="Len")
    } 
  }
  d
}