whatNWISData.r 5.34 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
#'
6
7
#' @param siteNumbers character USGS site number or multiple sites.
#' @param service character. Options are "all", or one or many of "dv"(daily values),
Laura A DeCicco's avatar
Laura A DeCicco committed
8
9
10
#'      "uv","rt", or "iv"(unit values), "qw"(water-quality),"sv"(sites visits),"pk"(peak measurements),
#'      "gw"(groundwater levels), "ad" (sites included in USGS Annual Water Data Reports External Link), 
#'      "aw" (sites monitored by the USGS Active Groundwater Level Network External Link), "id" (historical 
Laura A DeCicco's avatar
Laura A DeCicco committed
11
#'      instantaneous values)
12
13
#' @param parameterCd character vector of valid parameter codes to return. Defaults to "all" which will not perform a filter.
#' @param statCd character vector of all statistic codes to return. Defaults to "all" which will not perform a filter.
14
#' @keywords data import USGS web service
Laura A DeCicco's avatar
Laura A DeCicco committed
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
51
52
53
54
55
#' @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
#' }
56
#' @export
Laura A DeCicco's avatar
Laura A DeCicco committed
57
#' @importFrom lubridate parse_date_time
58
#' @examples
59
#' \dontrun{
Laura A DeCicco's avatar
Laura A DeCicco committed
60
#' availableData <- whatNWISdata('05114000')
Laura A DeCicco's avatar
Laura A DeCicco committed
61
#' # To find just unit value ('instantaneous') data:
Laura A DeCicco's avatar
Laura A DeCicco committed
62
#' uvData <- whatNWISdata('05114000',service="uv")
Laura A DeCicco's avatar
Laura A DeCicco committed
63
#' uvDataMulti <- whatNWISdata(c('05114000','09423350'),service=c("uv","dv"))
64
65
#' site_ids <- c("01491000","01645000")
#' flowAndTemp <- whatNWISdata(site_ids, parameterCd=c("00060","00010"))
66
#' }
67
whatNWISdata <- function(siteNumbers,service="all",parameterCd="all",statCd="all"){
68
  
Laura A DeCicco's avatar
Laura A DeCicco committed
69
70
71
  siteNumber <- paste(siteNumbers,collapse=",")
  
  if(!("all" %in% service)){
Laura A DeCicco's avatar
Laura A DeCicco committed
72
73
74
75
76
77
    service <- match.arg(service, c("dv","uv","qw","ad","id","pk","sv","gw","aw","all","ad","iv"), several.ok = TRUE)
    
    if(service == "uv"){
      service <- "iv"
    }
  } 
Laura A DeCicco's avatar
Laura A DeCicco committed
78
  
79
  if(!("all" %in% parameterCd)){
Doug Friedman's avatar
Doug Friedman committed
80
    if(anyNA(parameterCd)){
81
      pcodeCheck <- all(nchar(parameterCd) == 5) & all(!is.na(suppressWarnings(as.numeric(parameterCd))))
Laura A DeCicco's avatar
Laura A DeCicco committed
82
      
83
84
85
86
87
88
      if(!pcodeCheck){
        badIndex <- which(nchar(parameterCd) != 5 | is.na(suppressWarnings(as.numeric(parameterCd))))
        
        stop("The following pCodes appear mistyped:",paste(parameterCd[badIndex],collapse=","))
      } else {
        parameterCdCheck <- readNWISpCode(parameterCd)
Laura A DeCicco's avatar
Laura A DeCicco committed
89
      }
90
      
Laura A DeCicco's avatar
Laura A DeCicco committed
91
92
93
    }
  }
  
Laura A DeCicco's avatar
Laura A DeCicco committed
94
  urlSitefile <- drURL('site', Access=pkg.env$access, format='rdb', seriesCatalogOutput='true',sites=siteNumber)
Laura A DeCicco's avatar
Laura A DeCicco committed
95
 
Laura A DeCicco's avatar
Laura A DeCicco committed
96
  SiteFile <- importRDB1(urlSitefile, asDateTime = FALSE)
97
  
Laura A DeCicco's avatar
Laura A DeCicco committed
98
99
100
101
102
103
104
105
106
107
108
109
110
  headerInfo <- comment(SiteFile)
  
  parameterCds <- unique(SiteFile$parm_cd)
  
  parameterCdINFO <- parameterCdFile[parameterCdFile$parameter_cd %in% parameterCds,]
  SiteFile <- merge(SiteFile,parameterCdINFO,by.x="parm_cd" ,by.y="parameter_cd",all=TRUE)
  
  
  if(!("all" %in% service)){
    SiteFile <- SiteFile[SiteFile$data_type_cd %in% service,]
  }
  if(!("all" %in% statCd)){
    SiteFile <- SiteFile[SiteFile$stat_cd %in% statCd,]
Laura A DeCicco's avatar
Laura A DeCicco committed
111
  }
Laura A DeCicco's avatar
Laura A DeCicco committed
112
113
114
115
  if(!("all" %in% parameterCd)){
    SiteFile <- SiteFile[SiteFile$parm_cd %in% parameterCd,]
  }
  
116
117
118
119
  if(nrow(SiteFile) > 0){
    SiteFile$begin_date <- as.Date(parse_date_time(SiteFile$begin_date, c("Ymd", "mdY", "Y!")))
    SiteFile$end_date <- as.Date(parse_date_time(SiteFile$end_date, c("Ymd", "mdY", "Y!")))
  }
Laura A DeCicco's avatar
Laura A DeCicco committed
120
121
122
  
  comment(SiteFile) <- headerInfo
  attr(SiteFile, "url") <- urlSitefile
Laura A DeCicco's avatar
Laura A DeCicco committed
123
  attr(SiteFile, "queryTime") <- Sys.time()
Laura A DeCicco's avatar
Laura A DeCicco committed
124
125
126
  
  return(SiteFile)

127
}