Merge pull request #111 from ldecicco-USGS/master

Help file updates.

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: dataRetrieval
 Type: Package
 Title: Retrieval Functions for USGS and EPA Hydrologic and Water Quality Data
-Version: 2.1.4
-Date: 2015-03-09
+Version: 2.1.5
+Date: 2015-04-01
 Authors@R: c( person("Robert", "Hirsch", role = c("aut"),
     email = "[email protected]"),
     person("Laura", "DeCicco", role = c("aut","cre"),

NAMESPACE

@@ -3,6 +3,7 @@
 export(checkWQPdates)
 export(constructNWISURL)
 export(constructWQPURL)
+export(countyCd)
 export(getWebServiceData)
 export(importRDB1)
 export(importWQP)
@@ -23,6 +24,7 @@ export(readNWISuv)
 export(readWQPdata)
 export(readWQPqw)
 export(renameNWISColumns)
+export(stateCd)
 export(whatNWISdata)
 export(whatNWISsites)
 export(whatWQPsites)

R/importWaterML1.r

@@ -408,9 +408,10 @@ importWaterML1 <- function(obs_url,asDateTime=FALSE, tz=""){
 
     meltedmergedDF  <- melt(mergedDF,id.vars=sortingColumns)
     meltedmergedDF  <- meltedmergedDF[!is.na(meltedmergedDF$value),] 
-
+    rownames(meltedmergedDF) <- NULL
+    meltedmergedDF <- meltedmergedDF[!duplicated(meltedmergedDF),]
     castFormula <- as.formula(paste(paste(sortingColumns, collapse="+"),"variable",sep="~"))
-    mergedDF2 <- dcast(meltedmergedDF, castFormula, drop=FALSE)
+    mergedDF2 <- dcast(meltedmergedDF, castFormula, drop=FALSE, value.var = "value")
     dataColumns2 <- !(names(mergedDF2) %in% sortingColumns)
     if(sum(dataColumns2) == 1){
       mergedDF <- mergedDF2[!is.na(mergedDF2[,dataColumns2]),]

R/readNWISdata.r

@@ -2,6 +2,7 @@
 #'
 #' Returns data from the NWIS web service.
 #' Arguments to the function should be based on \url{http://waterservices.usgs.gov} service calls.
+#' See examples below for ideas of constructing queries.
 #'
 #' @param service string. Possible values are "iv" (for instantaneous), "dv" (for daily values), "gwlevels" 
 #' (for groundwater levels), "site" (for site service), and "qw" (water-quality). Note: "qw" calls go to: 
@@ -13,9 +14,12 @@
 #' Name \tab Type \tab Description \cr
 #' agency \tab character \tab The NWIS code for the agency reporting the data\cr
 #' site \tab character \tab The USGS site number \cr
-#' datetime \tab POSIXct \tab The date and time of the value converted to UTC (for unit value data), \cr 
-#' \tab character \tab or raw character string \cr
-#' tz_cd \tab character \tab The time zone code for datetime \cr
+#' dateTime \tab POSIXct \tab The date and time (if applicable) of the measurement, 
+#'           converted to UTC for unit value data. R only allows one time zone attribute per column. For unit data 
+#'           spanning a time zone change, converting the data to UTC solves this problem. For daily data,
+#'           the time zone attribute is the time zone of the first returned measurement.
+#'            \cr
+#' tz_cd \tab character \tab The time zone code for dateTime column\cr
 #' code \tab character \tab Any codes that qualify the corresponding value\cr
 #' value \tab numeric \tab The numeric value for the parameter \cr
 #' }
@@ -41,11 +45,21 @@
 #' \dontrun{
 #' # Examples not run for time considerations
 #' dataTemp <- readNWISdata(stateCd="OH",parameterCd="00010")
-#' dataTempUnit <- readNWISdata(sites="03086500", service="iv", parameterCd="00010")
+#' instFlow <- readNWISdata(sites="05114000", service="iv", 
+#'                    parameterCd="00060", 
+#'                    startDate="2014-05-01T00:00Z",endDate="2014-05-01T12:00Z")
+#'                    
+#' instFlowCDT <- readNWISdata(sites="05114000", service="iv", 
+#'                    parameterCd="00060", 
+#'                    startDate="2014-05-01T00:00",endDate="2014-05-01T12:00",
+#'                    tz="America/Chicago")
+#'
 #' #Empty:
-#' multiSite <- readNWISdata(sites=c("04025000","04072150"), service="iv", parameterCd="00010")
+#' multiSite <- readNWISdata(sites=c("04025000","04072150"), service="iv", 
+#'                            parameterCd="00010")
 #' #Not empty:
-#' multiSite <- readNWISdata(sites=c("04025500","040263491"), service="iv", parameterCd="00060")
+#' multiSite <- readNWISdata(sites=c("04025500","040263491"), 
+#'                            service="iv", parameterCd="00060")
 #' bBoxEx <- readNWISdata(bBox=c(-83,36.5,-81,38.5), parameterCd="00010")
 #' 
 #' startDate <- as.Date("2013-10-01")
@@ -58,6 +72,8 @@
 #'                   drain_area_va_min=50, qw_count_nu=50,qw_attributes="expanded",
 #'                   qw_sample_wide="wide",list_of_search_criteria=c("lat_long_bounding_box",
 #'                   "drain_area_va","obs_count_nu"),service="qw")
+#' temp <- readNWISdata(bBox=c(-83,36.5,-81,38.5), parameterCd="00010", service="site", 
+#'                    seriesCatalogOutput=TRUE)
 #' }
 readNWISdata <- function(service="dv", ...){
 
@@ -111,6 +127,21 @@ readNWISdata <- function(service="dv", ...){
 
   }
 
+  if("tz" %in% names(values)){
+    tz <- values["tz"]
+    if(tz != ""){
+      rTZ <- c("America/New_York","America/Chicago",
+               "America/Denver","America/Los_Angeles",
+               "America/Anchorage","America/Honolulu",
+               "America/Jamaica","America/Managua",
+               "America/Phoenix","America/Metlakatla")
+      tz <- match.arg(tz, rTZ)
+    }
+    values <- values[!(names(values) %in% "tz")]
+  } else {
+    tz <- ""
+  }
+
   if(service == "site"){
     format <- "rdb"
   }
@@ -121,12 +152,45 @@ readNWISdata <- function(service="dv", ...){
   urlCall <- paste0(baseURL,urlCall)
 
   if(service == "site"){
-    retval <- importRDB1(urlCall, asDateTime = FALSE, qw = FALSE)
+    possibleError <- tryCatch({
+      retval <- importRDB1(urlCall, asDateTime = FALSE, qw = FALSE, tz = tz)
+    }, error = function(e) {
+      stop(e, "with url:", urlCall)
+    })
+
   } else if(service != "qwdata") {
-    retval <- importWaterML1(urlCall, asDateTime = ("iv" == service))
+    possibleError <- tryCatch({
+      retval <- importWaterML1(urlCall, asDateTime = ("iv" == service), tz= tz)
+    }, error = function(e) {
+      stop(e, "with url:", urlCall)
+    })
+
     if("dv" == service){
-      retval$dateTime <- as.POSIXct(retval$dateTime)
+
+      tzLib <- setNames(c("America/New_York","America/New_York",
+                                  "America/Chicago","America/Chicago",
+                                  "America/Denver","America/Denver",
+                                  "America/Los_Angeles","America/Los_Angeles",
+                                  "America/Anchorage","America/Anchorage",
+                                  "America/Honolulu","America/Honolulu"),
+                                c("EST","EDT",
+                                  "CST","CDT",
+                                  "MST","MDT",
+                                  "PST","PDT",
+                                  "AKST","AKDT",
+                                  "HAST","HST"))
+      #TODO: Think about dates that cross a time zone boundary.
+      retval$dateTime <- as.POSIXct(retval$dateTime, tzLib[tz=retval$tz_cd[1]])
     }
+
+    if("iv" == service){
+      if(tz == ""){
+        retval$tz_cd <- rep("UTC", nrow(retval))
+      } else {
+        retval$tz_cd <- rep(tz, nrow(retval))
+      }
+    }
+
   } else {
     possibleError <- tryCatch({
       retval <- importRDB1(urlCall, asDateTime = TRUE, qw = TRUE)
@@ -135,5 +199,7 @@ readNWISdata <- function(service="dv", ...){
     })
   }
 
+
+
   return(retval)
 }

R/readNWISdv.r

@@ -6,9 +6,9 @@
 #' @param siteNumber character USGS site number.  This is usually an 8 digit number. Multiple sites can be requested with a character vector.
 #' @param parameterCd character of USGS parameter code(s).  This is usually an 5 digit number.
 #' @param startDate character starting date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates
-#' retrieval for the earliest possible record.
+#' retrieval for the earliest possible record. Date arguments are always specified in local time.
 #' @param endDate character ending date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates
-#' retrieval for the latest possible record.
+#' retrieval for the latest possible record. Date arguments are always specified in local time.
 #' @param statCd character USGS statistic code. This is usually 5 digits.  Daily mean (00003) is the default.
 #' @return A data frame with the following columns:
 #' \tabular{lll}{

R/readNWISqw.r

@@ -30,9 +30,9 @@
 #' @param parameterCd character that contains the code for a parameter
 #' group, or a character vector of 5-digit parameter codes. See \bold{Details}.
 #' @param startDate character starting date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates
-#' retrieval for the earliest possible record.
+#' retrieval for the earliest possible record. Date arguments are always specified in local time.
 #' @param endDate character ending date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates
-#' retrieval for the latest possible record.
+#' retrieval for the latest possible record. Date arguments are always specified in local time.
 #' @param expanded logical defaults to \code{TRUE}. If \code{TRUE}, retrieves additional information. Expanded data includes
 #' remark_cd (remark code), result_va (result value), val_qual_tx (result value qualifier code), meth_cd (method code),
 #' dqi_cd (data-quality indicator code), rpt_lev_va (reporting level), and rpt_lev_cd (reporting level type). If \code{FALSE},
@@ -41,31 +41,34 @@
 #' @param reshape logical, reshape the expanded data. If \code{TRUE}, then return a wide data frame with all water-quality in a single row for each sample. 
 #' If \code{FALSE} (default), then return a long data frame with each water-quality result in a single row. This
 #' argument is only applicable to expanded data. Data requested using \code{expanded=FALSE} is always returned in the wide format.
-#' @param tz character to set timezone attribute of datetime. Default is an empty quote, which converts the 
-#' datetimes to UTC (properly accounting for daylight savings times based on the data's provided tz_cd column).
+#' @param tz character to set timezone attribute of output columns: startDateTime and endDateTime. Default is an empty quote, which converts the 
+#' datetimes to UTC (properly accounting for daylight savings times).
 #' Possible values to provide are "America/New_York","America/Chicago", "America/Denver","America/Los_Angeles",
 #' "America/Anchorage","America/Honolulu","America/Jamaica","America/Managua","America/Phoenix", and "America/Metlakatla"
 #' @keywords data import USGS web service
-#' @return A data frame with the following columns:
+#' @return A data frame with at least the following columns:
 #' \tabular{lll}{
 #' Name \tab Type \tab Description \cr
 #' agency_cd \tab character \tab The NWIS code for the agency reporting the data\cr
 #' site_no \tab character \tab The USGS site number \cr
-#' datetime \tab POSIXct \tab The date and time of the value converted to UTC (if asDateTime = TRUE), \cr 
-#' \tab character \tab or raw character string (if asDateTime = FALSE) \cr
-#' tz_cd \tab character \tab The time zone code for datetime \cr
-#' code \tab character \tab Any codes that qualify the corresponding value\cr
-#' value \tab numeric \tab The numeric value for the parameter \cr
+#' sample_dt \tab Date \tab The date the sample was collected \cr 
+#' sample_tm \tab character \tab The reported sample collection time \cr
+#' startDateTime \tab POSIXct \tab Combining sample_dt and sample_tm, a date/time column is created, and converted into UTC 
+#' (unless the tz argument specifies a different time zone)\cr
+#' endDateTime \tab POSIXct \tab If any sample_end_dt and sample_end_dt exist, this column is created similar to startDateTime\cr
 #' }
 #' 
+#' Further columns will be included depending on the requested output format (expanded = TRUE or FALSE).
+#' 
+#' 
 #' There are also several useful attributes attached to the data frame:
 #' \tabular{lll}{
 #' Name \tab Type \tab Description \cr
 #' url \tab character \tab The url used to generate the data \cr
 #' queryTime \tab POSIXct \tab The time the data was returned \cr
 #' comment \tab character \tab Header comments from the RDB file \cr
-#' siteInfo \tab data.frame \tab A data frame containing information on the requested sites \cr
-#' variableInfo \tab data.frame \tab A data frame containing information on the requested parameters \cr
+#' siteInfo \tab data frame \tab A data frame containing information on the requested sites \cr
+#' variableInfo \tab data frame \tab A data frame containing information on the requested parameters \cr
 #' }
 #' @export
 #' @import reshape2

R/readNWISunit.r

@@ -8,9 +8,11 @@
 #' @param siteNumbers character USGS site number (or multiple sites).  This is usually an 8 digit number
 #' @param parameterCd character USGS parameter code.  This is usually an 5 digit number.
 #' @param startDate character starting date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates
-#' retrieval for the earliest possible record.
+#' retrieval for the earliest possible record. Simple date arguments are specified in local time.
+#' See more information here: \url{http://waterservices.usgs.gov/rest/IV-Service.html#Specifying}.
 #' @param endDate character ending date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates
-#' retrieval for the latest possible record.
+#' retrieval for the latest possible record. Simple date arguments are specified in local time.
+#' See more information here: \url{http://waterservices.usgs.gov/rest/IV-Service.html#Specifying}.
 #' @param tz character to set timezone attribute of dateTime. Default is an empty quote, which converts the 
 #' dateTimes to UTC (properly accounting for daylight savings times based on the data's provided tz_cd column).
 #' Possible values to provide are "America/New_York","America/Chicago", "America/Denver","America/Los_Angeles",
@@ -54,13 +56,27 @@
 #' 
 #' timeZoneChange <- readNWISuv(c('04024430','04024000'),parameterCd,
 #'          "2013-11-03","2013-11-03")
+#'  
+#' centralTime <- readNWISuv(siteNumber,parameterCd,
+#'                            "2014-10-10T12:00", "2014-10-10T23:59",
+#'                            tz="America/Chicago")
+#' 
+#' # Adding 'Z' to the time indicates to the web service to call the data with UTC time:
+#' GMTdata <- readNWISuv(siteNumber,parameterCd,
+#'                            "2014-10-10T00:00Z", "2014-10-10T23:59Z")
 #' }
 #' 
 readNWISuv <- function (siteNumbers,parameterCd,startDate="",endDate="", tz=""){  
 
   url <- constructNWISURL(siteNumbers,parameterCd,startDate,endDate,"uv",format="xml")
 
   data <- importWaterML1(url,asDateTime=TRUE,tz=tz)
+
+  if(tz == ""){
+    data$tz_cd <- rep("UTC", nrow(data))
+  } else {
+    data$tz_cd <- rep(tz, nrow(data))
+  }
 
   return (data)
 }

R/readWQPqw.r

@@ -11,9 +11,9 @@
 #' @param parameterCd vector of USGS 5-digit parameter code or characteristicNames. 
 #' Leaving this blank will return all of the measured values during the specified time period.
 #' @param startDate character starting date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates
-#' retrieval for the earliest possible record.
+#' retrieval for the earliest possible record. Date arguments are always specified in local time.
 #' @param endDate character ending date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates
-#' retrieval for the latest possible record.
+#' retrieval for the latest possible record. Date arguments are always specified in local time.
 #' @keywords data import USGS web service
 #' @return A data frame with at least the following columns:
 #' \tabular{lll}{ 

R/tabbedDataRetrievals.R

@@ -78,3 +78,48 @@ NULL
 #' @examples
 #' head(pCodeToName[,1:2])
 NULL
+
+#' US State Code Lookup Table
+#'
+#' Data pulled from \url{http://www2.census.gov/geo/docs/reference/state.txt}
+#' on April 1, 2015. 
+#'
+#' @name stateCd
+#' @return stateCd data frame.
+#'
+#' \tabular{lll}{
+#' Name \tab Type \tab Description\cr
+#' STATE \tab character \tab two-digit ANSI code  \cr
+#' STUSAB \tab character \tab State abbreviation \cr
+#' STATE_NAME \tab character \tab State full name \cr
+#' STATENS \tab character \tab State id \cr
+#' }
+#' @docType data
+#' @export stateCd
+#' @keywords USGS stateCd
+#' @examples
+#' head(stateCd)
+NULL
+
+#' US County Code Lookup Table
+#'
+#' Data pulled from \url{http://www2.census.gov/geo/docs/reference/codes/files/national_county.txt}
+#' on April 1, 2015. 
+#'
+#' @name countyCd
+#' @return countyCd data frame.
+#'
+#' \tabular{lll}{
+#' Name \tab Type \tab Description\cr
+#' STUSAB \tab character \tab State abbreviation \cr
+#' STATE \tab character \tab two-digit ANSI code  \cr
+#' COUNTY \tab character \tab three-digit county code \cr
+#' COUNTY_NAME \tab character \tab County full name \cr
+#' COUNTY_ID \tab character \tab County id \cr
+#' }
+#' @docType data
+#' @export countyCd
+#' @keywords USGS countyCd
+#' @examples
+#' head(countyCd)
+NULL