diff --git a/R/readNWISqw.r b/R/readNWISqw.r
index 50b185aba8dbf68def9b9d8214a7517d503a7bd6..e8556fdc7c4f300ce0933e777f2b8077671eb1ee 100644
--- a/R/readNWISqw.r
+++ b/R/readNWISqw.r
@@ -28,11 +28,6 @@
#' code \tab character \tab Any codes that qualify the corresponding value\cr
#' value \tab numeric \tab The numeric value for the parameter \cr
#' }
-#' Note that code and value are repeated for the parameters requested. The names are of the form
-#' X_D_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).
#'
#' There are also several useful attributes attached to the data frame:
#' \tabular{lll}{
@@ -80,6 +75,13 @@ readNWISqw <- function (siteNumber,pCodes,startDate="",endDate="",
}
+ siteInfo <- readNWISsite(siteNumber)
+ varInfo <- readNWISpCode(pCodes)
+
+ attr(data, "siteInfo") <- siteInfo
+ attr(data, "variableInfo") <- varInfo
+ attr(data, "statisticInfo") <- NULL
+
return (data)
}
diff --git a/inst/doc/dataRetrieval.R b/inst/doc/dataRetrieval.R
index 398063008852219f23f906b678a6d038d8a39944..6363b6804ed7642c1b05742cbf708e2b395037e8 100644
--- a/inst/doc/dataRetrieval.R
+++ b/inst/doc/dataRetrieval.R
@@ -162,6 +162,16 @@ names(temperatureAndFlow)
temperatureAndFlow <- renameNWISColumns(temperatureAndFlow)
names(temperatureAndFlow)
+
+## ----label=attr1, echo=TRUE-------------------------------
+#Information about the data frame attributes:
+names(attributes(temperatureAndFlow))
+
+statInfo <- attr(temperatureAndFlow, "statisticInfo")
+variableInfo <- attr(temperatureAndFlow, "variableInfo")
+siteInfo <- attr(temperatureAndFlow, "siteInfo")
+
+
## ----getNWIStemperaturePlot, echo=TRUE, fig.cap="Temperature and discharge plot of Choptank River in 2012.",out.width='1\\linewidth',out.height='1\\linewidth',fig.show='hold'----
variableInfo <- attr(temperatureAndFlow, "variableInfo")
siteInfo <- attr(temperatureAndFlow, "siteInfo")
@@ -187,6 +197,7 @@ startDate <- "2012-05-12"
endDate <- "2012-05-13"
dischargeUnit <- readNWISuv(siteNumber, parameterCd,
startDate, endDate)
+dischargeUnit <- renameNWISColumns(dischargeUnit)
## ----dischargeData, echo=TRUE-----------------------------
head(dischargeUnit)
@@ -270,6 +281,10 @@ dischargeWI <- readNWISdata(service="dv",
names(dischargeWI)
nrow(dischargeWI)
+siteInfo <- attr(dischargeWI, "siteInfo")
+head(siteInfo)
+
+
## ----NJChloride, eval=FALSE-------------------------------
#
# sitesNJ <- whatWQPsites(statecode="US:34",
@@ -288,6 +303,8 @@ attr(dischargeWI, "url")
attr(dischargeWI, "queryTime")
+siteInfo <- attr(dischargeWI, "siteInfo")
+
## ----meta2, eval=TRUE-------------------------------------
diff --git a/inst/doc/dataRetrieval.Rnw b/inst/doc/dataRetrieval.Rnw
index 9865c1a72c6dcc459849c7ca17379916b8376f2b..58601b00d1328ada9477b97cf95b2f4e60e46cce 100644
--- a/inst/doc/dataRetrieval.Rnw
+++ b/inst/doc/dataRetrieval.Rnw
@@ -274,9 +274,9 @@ Table \ref{tab:func} describes the functions available in the dataRetrieval pack
\section{USGS Web Retrievals}
\label{sec:genRetrievals}
%------------------------------------------------------------
-In this section, examples of Web retrievals document how to get raw data. This data includes site information (\ref{sec:usgsSite}), measured parameter information (\ref{sec:usgsParams}), historical daily values(\ref{sec:usgsDaily}), unit values (which include real-time data but can also include other sensor data stored at regular time intervals) (\ref{sec:usgsRT}), water quality data (\ref{sec:usgsWQP}), groundwater level data (\ref{sec:gwl}), peak flow data (\ref{sec:peak}), rating curve data (\ref{sec:rating}, and surface-water measurement data (\ref{sec:meas}). Section \ref{sec:metadata} shows instructions for getting metadata that is attached to each returned dataframe.
+In this section, examples of Web retrievals document how to get raw data. This data includes site information (\ref{sec:usgsSite}), measured parameter information (\ref{sec:usgsParams}), historical daily values(\ref{sec:usgsDaily}), unit values (which include real-time data but can also include other sensor data stored at regular time intervals) (\ref{sec:usgsRT}), water quality data (\ref{sec:usgsWQP}), groundwater level data (\ref{sec:gwl}), peak flow data (\ref{sec:peak}), rating curve data (\ref{sec:rating}, and surface-water measurement data (\ref{sec:meas}). Section \ref{sec:metadata} shows instructions for getting metadata that is attached to each returned data frame.
-The USGS organizes hydrologic data in a standard structure. Streamgages are located throughout the United States, and each streamgage has a unique ID (referred in this document and throughout the dataRetrieval package as \enquote{siteNumber}). Often (but not always), these ID's are 8 digits. The first step to finding data is discovering this siteNumber. There are many ways to do this, one is the National Water Information System: Mapper \url{http://maps.waterdata.usgs.gov/mapper/index.html}.
+The USGS organizes hydrologic data in a standard structure. Streamgages are located throughout the United States, and each streamgage has a unique ID (referred in this document and throughout the dataRetrieval package as \enquote{siteNumber}). Often (but not always), these ID's are 8 digits for streamgages, and 15 digits for groundwater gages. The first step to finding data is discovering this siteNumber. There are many ways to do this, one is the National Water Information System: Mapper \url{http://maps.waterdata.usgs.gov/mapper/index.html}.
Once the siteNumber is known, the next required input for USGS data retrievals is the \enquote{parameter code}. This is a 5-digit code that specifies the measured parameter being requested. For example, parameter code 00631 represents \enquote{Nitrate plus nitrite, water, filtered, milligrams per liter as nitrogen}, with units of \enquote{mg/l as N}.
@@ -433,7 +433,7 @@ print(xtable(tableData,label="tab:gda",
-See Section \ref{app:createWordTable} for instructions on converting an R dataframe to a table in Microsoft\textregistered\ software Excel or Word to display a data availability table similar to Table \ref{tab:gda}. Excel, Microsoft, PowerPoint, Windows, and Word are registered trademarks of Microsoft Corporation in the United States and other countries.
+See Section \ref{app:createWordTable} for instructions on converting an R data frame to a table in Microsoft\textregistered\ software Excel or Word to display a data availability table similar to Table \ref{tab:gda}. Excel, Microsoft, PowerPoint, Windows, and Word are registered trademarks of Microsoft Corporation in the United States and other countries.
\FloatBarrier
@@ -462,10 +462,10 @@ Parameter information can obtained from:
\FloatBarrier
%------------------------------------------------------------
-\subsection{Daily Values}
+\subsection{Daily Data}
\label{sec:usgsDaily}
%------------------------------------------------------------
-To obtain daily records of USGS data, use the \texttt{readNWISdv} function. The arguments for this function are siteNumber, parameterCd, startDate, endDate, and statCd (defaults to \texttt{"}00003\texttt{"}). If you want to use the default values, you do not need to list them in the function call.
+To obtain daily records of USGS data, use the \texttt{readNWISdv} function. The arguments for this function are siteNumber, parameterCd, startDate, endDate, and statCd (defaults to \texttt{"}00003\texttt{"}). If you want to use the default values, you do not need to list them in the function call. Daily data is pulled from \url{http://waterservices.usgs.gov/rest/DV-Test-Tool.html}.
The dates (start and end) must be in the format \texttt{"}YYYY-MM-DD\texttt{"} (note: the user must include the quotes). Setting the start date to \texttt{"}\texttt{"} (no space) will prompt the program to ask for the earliest date, and setting the end date to \texttt{"}\texttt{"} (no space) will prompt for the latest available date.
@@ -482,7 +482,7 @@ discharge <- readNWISdv(siteNumber,
names(discharge)
@
-The column \texttt{"}datetime\texttt{"} in the returned dataframe is automatically imported as a variable of class \texttt{"}Date\texttt{"} in R. Each requested parameter has a value and remark code column. The names of these columns depend on the requested parameter and stat code combinations. USGS daily value qualification codes are often \texttt{"}A\texttt{"} (approved for publication) or \texttt{"}P\texttt{"} (provisional data subject to revision). A more complete list of daily value qualification codes can be found here:
+The column \texttt{"}datetime\texttt{"} in the returned data frame is automatically imported as a variable of class \texttt{"}Date\texttt{"} in R. Each requested parameter has a value and remark code column. The names of these columns depend on the requested parameter and stat code combinations. USGS daily value qualification codes are often \texttt{"}A\texttt{"} (approved for publication) or \texttt{"}P\texttt{"} (provisional data subject to revision). A more complete list of daily value qualification codes can be found here:
\url{http://help.waterdata.usgs.gov/codes-and-parameters/daily-value-qualification-code-dv_rmk_cd}
@@ -500,17 +500,30 @@ temperatureAndFlow <- readNWISdv(siteNumber, parameterCd,
@
-Daily data is pulled from \url{http://waterservices.usgs.gov/rest/DV-Test-Tool.html}.
-The column names can be shortened and simplified using the \texttt{renameNWISColumns} function. This is not necessary, but may streamline subsequent data analysis and presentation.
+The column names can be shortened and simplified using the \texttt{renameNWISColumns} function. This is not necessary, but may streamline subsequent data analysis and presentation. Site information, daily statistic information, and measured parameter information is attached to the data frame as attributes. This is discused further in section \ref{sec:metadata}.
+
<<label=renameColumns, echo=TRUE>>=
names(temperatureAndFlow)
temperatureAndFlow <- renameNWISColumns(temperatureAndFlow)
names(temperatureAndFlow)
+
+@
+
+<<label=attr1, echo=TRUE>>=
+#Information about the data frame attributes:
+names(attributes(temperatureAndFlow))
+
+statInfo <- attr(temperatureAndFlow, "statisticInfo")
+variableInfo <- attr(temperatureAndFlow, "variableInfo")
+siteInfo <- attr(temperatureAndFlow, "siteInfo")
+
@
+
+
An example of plotting the above data (Figure \ref{fig:getNWIStemperaturePlot}):
<<getNWIStemperaturePlot, echo=TRUE, fig.cap="Temperature and discharge plot of Choptank River in 2012.",out.width='1\\linewidth',out.height='1\\linewidth',fig.show='hold'>>=
@@ -538,7 +551,7 @@ There are occasions where NWIS values are not reported as numbers, instead there
\FloatBarrier
%------------------------------------------------------------
-\subsection{Unit Values}
+\subsection{Unit Data}
\label{sec:usgsRT}
%------------------------------------------------------------
Any data collected at regular time intervals (such as 15-minute or hourly) are known as \enquote{unit values.} Many of these are delivered on a real time basis and very recent data (even less than an hour old in many cases) are available through the function \texttt{readNWISuv}. Some of these unit values are available for many years, and some are only available for a recent time period such as 120 days. Here is an example of a retrieval of such data.
@@ -550,6 +563,7 @@ startDate <- "2012-05-12"
endDate <- "2012-05-13"
dischargeUnit <- readNWISuv(siteNumber, parameterCd,
startDate, endDate)
+dischargeUnit <- renameNWISColumns(dischargeUnit)
@
The retrieval produces a data frame that contains 96 rows (one for every 15 minute period in the day). They include all data collected from the startDate through the endDate (starting and ending with midnight locally-collected time). The dateTime column is converted to \enquote{UTC} (Coordinated Universal Time), so midnight EST will be 5 hours earlier in the dateTime column (the previous day, at 7pm).
@@ -574,7 +588,7 @@ America/Phoenix
America/Metlakatla
\end{verbatim}
-Data are retrieved from \url{http://waterservices.usgs.gov/rest/IV-Test-Tool.html}. There are occasions where NWIS values are not reported as numbers, instead a common example is \enquote{Ice.} Any value that cannot be converted to a number will be reported as NA in this package.
+Data are retrieved from \url{http://waterservices.usgs.gov/rest/IV-Test-Tool.html}. There are occasions where NWIS values are not reported as numbers, instead a common example is \enquote{Ice.} Any value that cannot be converted to a number will be reported as NA in this package. Site information and measured parameter information is attached to the data frame as attributes. This is discused further in section \ref{sec:metadata}.
\newpage
@@ -582,7 +596,7 @@ Data are retrieved from \url{http://waterservices.usgs.gov/rest/IV-Test-Tool.htm
\FloatBarrier
%------------------------------------------------------------
-\subsection{Water Quality Values}
+\subsection{Water Quality Data}
\label{sec:usgsWQP}
%------------------------------------------------------------
To get USGS water quality data from water samples collected at the streamgage or other monitoring site (as distinct from unit values collected through some type of automatic monitor) we can use the function \texttt{readNWISqw}, with the input arguments: siteNumber, parameterCd, startDate, and endDate. Additionally, the argument \texttt{"}expanded\texttt{"} is a logical input that allows the user to choose between a simple return of datetimes/qualifier/values (expanded=FALSE), or a more complete and verbose output (expanded=TRUE). Expanded = TRUE includes such columns as remark codes, value qualifying text, and detection level for each parameter code. There also includes an argument \texttt{"}reshape\texttt{"}, that converts the expanded dataset to a \texttt{"}wide\texttt{"} format (each requested parameter code gets individual columns).
@@ -603,7 +617,7 @@ dfLong <- readNWISqw(siteNumber, parameterCd,
@
-Metadata, such as information about the column names can be found by using the \texttt{comment} function, as described in section \ref{sec:metadata}.
+Site information and measured parameter information is attached to the data frame as attributes. This is discused further in section \ref{sec:metadata}. Additional metadata, such as information about the column names can be found by using the \texttt{comment} function, also described in section \ref{sec:metadata}.
<<qwmeta, echo=TRUE, eval=FALSE>>=
@@ -614,10 +628,10 @@ comment(dfLong)
\FloatBarrier
%------------------------------------------------------------
-\subsection{Groundwater level data}
+\subsection{Groundwater Level Data}
\label{sec:gwl}
%------------------------------------------------------------
-Groundwater level measurements can be obtained with the \texttt{readNWISgwl} function. Information on the returned data can be found with the \texttt{comment} function as described in section \ref{sec:metadata}.
+Groundwater level measurements can be obtained with the \texttt{readNWISgwl} function. Information on the returned data can be found with the \texttt{comment} function, and attached attributes as described in section \ref{sec:metadata}.
<<gwlexample, echo=TRUE, eval=TRUE>>=
siteNumber <- "434400121275801"
@@ -628,11 +642,11 @@ names(groundWater)
@
%------------------------------------------------------------
-\subsection{Peak flow data}
+\subsection{Peak Flow Data}
\label{sec:peak}
%------------------------------------------------------------
-Peak flow data are instantaneous discharge or stage data that record the maximum values of these variables during a flood event. They include the annual peak flood event but can also include records of other peaks that are lower than the annual maximum. Peak discharge measurements can be obtained with the \texttt{readNWISpeak} function. Information on the returned data can be found with the \texttt{comment} function as described in section \ref{sec:metadata}.
+Peak flow data are instantaneous discharge or stage data that record the maximum values of these variables during a flood event. They include the annual peak flood event but can also include records of other peaks that are lower than the annual maximum. Peak discharge measurements can be obtained with the \texttt{readNWISpeak} function. Information on the returned data can be found with the \texttt{comment} function and attached attributes as described in section \ref{sec:metadata}.
<<peakexample, echo=TRUE, eval=TRUE>>=
siteNumber <- '01594440'
@@ -645,10 +659,10 @@ names(peakData)
%------------------------------------------------------------
-\subsection{Rating curve data}
+\subsection{Rating Curve Data}
\label{sec:rating}
%------------------------------------------------------------
-Rating curves are the calibration curves that are used to convert measurements of stage to discharge. Because of changing hydrologic conditions these rating curves change over time. Information on the returned data can be found with the \texttt{comment} function as described in section \ref{sec:metadata}.
+Rating curves are the calibration curves that are used to convert measurements of stage to discharge. Because of changing hydrologic conditions these rating curves change over time. Information on the returned data can be found with the \texttt{comment} function and attached attributes as described in section \ref{sec:metadata}.
Rating curves can be obtained with the \texttt{readNWISrating} function.
@@ -663,10 +677,10 @@ names(ratingData)
%------------------------------------------------------------
-\subsection{Surface-water measurement data}
+\subsection{Surface-Water Measurement Data}
\label{sec:meas}
%------------------------------------------------------------
-These data are the discrete measurements of discharge that are made for the purpose of developing or revising the rating curve. Information on the returned data can be found with the \texttt{comment} function as described in section \ref{sec:metadata}.
+These data are the discrete measurements of discharge that are made for the purpose of developing or revising the rating curve. Information on the returned data can be found with the \texttt{comment} function and attached attributes as described in section \ref{sec:metadata}.
Surface-water measurement data can be obtained with the \texttt{readNWISmeas} function.
@@ -711,7 +725,7 @@ specificCond <- readWQPqw('WIDNR_WQX-10032762',
'Specific conductance','2011-05-01','2011-09-30')
@
-A tool for finding NWIS characteristic names can be found at: \url{http://www.waterqualitydata.us/public_srsnames.jsp}
+A tool for finding NWIS characteristic names can be found at: \url{http://www.waterqualitydata.us/public_srsnames.jsp}.
\FloatBarrier
@@ -722,7 +736,7 @@ A tool for finding NWIS characteristic names can be found at: \url{http://www.wa
The previous examples all took specific input arguments: siteNumber, parameterCd (or characteristic name), startDate, endDate, etc. However, the Web services that supply the data can accept a wide variety of additional arguments.
%------------------------------------------------------------
-\subsubsection{NWIS sites}
+\subsubsection{NWIS Sites}
\label{sec:NWISGenSite}
%------------------------------------------------------------
The function \texttt{whatNWISsites} can be used to discover NWIS sites based on any query that the NWIS Site Service offers. This is done by using the \texttt{"..."} argument, which allows the user to use any arbitrary input argument. We can then use the service here:
@@ -746,7 +760,7 @@ nrow(sites)
%------------------------------------------------------------
-\subsubsection{NWIS data}
+\subsubsection{NWIS Data}
\label{sec:NWISGenData}
%------------------------------------------------------------
For NWIS data, the function \texttt{readNWISdata} can be used. The argument listed in the R help file is \texttt{"..."} and \texttt{"}service\texttt{"} (only for data requests). Table \ref{tab:NWISGeneral} describes the services are available.
@@ -782,10 +796,14 @@ dischargeWI <- readNWISdata(service="dv",
statCd="00003")
names(dischargeWI)
nrow(dischargeWI)
+
+siteInfo <- attr(dischargeWI, "siteInfo")
+head(siteInfo)
+
@
%------------------------------------------------------------
-\subsubsection{Water Quality Portal sites}
+\subsubsection{WQP Sites}
\label{sec:WQPGenSite}
%------------------------------------------------------------
@@ -804,7 +822,7 @@ sitesNJ <- whatWQPsites(statecode="US:34",
%------------------------------------------------------------
-\subsubsection{Water Quality Portal data}
+\subsubsection{WQP Data}
\label{sec:WQPGenData}
%------------------------------------------------------------
Finally, to get data from the WQP using generalized Web service calls, use the function \texttt{readWQPdata}. For example, to get all the pH data in Wisconsin:
@@ -823,10 +841,10 @@ dataPH <- readWQPdata(statecode="US:55",
\clearpage
%------------------------------------------------------------
-\section{Dataframe Metadata}
+\section{Embedded Metadata}
\label{sec:metadata}
%------------------------------------------------------------
-All dataframes returned from the Web services have some form of associated metadata. This information is included as attributes to the dataframe. All dataframes will have a \texttt{url} and \texttt{queryTime} attribute. For example, the url and query time used to obtain the data can be found as follows:
+All data frames returned from the Web services have some form of associated metadata. This information is included as attributes to the data frame. All data frames will have a \texttt{url} (returning a character of the url used to obtain the data), \texttt{siteInfo} (returning a data frame with information on sites), and \texttt{queryTime} (returning a POSIXct datetime) attributes. For example, the url and query time used to obtain the data can be found as follows:
<<meta1, eval=TRUE>>=
@@ -834,9 +852,11 @@ attr(dischargeWI, "url")
attr(dischargeWI, "queryTime")
+siteInfo <- attr(dischargeWI, "siteInfo")
+
@
-Depending on the format that the data was obtained (xml, rdb, etc), there will be additional information embedded in the dataframe as attributes. To discover the available attributes:
+Depending on the format that the data was obtained (RDB, WaterML1, etc), there will be additional information embedded in the data frame as attributes. To discover the available attributes:
<<meta2, eval=TRUE>>=
@@ -924,10 +944,10 @@ library(dataRetrieval)
%------------------------------------------------------------
-\section{Creating tables in Microsoft\textregistered\ software from R}
+\section{Creating Tables in Microsoft\textregistered\ Software from R}
\label{app:createWordTable}
%------------------------------------------------------------
-There are a few steps that are required in order to create a table in Microsoft\textregistered\ software (Excel, Word, PowerPoint, etc.) from an R dataframe. There are certainly a variety of good methods, one of which is detailed here. The example we will step through here will be to create a table in Microsoft Excel based on the dataframe tableData:
+There are a few steps that are required in order to create a table in Microsoft\textregistered\ software (Excel, Word, PowerPoint, etc.) from an R data frame. There are certainly a variety of good methods, one of which is detailed here. The example we will step through here will be to create a table in Microsoft Excel based on the data frame tableData:
<<label=getSiteApp, echo=TRUE>>=
availableData <- whatNWISdata(siteNumber, "dv")
@@ -944,7 +964,7 @@ tableData <- with(dailyData,
tableData
@
-First, save the dataframe as a tab delimited file (you don't want to use comma delimited because there are commas in some of the data elements):
+First, save the data frame as a tab delimited file (you don't want to use comma delimited because there are commas in some of the data elements):
<<label=saveData, echo=TRUE, eval=FALSE>>=
diff --git a/man/readNWISqw.Rd b/man/readNWISqw.Rd
index effe8cb5a177f24e46086667072b7debe90a4bb5..71264b87b1ea0a4637b1dafd44204d8e43702dc2 100644
--- a/man/readNWISqw.Rd
+++ b/man/readNWISqw.Rd
@@ -42,11 +42,6 @@ tz_cd \tab character \tab The time zone code for datetime \cr
code \tab character \tab Any codes that qualify the corresponding value\cr
value \tab numeric \tab The numeric value for the parameter \cr
}
-Note that code and value are repeated for the parameters requested. The names are of the form
-X_D_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).
There are also several useful attributes attached to the data frame:
\tabular{lll}{
diff --git a/vignettes/Rhelp.png b/vignettes/Rhelp.png
index 453786664e0501c3ef8b4fe2073c18fbd363ccac..6d2b436aa3d6c83f52f4c3a10463f8ed26d5944c 100644
Binary files a/vignettes/Rhelp.png and b/vignettes/Rhelp.png differ
diff --git a/vignettes/dataRetrieval-concordance.tex b/vignettes/dataRetrieval-concordance.tex
deleted file mode 100644
index 9af5b0742a302be2bfc9e12ca7aaa21ecb567036..0000000000000000000000000000000000000000
--- a/vignettes/dataRetrieval-concordance.tex
+++ /dev/null
@@ -1,9 +0,0 @@
-\Sconcordance{concordance:dataRetrieval.tex:dataRetrieval.Rnw:%
-1 127 1 49 0 1 7 15 1 1 14 47 1 3 0 97 1 2 0 8 1 9 0 %
-31 1 3 0 21 1 4 0 6 1 8 0 7 1 4 0 23 1 2 0 21 1 1 8 %
-19 1 9 0 6 1 7 0 26 1 7 0 18 1 2 0 11 1 15 0 21 1 8 0 %
-20 1 3 0 7 1 20 0 44 1 2 0 8 1 2 0 16 1 9 0 16 1 10 0 %
-17 1 13 0 17 1 14 0 20 1 4 0 14 1 4 0 33 1 13 0 40 1 %
-13 0 18 1 2 0 14 1 2 0 20 1 9 0 8 1 7 0 12 1 25 0 9 1 %
-4 0 7 1 29 0 19 1 4 0 15 1 4 0 11 1 4 0 5 1 4 0 22 1 %
-14 0 8 1 4 0 43 1}
diff --git a/vignettes/dataRetrieval.Rnw b/vignettes/dataRetrieval.Rnw
index 0a4cd78aa55ddc76915f99d89bf14214f13a1ddf..58601b00d1328ada9477b97cf95b2f4e60e46cce 100644
--- a/vignettes/dataRetrieval.Rnw
+++ b/vignettes/dataRetrieval.Rnw
@@ -274,9 +274,9 @@ Table \ref{tab:func} describes the functions available in the dataRetrieval pack
\section{USGS Web Retrievals}
\label{sec:genRetrievals}
%------------------------------------------------------------
-In this section, examples of Web retrievals document how to get raw data. This data includes site information (\ref{sec:usgsSite}), measured parameter information (\ref{sec:usgsParams}), historical daily values(\ref{sec:usgsDaily}), unit values (which include real-time data but can also include other sensor data stored at regular time intervals) (\ref{sec:usgsRT}), water quality data (\ref{sec:usgsWQP}), groundwater level data (\ref{sec:gwl}), peak flow data (\ref{sec:peak}), rating curve data (\ref{sec:rating}, and surface-water measurement data (\ref{sec:meas}). Section \ref{sec:metadata} shows instructions for getting metadata that is attached to each returned dataframe.
+In this section, examples of Web retrievals document how to get raw data. This data includes site information (\ref{sec:usgsSite}), measured parameter information (\ref{sec:usgsParams}), historical daily values(\ref{sec:usgsDaily}), unit values (which include real-time data but can also include other sensor data stored at regular time intervals) (\ref{sec:usgsRT}), water quality data (\ref{sec:usgsWQP}), groundwater level data (\ref{sec:gwl}), peak flow data (\ref{sec:peak}), rating curve data (\ref{sec:rating}, and surface-water measurement data (\ref{sec:meas}). Section \ref{sec:metadata} shows instructions for getting metadata that is attached to each returned data frame.
-The USGS organizes hydrologic data in a standard structure. Streamgages are located throughout the United States, and each streamgage has a unique ID (referred in this document and throughout the dataRetrieval package as \enquote{siteNumber}). Often (but not always), these ID's are 8 digits. The first step to finding data is discovering this siteNumber. There are many ways to do this, one is the National Water Information System: Mapper \url{http://maps.waterdata.usgs.gov/mapper/index.html}.
+The USGS organizes hydrologic data in a standard structure. Streamgages are located throughout the United States, and each streamgage has a unique ID (referred in this document and throughout the dataRetrieval package as \enquote{siteNumber}). Often (but not always), these ID's are 8 digits for streamgages, and 15 digits for groundwater gages. The first step to finding data is discovering this siteNumber. There are many ways to do this, one is the National Water Information System: Mapper \url{http://maps.waterdata.usgs.gov/mapper/index.html}.
Once the siteNumber is known, the next required input for USGS data retrievals is the \enquote{parameter code}. This is a 5-digit code that specifies the measured parameter being requested. For example, parameter code 00631 represents \enquote{Nitrate plus nitrite, water, filtered, milligrams per liter as nitrogen}, with units of \enquote{mg/l as N}.
@@ -433,7 +433,7 @@ print(xtable(tableData,label="tab:gda",
-See Section \ref{app:createWordTable} for instructions on converting an R dataframe to a table in Microsoft\textregistered\ software Excel or Word to display a data availability table similar to Table \ref{tab:gda}. Excel, Microsoft, PowerPoint, Windows, and Word are registered trademarks of Microsoft Corporation in the United States and other countries.
+See Section \ref{app:createWordTable} for instructions on converting an R data frame to a table in Microsoft\textregistered\ software Excel or Word to display a data availability table similar to Table \ref{tab:gda}. Excel, Microsoft, PowerPoint, Windows, and Word are registered trademarks of Microsoft Corporation in the United States and other countries.
\FloatBarrier
@@ -465,7 +465,7 @@ Parameter information can obtained from:
\subsection{Daily Data}
\label{sec:usgsDaily}
%------------------------------------------------------------
-To obtain daily records of USGS data, use the \texttt{readNWISdv} function. The arguments for this function are siteNumber, parameterCd, startDate, endDate, and statCd (defaults to \texttt{"}00003\texttt{"}). If you want to use the default values, you do not need to list them in the function call.
+To obtain daily records of USGS data, use the \texttt{readNWISdv} function. The arguments for this function are siteNumber, parameterCd, startDate, endDate, and statCd (defaults to \texttt{"}00003\texttt{"}). If you want to use the default values, you do not need to list them in the function call. Daily data is pulled from \url{http://waterservices.usgs.gov/rest/DV-Test-Tool.html}.
The dates (start and end) must be in the format \texttt{"}YYYY-MM-DD\texttt{"} (note: the user must include the quotes). Setting the start date to \texttt{"}\texttt{"} (no space) will prompt the program to ask for the earliest date, and setting the end date to \texttt{"}\texttt{"} (no space) will prompt for the latest available date.
@@ -482,7 +482,7 @@ discharge <- readNWISdv(siteNumber,
names(discharge)
@
-The column \texttt{"}datetime\texttt{"} in the returned dataframe is automatically imported as a variable of class \texttt{"}Date\texttt{"} in R. Each requested parameter has a value and remark code column. The names of these columns depend on the requested parameter and stat code combinations. USGS daily value qualification codes are often \texttt{"}A\texttt{"} (approved for publication) or \texttt{"}P\texttt{"} (provisional data subject to revision). A more complete list of daily value qualification codes can be found here:
+The column \texttt{"}datetime\texttt{"} in the returned data frame is automatically imported as a variable of class \texttt{"}Date\texttt{"} in R. Each requested parameter has a value and remark code column. The names of these columns depend on the requested parameter and stat code combinations. USGS daily value qualification codes are often \texttt{"}A\texttt{"} (approved for publication) or \texttt{"}P\texttt{"} (provisional data subject to revision). A more complete list of daily value qualification codes can be found here:
\url{http://help.waterdata.usgs.gov/codes-and-parameters/daily-value-qualification-code-dv_rmk_cd}
@@ -500,17 +500,30 @@ temperatureAndFlow <- readNWISdv(siteNumber, parameterCd,
@
-Daily data is pulled from \url{http://waterservices.usgs.gov/rest/DV-Test-Tool.html}.
-The column names can be shortened and simplified using the \texttt{renameNWISColumns} function. This is not necessary, but may streamline subsequent data analysis and presentation.
+The column names can be shortened and simplified using the \texttt{renameNWISColumns} function. This is not necessary, but may streamline subsequent data analysis and presentation. Site information, daily statistic information, and measured parameter information is attached to the data frame as attributes. This is discused further in section \ref{sec:metadata}.
+
<<label=renameColumns, echo=TRUE>>=
names(temperatureAndFlow)
temperatureAndFlow <- renameNWISColumns(temperatureAndFlow)
names(temperatureAndFlow)
+
+@
+
+<<label=attr1, echo=TRUE>>=
+#Information about the data frame attributes:
+names(attributes(temperatureAndFlow))
+
+statInfo <- attr(temperatureAndFlow, "statisticInfo")
+variableInfo <- attr(temperatureAndFlow, "variableInfo")
+siteInfo <- attr(temperatureAndFlow, "siteInfo")
+
@
+
+
An example of plotting the above data (Figure \ref{fig:getNWIStemperaturePlot}):
<<getNWIStemperaturePlot, echo=TRUE, fig.cap="Temperature and discharge plot of Choptank River in 2012.",out.width='1\\linewidth',out.height='1\\linewidth',fig.show='hold'>>=
@@ -550,6 +563,7 @@ startDate <- "2012-05-12"
endDate <- "2012-05-13"
dischargeUnit <- readNWISuv(siteNumber, parameterCd,
startDate, endDate)
+dischargeUnit <- renameNWISColumns(dischargeUnit)
@
The retrieval produces a data frame that contains 96 rows (one for every 15 minute period in the day). They include all data collected from the startDate through the endDate (starting and ending with midnight locally-collected time). The dateTime column is converted to \enquote{UTC} (Coordinated Universal Time), so midnight EST will be 5 hours earlier in the dateTime column (the previous day, at 7pm).
@@ -574,7 +588,7 @@ America/Phoenix
America/Metlakatla
\end{verbatim}
-Data are retrieved from \url{http://waterservices.usgs.gov/rest/IV-Test-Tool.html}. There are occasions where NWIS values are not reported as numbers, instead a common example is \enquote{Ice.} Any value that cannot be converted to a number will be reported as NA in this package.
+Data are retrieved from \url{http://waterservices.usgs.gov/rest/IV-Test-Tool.html}. There are occasions where NWIS values are not reported as numbers, instead a common example is \enquote{Ice.} Any value that cannot be converted to a number will be reported as NA in this package. Site information and measured parameter information is attached to the data frame as attributes. This is discused further in section \ref{sec:metadata}.
\newpage
@@ -603,7 +617,7 @@ dfLong <- readNWISqw(siteNumber, parameterCd,
@
-Metadata, such as information about the column names can be found by using the \texttt{comment} function, as described in section \ref{sec:metadata}.
+Site information and measured parameter information is attached to the data frame as attributes. This is discused further in section \ref{sec:metadata}. Additional metadata, such as information about the column names can be found by using the \texttt{comment} function, also described in section \ref{sec:metadata}.
<<qwmeta, echo=TRUE, eval=FALSE>>=
@@ -617,7 +631,7 @@ comment(dfLong)
\subsection{Groundwater Level Data}
\label{sec:gwl}
%------------------------------------------------------------
-Groundwater level measurements can be obtained with the \texttt{readNWISgwl} function. Information on the returned data can be found with the \texttt{comment} function as described in section \ref{sec:metadata}.
+Groundwater level measurements can be obtained with the \texttt{readNWISgwl} function. Information on the returned data can be found with the \texttt{comment} function, and attached attributes as described in section \ref{sec:metadata}.
<<gwlexample, echo=TRUE, eval=TRUE>>=
siteNumber <- "434400121275801"
@@ -632,7 +646,7 @@ names(groundWater)
\label{sec:peak}
%------------------------------------------------------------
-Peak flow data are instantaneous discharge or stage data that record the maximum values of these variables during a flood event. They include the annual peak flood event but can also include records of other peaks that are lower than the annual maximum. Peak discharge measurements can be obtained with the \texttt{readNWISpeak} function. Information on the returned data can be found with the \texttt{comment} function as described in section \ref{sec:metadata}.
+Peak flow data are instantaneous discharge or stage data that record the maximum values of these variables during a flood event. They include the annual peak flood event but can also include records of other peaks that are lower than the annual maximum. Peak discharge measurements can be obtained with the \texttt{readNWISpeak} function. Information on the returned data can be found with the \texttt{comment} function and attached attributes as described in section \ref{sec:metadata}.
<<peakexample, echo=TRUE, eval=TRUE>>=
siteNumber <- '01594440'
@@ -648,7 +662,7 @@ names(peakData)
\subsection{Rating Curve Data}
\label{sec:rating}
%------------------------------------------------------------
-Rating curves are the calibration curves that are used to convert measurements of stage to discharge. Because of changing hydrologic conditions these rating curves change over time. Information on the returned data can be found with the \texttt{comment} function as described in section \ref{sec:metadata}.
+Rating curves are the calibration curves that are used to convert measurements of stage to discharge. Because of changing hydrologic conditions these rating curves change over time. Information on the returned data can be found with the \texttt{comment} function and attached attributes as described in section \ref{sec:metadata}.
Rating curves can be obtained with the \texttt{readNWISrating} function.
@@ -666,7 +680,7 @@ names(ratingData)
\subsection{Surface-Water Measurement Data}
\label{sec:meas}
%------------------------------------------------------------
-These data are the discrete measurements of discharge that are made for the purpose of developing or revising the rating curve. Information on the returned data can be found with the \texttt{comment} function as described in section \ref{sec:metadata}.
+These data are the discrete measurements of discharge that are made for the purpose of developing or revising the rating curve. Information on the returned data can be found with the \texttt{comment} function and attached attributes as described in section \ref{sec:metadata}.
Surface-water measurement data can be obtained with the \texttt{readNWISmeas} function.
@@ -711,7 +725,7 @@ specificCond <- readWQPqw('WIDNR_WQX-10032762',
'Specific conductance','2011-05-01','2011-09-30')
@
-A tool for finding NWIS characteristic names can be found at: \url{http://www.waterqualitydata.us/public_srsnames.jsp}
+A tool for finding NWIS characteristic names can be found at: \url{http://www.waterqualitydata.us/public_srsnames.jsp}.
\FloatBarrier
@@ -782,6 +796,10 @@ dischargeWI <- readNWISdata(service="dv",
statCd="00003")
names(dischargeWI)
nrow(dischargeWI)
+
+siteInfo <- attr(dischargeWI, "siteInfo")
+head(siteInfo)
+
@
%------------------------------------------------------------
@@ -823,10 +841,10 @@ dataPH <- readWQPdata(statecode="US:55",
\clearpage
%------------------------------------------------------------
-\section{Dataframe Metadata}
+\section{Embedded Metadata}
\label{sec:metadata}
%------------------------------------------------------------
-All dataframes returned from the Web services have some form of associated metadata. This information is included as attributes to the dataframe. All dataframes will have a \texttt{url} and \texttt{queryTime} attribute. For example, the url and query time used to obtain the data can be found as follows:
+All data frames returned from the Web services have some form of associated metadata. This information is included as attributes to the data frame. All data frames will have a \texttt{url} (returning a character of the url used to obtain the data), \texttt{siteInfo} (returning a data frame with information on sites), and \texttt{queryTime} (returning a POSIXct datetime) attributes. For example, the url and query time used to obtain the data can be found as follows:
<<meta1, eval=TRUE>>=
@@ -834,9 +852,11 @@ attr(dischargeWI, "url")
attr(dischargeWI, "queryTime")
+siteInfo <- attr(dischargeWI, "siteInfo")
+
@
-Depending on the format that the data was obtained (RDB, WaterML1, etc), there will be additional information embedded in the dataframe as attributes. To discover the available attributes:
+Depending on the format that the data was obtained (RDB, WaterML1, etc), there will be additional information embedded in the data frame as attributes. To discover the available attributes:
<<meta2, eval=TRUE>>=
@@ -927,7 +947,7 @@ library(dataRetrieval)
\section{Creating Tables in Microsoft\textregistered\ Software from R}
\label{app:createWordTable}
%------------------------------------------------------------
-There are a few steps that are required in order to create a table in Microsoft\textregistered\ software (Excel, Word, PowerPoint, etc.) from an R dataframe. There are certainly a variety of good methods, one of which is detailed here. The example we will step through here will be to create a table in Microsoft Excel based on the dataframe tableData:
+There are a few steps that are required in order to create a table in Microsoft\textregistered\ software (Excel, Word, PowerPoint, etc.) from an R data frame. There are certainly a variety of good methods, one of which is detailed here. The example we will step through here will be to create a table in Microsoft Excel based on the data frame tableData:
<<label=getSiteApp, echo=TRUE>>=
availableData <- whatNWISdata(siteNumber, "dv")
@@ -944,7 +964,7 @@ tableData <- with(dailyData,
tableData
@
-First, save the dataframe as a tab delimited file (you don't want to use comma delimited because there are commas in some of the data elements):
+First, save the data frame as a tab delimited file (you don't want to use comma delimited because there are commas in some of the data elements):
<<label=saveData, echo=TRUE, eval=FALSE>>=
diff --git a/vignettes/figure/getNWIStemperaturePlot-1.pdf b/vignettes/figure/getNWIStemperaturePlot-1.pdf
index 9a0cdfe9bc5c70f5ae9a948fddaa97ea349277b9..214cf0b6958302a89a86e16f88a2af155596d717 100644
Binary files a/vignettes/figure/getNWIStemperaturePlot-1.pdf and b/vignettes/figure/getNWIStemperaturePlot-1.pdf differ