importRDB1: Function to return data from the NWIS RDB 1.0 format

In dataRetrieval: Retrieval Functions for USGS and EPA Hydrology and Water Quality Data

Function to return data from the NWIS RDB 1.0 format

Description

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:

Name	Type	Description
agency_cd	character	The NWIS code for the agency reporting the data
site_no	character	The USGS site number
datetime	POSIXct	The date and time of the value converted to UTC (if asDateTime = TRUE),
	character	or raw character string (if asDateTime = FALSE)
tz_cd	character	The time zone code for datetime
code	character	Any codes that qualify the corresponding value
value	numeric	The numeric value for the parameter
tz_cd_reported	The 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:

Name	Type	Description
url	character	The url used to generate the data
queryTime	POSIXct	The time the data was returned
comment	character	Header 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"
)

data <- importRDB1(obs_url)


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

multiData <- importRDB1(urlMultiPcodes)

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

unitData <- importRDB1(unitDataURL, asDateTime = TRUE)

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

ice <- importRDB1(urlIce, asDateTime = TRUE)
iceNoConvert <- importRDB1(urlIce, convertType = FALSE)

# User file:
filePath <- system.file("extdata", package = "dataRetrieval")
fileName <- "RDB1Example.txt"
fullPath <- file.path(filePath, fileName)
importUserRDB <- importRDB1(fullPath)

dataRetrieval documentation built on Oct. 31, 2024, 9:07 a.m.