header_tag.html

Skip to contents

This function accepts a url parameter that already contains the desired NWIS site, parameter code, statistic, startdate and enddate. It is not recommended to use the RDB format for importing multi-site data.

Usage

importRDB1(obs_url, asDateTime = TRUE, convertType = TRUE, tz = "UTC")

Arguments

obs_url

character containing the url for the retrieval or a file path to the data file.

asDateTime

logical, if TRUE returns date and time as POSIXct, if FALSE, Date

convertType

logical, defaults to TRUE. If TRUE, the function will convert the data to dates, datetimes, numerics based on a standard algorithm. If false, everything is returned as a character

tz

character to set timezone attribute of datetime. Default converts the datetimes to UTC (properly accounting for daylight savings times based on the data's provided tz_cd column). Recommended US values include "UTC", "America/New_York", "America/Chicago", "America/Denver", "America/Los_Angeles", "America/Anchorage", "America/Honolulu", "America/Jamaica", "America/Managua", "America/Phoenix", and "America/Metlakatla". For a complete list, see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Value

A data frame with the following columns:

NameTypeDescription
agency_cdcharacterThe NWIS code for the agency reporting the data
site_nocharacterThe USGS site number
datetimePOSIXctThe date and time of the value converted to UTC (if asDateTime = TRUE),
characteror raw character string (if asDateTime = FALSE)
tz_cdcharacterThe time zone code for datetime
codecharacterAny codes that qualify the corresponding value
valuenumericThe numeric value for the parameter
tz_cd_reportedThe originally reported time zone

Note that code and value are repeated for the parameters requested. The names are of the form XD_P_S, where X is literal, D is an option description of the parameter, P is the parameter code, and S is the statistic code (if applicable). If a date/time (dt) column contained incomplete date and times, a new column of dates and time was inserted. This could happen when older data was reported as dates, and newer data was reported as a date/time.

There are also several useful attributes attached to the data frame:

NameTypeDescription
urlcharacterThe url used to generate the data
queryTimePOSIXctThe time the data was returned
commentcharacterHeader comments from the RDB file

Examples

site_id <- "02177000"
startDate <- "2012-09-01"
endDate <- "2012-10-01"
offering <- "00003"
property <- "00060"

obs_url <- constructNWISURL(site_id, property,
  startDate, endDate, "dv",
  format = "tsv"
)
# \donttest{
data <- importRDB1(obs_url)
#> GET: https://waterservices.usgs.gov/nwis/dv/?site=02177000&format=rdb,1.0&ParameterCd=00060&StatCd=00003&startDT=2012-09-01&endDT=2012-10-01


urlMultiPcodes <- constructNWISURL("04085427", c("00060", "00010"),
  startDate, endDate, "dv",
  statCd = c("00003", "00001"), "tsv"
)

multiData <- importRDB1(urlMultiPcodes)
#> GET: https://waterservices.usgs.gov/nwis/dv/?site=04085427&format=rdb,1.0&ParameterCd=00060,00010&StatCd=00003,00001&startDT=2012-09-01&endDT=2012-10-01

unitDataURL <- constructNWISURL(site_id, property,
  "2020-10-30", "2020-11-01", "uv",
  format = "tsv"
) # includes timezone switch

unitData <- importRDB1(unitDataURL, asDateTime = TRUE)
#> GET: https://nwis.waterservices.usgs.gov/nwis/iv/?site=02177000&format=rdb,1.0&ParameterCd=00060&startDT=2020-10-30&endDT=2020-11-01

iceSite <- "04024000"
start <- "2015-11-09"
end <- "2015-11-24"
urlIce <- constructNWISURL(iceSite, "00060", start, end, "uv", format = "tsv")

ice <- importRDB1(urlIce, asDateTime = TRUE)
#> GET: https://nwis.waterservices.usgs.gov/nwis/iv/?site=04024000&format=rdb,1.0&ParameterCd=00060&startDT=2015-11-09&endDT=2015-11-24
iceNoConvert <- importRDB1(urlIce, convertType = FALSE)
#> GET: https://nwis.waterservices.usgs.gov/nwis/iv/?site=04024000&format=rdb,1.0&ParameterCd=00060&startDT=2015-11-09&endDT=2015-11-24
# }
# User file:
filePath <- system.file("extdata", package = "dataRetrieval")
fileName <- "RDB1Example.txt"
fullPath <- file.path(filePath, fileName)
importUserRDB <- importRDB1(fullPath)