readNWISmeas.Rd 3.57 KB
Newer Older
Laura A DeCicco's avatar
Laura A DeCicco committed
1
% Generated by roxygen2: do not edit by hand
2
% Please edit documentation in R/readNWISunit.r
3
4
\name{readNWISmeas}
\alias{readNWISmeas}
5
\title{Surface-water measurement data retrieval from USGS (NWIS)}
6
\usage{
Laura A DeCicco's avatar
Laura A DeCicco committed
7
8
9
10
11
12
13
14
readNWISmeas(
  siteNumbers,
  startDate = "",
  endDate = "",
  tz = "UTC",
  expanded = FALSE,
  convertType = TRUE
)
15
16
}
\arguments{
17
\item{siteNumbers}{character USGS site number (or multiple sites).  This is usually an 8 digit number}
18

19
20
\item{startDate}{character starting date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates
retrieval for the earliest possible record.}
21

22
23
\item{endDate}{character ending date for data retrieval in the form YYYY-MM-DD. Default is "" which indicates
retrieval for the latest possible record.}
Laura A DeCicco's avatar
Laura A DeCicco committed
24

25
26
\item{tz}{character to set timezone attribute of dateTime. Default is "UTC", and converts the 
date times to UTC, properly accounting for daylight savings times based on the data's provided tz_cd column.
Laura A DeCicco's avatar
Laura A DeCicco committed
27
Possible values to provide are "America/New_York","America/Chicago", "America/Denver","America/Los_Angeles",
28
29
30
"America/Anchorage", as well as the following which do not use daylight savings time: "America/Honolulu",
"America/Jamaica","America/Managua","America/Phoenix", and "America/Metlakatla". See also  \code{OlsonNames()} 
for more information on time zones.}
31
32

\item{expanded}{logical. Whether or not (TRUE or FALSE) to call the expanded data.}
Laura A DeCicco's avatar
Laura A DeCicco committed
33
34
35

\item{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}
36
}
37
38
39
40
41
42
\value{
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
43
measurement_dt \tab POSIXct \tab The date and time (in POSIXct) of the measurement. Unless specified
Laura A DeCicco's avatar
Laura A DeCicco committed
44
45
with the tz parameter, this is converted to UTC. If the measurement_dt column is an incomplete, a measurement_dt_date and
measurement_dt_time column are added to the returned data frame.   \cr
46
tz_cd \tab character \tab The time zone code for the measurement_dt column \cr
47
}
Laura A DeCicco's avatar
Laura A DeCicco committed
48
 
Laura A DeCicco's avatar
Laura A DeCicco committed
49
See \url{https://waterdata.usgs.gov/usa/nwis/sw} for details about surface water, and 
Laura A DeCicco's avatar
Laura A DeCicco committed
50
\url{https://waterdata.usgs.gov/nwis/help?output_formats_help}
Laura A DeCicco's avatar
Laura A DeCicco committed
51
for help on the columns and codes.
Laura A DeCicco's avatar
Laura A DeCicco committed
52

53
54
55
56
57
58
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
Laura A DeCicco's avatar
Laura A DeCicco committed
59
siteInfo \tab data.frame \tab A data frame containing information on the requested sites \cr
60
tz_cd_reported \tab The originally reported time zone \cr
61
62
}
}
63
\description{
Laura A DeCicco's avatar
Laura A DeCicco committed
64
65
Reads surface-water measurement data from NWISweb. Data is retrieved from \url{https://waterdata.usgs.gov/nwis}.
See \url{https://waterdata.usgs.gov/usa/nwis/sw} for details about surface water.
66
67
}
\examples{
Laura A DeCicco's avatar
Laura A DeCicco committed
68
\dontshow{if (is_dataRetrieval_user()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}
69
site_ids <- c('01594440','040851325')
70
\donttest{
71
data <- readNWISmeas(site_ids)
Laura A DeCicco's avatar
Laura A DeCicco committed
72
Meas05316840 <- readNWISmeas("05316840")
73
Meas05316840.ex <- readNWISmeas("05316840",expanded=TRUE)
Laura A DeCicco's avatar
Laura A DeCicco committed
74
Meas07227500.ex <- readNWISmeas("07227500",expanded=TRUE)
Laura A DeCicco's avatar
Laura A DeCicco committed
75
Meas07227500.exRaw <- readNWISmeas("07227500",expanded=TRUE, convertType = FALSE)
76
}
Laura A DeCicco's avatar
Laura A DeCicco committed
77
\dontshow{\}) # examplesIf}
Laura A DeCicco's avatar
Laura A DeCicco committed
78
}
Laura A DeCicco's avatar
Laura A DeCicco committed
79
80
81
\seealso{
\code{\link{constructNWISURL}}, \code{\link{importRDB1}}
}