whatNWISData.r 4.94 KB
Newer Older
1
2
#' USGS data availability
#'
Laura A DeCicco's avatar
Laura A DeCicco committed
3
#' Imports a table of available parameters, period of record, and count. See \url{https://waterservices.usgs.gov/rest/Site-Service.html}
Laura A DeCicco's avatar
Laura A DeCicco committed
4
#' for more information.
5
#'
Laura A DeCicco's avatar
Laura A DeCicco committed
6
#' @param \dots see \url{https://waterservices.usgs.gov/rest/Site-Service.html} for a complete list of options.  A list of arguments can also be supplied. 
Laura A DeCicco's avatar
Laura A DeCicco committed
7
8
#' @param convertType logical, defaults to \code{TRUE}. If \code{TRUE}, the function will convert the data to dates, datetimes,
#' numerics based on a standard algorithm. If false, everything is returned as a character
9
#' @keywords data import USGS web service
Laura A DeCicco's avatar
Laura A DeCicco committed
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
#' @return A data frame with 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
#' station_nm \tab character \tab Site name \cr 
#' site_tp_cd \tab character \tab Site type \cr
#' dec_lat_va \tab numeric \tab Decimal latitude\cr
#' dec_long_va \tab numeric \tab Decimal longitude \cr
#' coord_acy_cd \tab character \tab Latitude-longitude accuracy \cr
#' dec_coord_datum_cd \tab character \tab Decimal Latitude-longitude datum \cr
#' alt_va \tab character \tab Altitude of Gage or land surface \cr
#' alt_acy_va \tab character \tab Altitude accuracy \cr
#' alt_datum_cd \tab character \tab Altitude datum \cr
#' huc_cd \tab character \tab Hydrologic unit code \cr
#' data_type_cd \tab character \tab Data type \cr
#' parm_cd \tab character \tab Parameter code \cr
#' stat_cd \tab character \tab Statistical code \cr
#' dd_nu \tab character \tab Internal database key \cr
#' loc_web_ds \tab character \tab Additional measurement description \cr
#' medium_grp_cd \tab character \tab Medium group code \cr
#' parm_grp_cd \tab character \tab Parameter group code \cr
#' srs_id \tab character \tab SRS ID \cr
#' access_cd \tab character \tab Access code \cr
#' begin_date \tab Date \tab Begin date \cr
#' end_date \tab Date \tab End date \cr
#' count_nu \tab integer \tab Record count\cr
#' parameter_group_nm \tab character \tab Parameter group name \cr
#' parameter_nm \tab character \tab Parameter name \cr
#' casrn \tab character \tab Chemical Abstracts Service (CAS) Registry Number \cr
#' srsname \tab character \tab Substance Registry Services \cr
#' parameter_units \tab character \tab Parameter units \cr
#' }
#'
#' 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
#' comment \tab character \tab Header comments from the RDB file \cr
#' queryTime \tab POSIXct \tab The time the data was returned \cr
#' }
51
52
#' @export
#' @examples
53
#' \donttest{
Laura A DeCicco's avatar
Laura A DeCicco committed
54
#' try({
Laura A DeCicco's avatar
Laura A DeCicco committed
55
#' availableData <- whatNWISdata(siteNumber = '05114000')
Laura A DeCicco's avatar
Laura A DeCicco committed
56
#' # To find just unit value ('instantaneous') data:
Laura A DeCicco's avatar
Laura A DeCicco committed
57
58
#' uvData <- whatNWISdata(siteNumber = '05114000',service="uv")
#' uvDataMulti <- whatNWISdata(siteNumber = c('05114000','09423350'),service=c("uv","dv"))
Laura A DeCicco's avatar
Laura A DeCicco committed
59
60
61
#' flowAndTemp <- whatNWISdata(stateCd = "WI", service = "uv", 
#'                              parameterCd = c("00060","00010"),
#'                              statCd = "00003")
Laura A DeCicco's avatar
Laura A DeCicco committed
62
#' })
63
#' }
Laura A DeCicco's avatar
Laura A DeCicco committed
64
whatNWISdata <- function(..., convertType=TRUE){
65
  
Laura A DeCicco's avatar
Laura A DeCicco committed
66
  matchReturn <- convertLists(...)
Laura A DeCicco's avatar
Laura A DeCicco committed
67
  
Laura A DeCicco's avatar
Laura A DeCicco committed
68
69
  if("service" %in% names(matchReturn)){
    service <- matchReturn$service
70
    if(any(service %in% c("qw", "qwdata"))){
Laura A DeCicco's avatar
Laura A DeCicco committed
71
72
73
74
75
      .Deprecated(old = "whatNWISdata", package = "dataRetrieval", 
                  new = "whatWQPdata",
                  msg = "NWIS qw web services are being retired. Please see the vignette 
'Changes to NWIS QW services' for more information.")
    }
Laura A DeCicco's avatar
Laura A DeCicco committed
76
77
  } else {
    service <- "all"
Laura A DeCicco's avatar
Laura A DeCicco committed
78
79
  }
  
Laura A DeCicco's avatar
Laura A DeCicco committed
80
81
82
83
84
85
86
87
88
  if("statCd" %in% names(matchReturn)){
    statCd <- matchReturn$statCd
    matchReturn <- matchReturn[names(matchReturn) != "statCd"]
  } else {
    statCd <- "all"
  }
  
  if("parameterCd" %in% names(matchReturn)){
    parameterCd <- matchReturn$parameterCd
Laura A DeCicco's avatar
Laura A DeCicco committed
89
    matchReturn[["parameterCd"]] <- NULL
Laura A DeCicco's avatar
Laura A DeCicco committed
90
91
92
93
  } else {
    parameterCd <- "all"
  }
  
Laura A DeCicco's avatar
Laura A DeCicco committed
94
  matchReturn$service <- "site"
95
  
Laura A DeCicco's avatar
Laura A DeCicco committed
96
  valuesList <- readNWISdots(matchReturn)
Laura A DeCicco's avatar
Laura A DeCicco committed
97
  
Laura A DeCicco's avatar
Laura A DeCicco committed
98
99
100
101
102
  values <- sapply(valuesList$values, function(x) URLencode(x))

  if(any(service == "iv")){
    service[service == "iv"] <- "uv"
  }
Laura A DeCicco's avatar
Laura A DeCicco committed
103
  
Laura A DeCicco's avatar
Laura A DeCicco committed
104
105
  urlSitefile <- drURL('site', Access=pkg.env$access, seriesCatalogOutput='true',arg.list=values)
 
Laura A DeCicco's avatar
Laura A DeCicco committed
106
  SiteFile <- importRDB1(urlSitefile, asDateTime = FALSE, convertType = convertType)
Laura A DeCicco's avatar
Laura A DeCicco committed
107

Laura A DeCicco's avatar
Laura A DeCicco committed
108
109
110
111
  if(!("all" %in% service)){
    SiteFile <- SiteFile[SiteFile$data_type_cd %in% service,]
  }
  if(!("all" %in% statCd)){
Laura A DeCicco's avatar
Laura A DeCicco committed
112
    SiteFile <- SiteFile[SiteFile$stat_cd %in% c(statCd,NA),]
Laura A DeCicco's avatar
Laura A DeCicco committed
113
  }
Laura A DeCicco's avatar
Laura A DeCicco committed
114
115
116
117
  if(!("all" %in% parameterCd)){
    SiteFile <- SiteFile[SiteFile$parm_cd %in% parameterCd,]
  }
  
Laura A DeCicco's avatar
Laura A DeCicco committed
118
  if(nrow(SiteFile) > 0 & convertType){
Laura A DeCicco's avatar
Laura A DeCicco committed
119
120
    SiteFile$begin_date <- as.Date(lubridate::parse_date_time(SiteFile$begin_date, c("Ymd", "mdY", "Y!")))
    SiteFile$end_date <- as.Date(lubridate::parse_date_time(SiteFile$end_date, c("Ymd", "mdY", "Y!")))
121
  }
Laura A DeCicco's avatar
Laura A DeCicco committed
122
123
124
  
  return(SiteFile)

125
}