From 9b63b774c0adad0a2473807607132bbf9696ea08 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Fri, 19 May 2017 13:28:43 -0500 Subject: [PATCH 1/6] Convert to markdown --- DESCRIPTION | 4 +- inst/doc/dataRetrieval.R | 251 +++-- inst/doc/dataRetrieval.Rmd | 763 ++++++++++++++ inst/doc/dataRetrieval.Rnw | 960 ------------------ inst/doc/dataRetrieval.html | 903 ++++++++++++++++ inst/doc/dataRetrieval.pdf | Bin 246357 -> 0 bytes vignettes/dataRetrieval.Rmd | 763 ++++++++++++++ vignettes/dataRetrieval.Rnw | 960 ------------------ vignettes/figure/egretEx.pdf | Bin 45187 -> 0 bytes vignettes/figure/getNWISUnitPlot.pdf | Bin 13636 -> 0 bytes vignettes/figure/getNWIStemperaturePlot-1.pdf | Bin 6597 -> 0 bytes vignettes/figure/getQWtemperaturePlot-1.pdf | Bin 35906 -> 0 bytes vignettes/figure/getQWtemperaturePlot.pdf | Bin 8435 -> 0 bytes 13 files changed, 2607 insertions(+), 1997 deletions(-) create mode 100644 inst/doc/dataRetrieval.Rmd delete mode 100644 inst/doc/dataRetrieval.Rnw create mode 100644 inst/doc/dataRetrieval.html delete mode 100644 inst/doc/dataRetrieval.pdf create mode 100644 vignettes/dataRetrieval.Rmd delete mode 100644 vignettes/dataRetrieval.Rnw delete mode 100644 vignettes/figure/egretEx.pdf delete mode 100644 vignettes/figure/getNWISUnitPlot.pdf delete mode 100644 vignettes/figure/getNWIStemperaturePlot-1.pdf delete mode 100644 vignettes/figure/getQWtemperaturePlot-1.pdf delete mode 100644 vignettes/figure/getQWtemperaturePlot.pdf diff --git a/DESCRIPTION b/DESCRIPTION index 37105f77..8990c3b3 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -39,11 +39,11 @@ Imports: readr (>= 1.0.0), jsonlite Suggests: - xtable, + htmlTable, knitr, testthat -VignetteBuilder: knitr BuildVignettes: true +VignetteBuilder: knitr BugReports: https://github.com/USGS-R/dataRetrieval/issues URL: https://pubs.usgs.gov/tm/04/a10/ RoxygenNote: 6.0.1 diff --git a/inst/doc/dataRetrieval.R b/inst/doc/dataRetrieval.R index c915b2b5..b4abb4d6 100644 --- a/inst/doc/dataRetrieval.R +++ b/inst/doc/dataRetrieval.R @@ -1,24 +1,22 @@ -## ----openLibrary, echo=FALSE------------------------------ -library(xtable) -options(continue=" ") -options(width=60) +## ----setup, include=FALSE, message=FALSE------------------ library(knitr) +library(dataRetrieval) - -## ----include=TRUE ,echo=FALSE,eval=TRUE------------------- -opts_chunk$set(highlight=TRUE, tidy=TRUE, keep.space=TRUE, keep.blank.space=FALSE, keep.comment=TRUE, tidy=FALSE,comment="") +options(continue=" ") +options(width=60) +knitr::opts_chunk$set(echo = TRUE, + warning = FALSE, + message = FALSE, + fig.height = 7, + fig.width = 7) + +opts_chunk$set(highlight=TRUE, + tidy=TRUE, + keep.space=TRUE, + keep.blank.space=FALSE, + keep.comment=TRUE) knit_hooks$set(inline = function(x) { if (is.numeric(x)) round(x, 3)}) -knit_hooks$set(crop = hook_pdfcrop) - -bold.colHeaders <- function(x) { - x <- gsub("\\^(\\d)","$\\^\\1$",x) - x <- gsub("\\%","\\\\%",x) - x <- gsub("\\_"," ",x) - returnX <- paste("\\multicolumn{1}{c}{\\textbf{\\textsf{", x, "}}}", sep = "") -} -addSpace <- function(x) ifelse(x != "1", "[5pt]","") -library(dataRetrieval) ## ----workflow, echo=TRUE,eval=FALSE----------------------- # library(dataRetrieval) @@ -39,38 +37,98 @@ library(dataRetrieval) # pCode <- readNWISpCode(parameterCd) # -## ----tableParameterCodes, echo=FALSE,results='asis'------- +## ----echo=FALSE------------------------------------------- + +library(htmlTable) + +Functions <- c("readNWISdata","", + "readNWISdv","","","","", + "readNWISqw","","","","", + "readNWISuv","","","", + "readNWISrating","", + "readNWISmeas","","", + "readNWISpeak","","", + "readNWISgwl","","", + "readNWISuse","","","", + "readNWISstat","","","","","", + "readNWISpCode", + "readNWISsite", + "whatNWISsites", + "whatNWISdata","", + "readWQPdata", + "readWQPqw","","","", + "whatWQPsites") +Arguments <- c("...","service", #readNWISdata + "siteNumber","parameterCd","startDate","endDate","statCd", #readNWISdv + "siteNumber","parameterCd","startDate","endDate","expanded", #readNWISqw + "siteNumber","parameterCd","startDate","endDate", #readNWISuv + "siteNumber","type", #readNWISrating + "siteNumber","startDate","endDate", #readNWISmeas + "siteNumber","startDate","endDate", #readNWISpeak + "siteNumber","startDate","endDate", #readNWISgwl + "stateCd","countyCd","years","categories", #readNWISuse + "siteNumbers","parameterCd","startDate","endDate","statReportType","statType", #readNWISstat + "parameterCd", #readNWISpCode + "siteNumber", #readNWISsite + "...", #whatNWISsites + "siteNumber","service", #whatNWISdata + "...", #readWQPdata + "siteNumber","parameterCd","startDate","endDate", #readWQPqw + "...") #whatWQPsites +Description <- c("NWIS data using user-specified queries","", #readNWISdata + "NWIS daily data","","","","", #readNWISdv + "NWIS water quality data","","","","", #readNWISqw + "NWIS instantaneous value data","","","", #readNWISuv + "NWIS rating table for active streamgage","", #readNWISrating + "NWIS surface-water measurements","","", #readNWISmeas + "NWIS peak flow data","","", #readNWISpeak + "NWIS groundwater level measurements","","", #readNWISgwl + "NWIS water use","","","", #readNWISuse + "NWIS statistical service","","","","","", #readNWISstat + "NWIS parameter code information", #readNWISpCode + "NWIS site information", #readNWISsite + "NWIS site search using user-specified queries", + "NWIS data availability, including period of record and count","", + "WQP data using user-specified queries", + "WQP data","","","", + "WQP site search using user-specified queries") + +data.df <- data.frame(`Function Name` = Functions, Arguments, Description, stringsAsFactors=FALSE) + +htmlTable(data.df, + caption="Table 1: dataRetrieval functions", + rnames=FALSE, align=c("l","l","l","l"), + col.rgroup = c("none", "#F7F7F7"), + css.cell="padding-bottom: 0.0em; padding-right: 0.5em; padding-top: 0.0em;") + + +## ----tableParameterCodes, echo=FALSE---------------------- + + pCode <- c('00060', '00065', '00010','00045','00400') -shortName <- c("Discharge [ft$^3$/s]","Gage height [ft]","Temperature [C]", "Precipitation [in]", "pH") +shortName <- c("Discharge [ft3/s]","Gage height [ft]","Temperature [C]", "Precipitation [in]", "pH") data.df <- data.frame(pCode, shortName, stringsAsFactors=FALSE) -print(xtable(data.df, - label="tab:params", - caption="Common USGS Parameter Codes"), - caption.placement="top", - size = "\\footnotesize", - latex.environment=NULL, - sanitize.text.function = function(x) {x}, - sanitize.colnames.function = bold.colHeaders, - sanitize.rownames.function = addSpace - ) +htmlTable(data.df, + caption="Table 2: Common USGS Parameter Codes", + rnames=FALSE, align=c("c","c"), col.rgroup = c("none", "#F7F7F7"), + css.cell="padding-bottom: 0.0em; padding-right: 0.5em; padding-top: 0.0em;") -## ----tableStatCodes, echo=FALSE,results='asis'------------ + +## ----tableStatCodes, echo=FALSE--------------------------- StatCode <- c('00001', '00002', '00003','00008') shortName <- c("Maximum","Minimum","Mean", "Median") data.df <- data.frame(StatCode, shortName, stringsAsFactors=FALSE) -print(xtable(data.df,label="tab:stat", - caption="Commonly used USGS Stat Codes"), - caption.placement="top", - size = "\\footnotesize", - latex.environment=NULL, - sanitize.colnames.function = bold.colHeaders, - sanitize.rownames.function = addSpace - ) +htmlTable(data.df, + caption="Table 3: Commonly used USGS Stat Codes", + rnames=FALSE, align=c("c","c"), col.rgroup = c("none", "#F7F7F7"), + css.cell="padding-bottom: 0.0em; padding-right: 0.5em; padding-top: 0.0em;") + + ## ----getSite, echo=TRUE, eval=FALSE----------------------- @@ -89,33 +147,28 @@ print(xtable(data.df,label="tab:stat", # # -## ----tablegda, echo=FALSE,eval=FALSE---------------------- -# tableData <- with(dailyDataAvailable, -# data.frame( -# siteNumber= site_no, -# srsname=srsname, -# startDate=as.character(begin_date), -# endDate=as.character(end_date), -# count=as.character(count_nu), -# units=parameter_units, -# # statCd = stat_cd, -# stringsAsFactors=FALSE) -# ) -# -# tableData$units[which(tableData$units == "ft3/s")] <- "ft$^3$/s" -# tableData$units[which(tableData$units == "uS/cm @25C")] <- "$\\mu$S/cm @25C" -# -# -# print(xtable(tableData,label="tab:gda", -# caption="Reformatted version of output from \\texttt{whatNWISdata} function for the Choptank River near Greensboro, MD, and from Seneca Creek at Dawsonville, MD from the daily values service [Some columns deleted for space considerations]"), -# caption.placement="top", -# size = "\\footnotesize", -# latex.environment=NULL, -# sanitize.text.function = function(x) {x}, -# sanitize.colnames.function = bold.colHeaders, -# sanitize.rownames.function = addSpace -# ) -# +## ----echo=FALSE------------------------------------------- + +tableData <- data.frame( + siteNumber = c("01491000","01491000","01645000","01491000","01491000","01491000"), + srsname = c("Temperature, water","Stream flow, mean daily", + "Stream flow, mean daily", + "Specific conductance", + "Suspended sediment concentration (SSC)", + "Suspended sediment discharge" ), + startDate = c("2010-10-01","1948-01-01","1930-09-26","2010-10-01","1980-10-01","1980-10-01"), + endDate = c("2012-05-09","2017-05-17","2017-05-17","2012-05-09","1991-09-30","1991-09-30"), + count = c("529","25340","31646","527","4017","4017"), + units = c("deg C","ft3/s","ft3/s","uS/cm @25C","mg/l","tons/day"), + stringsAsFactors = FALSE) + + +htmlTable(tableData, + caption="Table 4: Reformatted version of output from the whatNWISdata function for the Choptank River near Greensboro, MD, and from Seneca Creek at Dawsonville, MD from the daily values service [Some columns deleted for space considerations]", + rnames=FALSE, + col.rgroup = c("none", "#F7F7F7"), + css.cell="padding-bottom: 0.0em; padding-right: 0.5em; padding-top: 0.0em;") + ## ----label=getPCodeInfo, echo=TRUE, eval=FALSE------------ # # Using defaults: @@ -167,7 +220,7 @@ 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") @@ -205,8 +258,8 @@ legend("topleft", variableInfo$param_units, # startDate, endDate) # # # Or the wide return: -# # dfWide <- readNWISqw(siteNumber, parameterCd, -# # startDate, endDate, reshape=TRUE) +# dfWide <- readNWISqw(siteNumber, parameterCd, +# startDate, endDate, reshape=TRUE) # ## ----qwmeta, echo=TRUE, eval=FALSE------------------------ @@ -232,15 +285,57 @@ legend("topleft", variableInfo$param_units, # surfaceData <- readNWISmeas(siteNumber) # +## ----eval=FALSE------------------------------------------- +# allegheny <- readNWISuse(stateCd = "Pennsylvania", +# countyCd = "Allegheny") +# +# +# national <- readNWISuse(stateCd = NULL, +# countyCd = NULL, +# transform = TRUE) +# + +## ----eval=FALSE------------------------------------------- +# discharge_stats <- readNWISstat(siteNumbers=c("02319394"), +# parameterCd=c("00060"), +# statReportType="annual") +# + ## ----label=getQWData, echo=TRUE, eval=FALSE--------------- # specificCond <- readWQPqw('WIDNR_WQX-10032762', -# 'Specific conductance','2011-05-01','2011-09-30') +# 'Specific conductance', +# '2011-05-01','2011-09-30') ## ----siteSearch, eval=FALSE------------------------------- # sites <- whatNWISsites(bBox=c(-83.0,36.5,-81.0,38.5), # parameterCd=c("00010","00060"), # hasDataTypeCd="dv") +## ----echo=FALSE------------------------------------------- + +Service <- c("dv","iv","gwlevels","qwdata","measurements","peak","stat") +Description <- c("Daily","Instantaneous","Groundwater Levels","Water Quality","Surface Water Measurements","Peak Flow","Statistics Service") +URL <- c("https://waterservices.usgs.gov/rest/DV-Test-Tool.html", + "https://waterservices.usgs.gov/rest/IV-Test-Tool.html", + "https://waterservices.usgs.gov/rest/GW-Levels-Test-Tool.html", + "https://nwis.waterdata.usgs.gov/nwis/qwdata", + "https://waterdata.usgs.gov/nwis/measurements/", + "https://nwis.waterdata.usgs.gov/usa/nwis/peak/", + "https://waterservices.usgs.gov/rest/Statistics-Service-Test-Tool.html") + +tableData <- data.frame(Service, + Description, + URL, + stringsAsFactors = FALSE) + + +htmlTable(tableData, + caption="Table 5: NWIS general data calls", + rnames=FALSE, align=c("l","l","l"), + col.rgroup = c("none", "#F7F7F7"), + css.cell="padding-bottom: 0.0em; padding-right: 0.5em; padding-top: 0.0em;") + + ## ----dataExample, eval=FALSE------------------------------ # dischargeWI <- readNWISdata(service="dv", # stateCd="WI", @@ -258,10 +353,19 @@ legend("topleft", variableInfo$param_units, # ## ----phData, eval=FALSE----------------------------------- -# # dataPH <- readWQPdata(statecode="US:55", # characteristicName="pH") -# + +## ----eval=FALSE------------------------------------------- +# type <- "Stream" +# sites <- whatWQPdata(countycode="US:55:025",siteType=type) + +## ----eval=FALSE------------------------------------------- +# site <- whatWQPsamples(siteid="USGS-01594440") + +## ----eval=FALSE------------------------------------------- +# type <- "Stream" +# sites <- whatWQPmetrics(countycode="US:55:025",siteType=type) ## ----meta1, eval=FALSE------------------------------------ # @@ -289,10 +393,7 @@ legend("topleft", variableInfo$param_units, # comment(peakData) # # #Which is equivalent to: -# # attr(peakData, "comment") - -## ----helpFunc,eval = FALSE-------------------------------- -# ?readNWISpCode +# attr(peakData, "comment") ## ----seeVignette,eval = FALSE----------------------------- # vignette(dataRetrieval) diff --git a/inst/doc/dataRetrieval.Rmd b/inst/doc/dataRetrieval.Rmd new file mode 100644 index 00000000..9ad527ea --- /dev/null +++ b/inst/doc/dataRetrieval.Rmd @@ -0,0 +1,763 @@ +--- +title: "Introduction to the dataRetrieval package" +date: "`r format(Sys.time(), '%d %B, %Y')`" +author: Laura A. DeCicco and Robert M. Hirsch +output: + rmarkdown::html_vignette: + toc: true + number_sections: true +vignette: > + %\VignetteEngine{knitr::rmarkdown} + %\VignetteIndexEntry{Introduction to the dataRetrieval package} + \usepackage[utf8]{inputenc} +--- + + +```{r setup, include=FALSE, message=FALSE} +library(knitr) +library(dataRetrieval) + +options(continue=" ") +options(width=60) +knitr::opts_chunk$set(echo = TRUE, + warning = FALSE, + message = FALSE, + fig.height = 7, + fig.width = 7) + +opts_chunk$set(highlight=TRUE, + tidy=TRUE, + keep.space=TRUE, + keep.blank.space=FALSE, + keep.comment=TRUE) +knit_hooks$set(inline = function(x) { + if (is.numeric(x)) round(x, 3)}) +``` + +The `dataRetrieval` package was created to simplify the process of loading hydrologic data into the R environment. It is designed to retrieve the major data types of U.S. Geological Survey (USGS) hydrologic data that are available on the Web, as well as data from the Water Quality Portal (WQP), which currently houses water quality data from the Environmental Protection Agency (EPA), U.S. Department of Agriculture (USDA), and USGS. Direct USGS data is obtained from a service called the National Water Information System (NWIS). + +For information on getting started in R and installing the package, see [Getting Started](#getting-started-in-r). Any use of trade, firm, or product names is for descriptive purposes only and does not imply endorsement by the U.S. Government. + +A quick workflow for USGS `dataRetrieval` functions: + +```{r workflow, echo=TRUE,eval=FALSE} +library(dataRetrieval) +# Choptank River near Greensboro, MD +siteNumber <- "01491000" +ChoptankInfo <- readNWISsite(siteNumber) +parameterCd <- "00060" + +#Raw daily data: +rawDailyData <- readNWISdv(siteNumber,parameterCd, + "1980-01-01","2010-01-01") + +# Sample data Nitrate: +parameterCd <- "00618" +qwData <- readNWISqw(siteNumber,parameterCd, + "1980-01-01","2010-01-01") + +pCode <- readNWISpCode(parameterCd) + +``` + +USGS data are made available through the National Water Information System (NWIS). + +Table 1 describes the functions available in the `dataRetrieval` package. + +```{r echo=FALSE} + +library(htmlTable) + +Functions <- c("readNWISdata","", + "readNWISdv","","","","", + "readNWISqw","","","","", + "readNWISuv","","","", + "readNWISrating","", + "readNWISmeas","","", + "readNWISpeak","","", + "readNWISgwl","","", + "readNWISuse","","","", + "readNWISstat","","","","","", + "readNWISpCode", + "readNWISsite", + "whatNWISsites", + "whatNWISdata","", + "readWQPdata", + "readWQPqw","","","", + "whatWQPsites") +Arguments <- c("...","service", #readNWISdata + "siteNumber","parameterCd","startDate","endDate","statCd", #readNWISdv + "siteNumber","parameterCd","startDate","endDate","expanded", #readNWISqw + "siteNumber","parameterCd","startDate","endDate", #readNWISuv + "siteNumber","type", #readNWISrating + "siteNumber","startDate","endDate", #readNWISmeas + "siteNumber","startDate","endDate", #readNWISpeak + "siteNumber","startDate","endDate", #readNWISgwl + "stateCd","countyCd","years","categories", #readNWISuse + "siteNumbers","parameterCd","startDate","endDate","statReportType","statType", #readNWISstat + "parameterCd", #readNWISpCode + "siteNumber", #readNWISsite + "...", #whatNWISsites + "siteNumber","service", #whatNWISdata + "...", #readWQPdata + "siteNumber","parameterCd","startDate","endDate", #readWQPqw + "...") #whatWQPsites +Description <- c("NWIS data using user-specified queries","", #readNWISdata + "NWIS daily data","","","","", #readNWISdv + "NWIS water quality data","","","","", #readNWISqw + "NWIS instantaneous value data","","","", #readNWISuv + "NWIS rating table for active streamgage","", #readNWISrating + "NWIS surface-water measurements","","", #readNWISmeas + "NWIS peak flow data","","", #readNWISpeak + "NWIS groundwater level measurements","","", #readNWISgwl + "NWIS water use","","","", #readNWISuse + "NWIS statistical service","","","","","", #readNWISstat + "NWIS parameter code information", #readNWISpCode + "NWIS site information", #readNWISsite + "NWIS site search using user-specified queries", + "NWIS data availability, including period of record and count","", + "WQP data using user-specified queries", + "WQP data","","","", + "WQP site search using user-specified queries") + +data.df <- data.frame(`Function Name` = Functions, Arguments, Description, stringsAsFactors=FALSE) + +htmlTable(data.df, + caption="Table 1: dataRetrieval functions", + rnames=FALSE, align=c("l","l","l","l"), + col.rgroup = c("none", "#F7F7F7"), + css.cell="padding-bottom: 0.0em; padding-right: 0.5em; padding-top: 0.0em;") + +``` + + +# USGS Web Retrievals + +In this section, examples of National Water Information System (NWIS) retrievals show how to get raw data into R. This data includes [site information](#site-information), measured [parameter information](#parameter-information), historical [daily values](#daily-data), [unit values](#unit-data) (which include real-time data but can also include other sensor data stored at regular time intervals), [water quality data](#water-quality-data), [groundwater level data](#groundwater-level-data), [peak flow data](#peak-flow-data), [rating curve data](#rating-curve-data), and [surface-water measurement data](#surface-water-measurement-data). The section [Embedded Metadata](#embedded-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 `siteNumber`). Often (but not always), these ID's are 8 digits for surface-water sites and 15 digits for groundwater sites. 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](https://maps.waterdata.usgs.gov/mapper/index.html). + +Once the `siteNumber` is known, the next required input for USGS data retrievals is the "parameter code". This is a 5-digit code that specifies the measured parameter being requested. For example, parameter code 00631 represents "Nitrate plus nitrite, water, filtered, milligrams per liter as nitrogen", with units of "mg/l as N". + +Not every station will measure all parameters. A short list of commonly measured parameters is shown in Table 2. + +```{r tableParameterCodes, echo=FALSE} + + +pCode <- c('00060', '00065', '00010','00045','00400') +shortName <- c("Discharge [ft3/s]","Gage height [ft]","Temperature [C]", "Precipitation [in]", "pH") + +data.df <- data.frame(pCode, shortName, stringsAsFactors=FALSE) + +htmlTable(data.df, + caption="Table 2: Common USGS Parameter Codes", + rnames=FALSE, align=c("c","c"), col.rgroup = c("none", "#F7F7F7"), + css.cell="padding-bottom: 0.0em; padding-right: 0.5em; padding-top: 0.0em;") + + +``` + +Two output columns that may not be obvious are "srsname" and "casrn". Srsname stands for "Substance Registry Services". More information on the srs name can be found [here](http://ofmpub.epa.gov/sor_internet/registry/substreg/home/overview/home.do). + +Casrn stands for "Chemical Abstracts Service (CAS) Registry Number". More information on CAS can be found [here](http://www.cas.org/content/chemical-substances/faqs). + +For unit values data (sensor data measured at regular time intervals such as 15 minutes or hourly), knowing the parameter code and `siteNumber` is enough to make a request for data. For most variables that are measured on a continuous basis, the USGS also stores the historical data as daily values. These daily values are statistical summaries of the continuous data, e.g. maximum, minimum, mean, or median. The different statistics are specified by a 5-digit statistics code. + +Some common codes are shown in Table 3. + +```{r tableStatCodes, echo=FALSE} +StatCode <- c('00001', '00002', '00003','00008') +shortName <- c("Maximum","Minimum","Mean", "Median") + +data.df <- data.frame(StatCode, shortName, stringsAsFactors=FALSE) + +htmlTable(data.df, + caption="Table 3: Commonly used USGS Stat Codes", + rnames=FALSE, align=c("c","c"), col.rgroup = c("none", "#F7F7F7"), + css.cell="padding-bottom: 0.0em; padding-right: 0.5em; padding-top: 0.0em;") + + + +``` + +Examples for using these site numbers, parameter codes, and statistic codes will be presented in subsequent sections. + +## Site Information + + +### readNWISsite + +Use the `readNWISsite` function to obtain all of the information available for a particular USGS site (or sites) such as full station name, drainage area, latitude, and longitude. `readNWISsite` can also access information about multiple sites with a vector input. + + +```{r getSite, echo=TRUE, eval=FALSE} +siteNumbers <- c("01491000","01645000") +siteINFO <- readNWISsite(siteNumbers) +``` + +Site information is obtained from: +[https://waterservices.usgs.gov/rest/Site-Test-Tool.html](https://waterservices.usgs.gov/rest/Site-Test-Tool.html) + +Information on the returned data can be found with the `comment` function as described in the [Metadata](#embedded-metadata) section. + +```{r siteNames3, echo=TRUE, eval=FALSE} +comment(siteINFO) +``` + + +### whatNWISdata + +To discover what data is available for a particular USGS site, including measured parameters, period of record, and number of samples (count), use the `whatNWISdata` function. It is possible to limit the retrieval information to a subset of services. The possible choices for services are: "dv" (daily values), "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), and "id" (historical instantaneous values). + +In the following example, we limit the retrieved data to only daily data. The default for "service" is `all`, which returns all of the available data for that site. Likewise, there are arguments for parameter code (`parameterCd`) and statistic code (`statCd`) to filter the results. The default for both is to return all possible values (`all`). The returned `count_nu` for "uv" data is the count of days with returned data, not the actual count of returned values. + + +```{r getSiteExtended, echo=TRUE, eval=FALSE} +# Continuing from the previous example: +# This pulls out just the daily, mean data: + +dailyDataAvailable <- whatNWISdata(siteNumbers, + service="dv", statCd="00003") + + +``` + +```{r echo=FALSE} + +tableData <- data.frame( + siteNumber = c("01491000","01491000","01645000","01491000","01491000","01491000"), + srsname = c("Temperature, water","Stream flow, mean daily", + "Stream flow, mean daily", + "Specific conductance", + "Suspended sediment concentration (SSC)", + "Suspended sediment discharge" ), + startDate = c("2010-10-01","1948-01-01","1930-09-26","2010-10-01","1980-10-01","1980-10-01"), + endDate = c("2012-05-09","2017-05-17","2017-05-17","2012-05-09","1991-09-30","1991-09-30"), + count = c("529","25340","31646","527","4017","4017"), + units = c("deg C","ft3/s","ft3/s","uS/cm @25C","mg/l","tons/day"), + stringsAsFactors = FALSE) + + +htmlTable(tableData, + caption="Table 4: Reformatted version of output from the whatNWISdata function for the Choptank River near Greensboro, MD, and from Seneca Creek at Dawsonville, MD from the daily values service [Some columns deleted for space considerations]", + rnames=FALSE, + col.rgroup = c("none", "#F7F7F7"), + css.cell="padding-bottom: 0.0em; padding-right: 0.5em; padding-top: 0.0em;") + +``` + +See [Creating Tables](#creating-tables-in-microsoft-software-from-r) for instructions on converting an R data frame to a table in Microsoft® software Excel or Word to display a data availability table similar to Table 4. Excel, Microsoft, PowerPoint, Windows, and Word are registered trademarks of Microsoft Corporation in the United States and other countries. + +## Parameter Information + +To obtain all of the available information concerning a measured parameter (or multiple parameters), use the `readNWISpCode` function: + +```{r label=getPCodeInfo, echo=TRUE, eval=FALSE} +# Using defaults: +parameterCd <- "00618" +parameterINFO <- readNWISpCode(parameterCd) +``` + + +## Daily Data + +To obtain daily records of USGS data, use the `readNWISdv` function. The arguments for this function are `siteNumber`, `parameterCd`, `startDate`, `endDate`, and `statCd` (defaults to "00003"). If you want to use the default values, you do not need to list them in the function call. Daily data is pulled from [https://waterservices.usgs.gov/rest/DV-Test-Tool.html](https://waterservices.usgs.gov/rest/DV-Test-Tool.html). + +The dates (start and end) must be in the format "YYYY-MM-DD" (note: the user must include the quotes). Setting the start date to "" (no space) will prompt the program to ask for the earliest date, and setting the end date to "" (no space) will prompt for the latest available date. + +```{r label=getNWISDaily, echo=TRUE, eval=FALSE} + +# Choptank River near Greensboro, MD: +siteNumber <- "01491000" +parameterCd <- "00060" # Discharge +startDate <- "2009-10-01" +endDate <- "2012-09-30" + +discharge <- readNWISdv(siteNumber, + parameterCd, startDate, endDate) +``` + +The column "datetime" in the returned data frame is automatically imported as a variable of class "Date" 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 "A" (approved for publication) or "P" (provisional data subject to revision). + +Another example would be a request for mean and maximum daily temperature and discharge in early 2012: + +```{r label=getNWIStemperature, echo=TRUE, eval=FALSE} +siteNumber <- "01491000" +parameterCd <- c("00010","00060") # Temperature and discharge +statCd <- c("00001","00003") # Mean and maximum +startDate <- "2012-01-01" +endDate <- "2012-05-01" + +temperatureAndFlow <- readNWISdv(siteNumber, parameterCd, + startDate, endDate, statCd=statCd) + +``` + +```{r label=getNWIStemperature2, echo=FALSE, eval=TRUE} +filePath <- system.file("extdata", package="dataRetrieval") +fileName <- "temperatureAndFlow.RData" +fullPath <- file.path(filePath, fileName) +load(fullPath) + +``` + +The column names can be shortened and simplified using the `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 discussed further in the [metadata](#embedded-metadata) section. + + +```{r label=renameColumns, echo=TRUE} +names(temperatureAndFlow) + +temperatureAndFlow <- renameNWISColumns(temperatureAndFlow) +names(temperatureAndFlow) + +``` + +```{r 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: + +```{r} +variableInfo <- attr(temperatureAndFlow, "variableInfo") +siteInfo <- attr(temperatureAndFlow, "siteInfo") + +par(mar=c(5,5,5,5)) #sets the size of the plot window + +plot(temperatureAndFlow$Date, temperatureAndFlow$Wtemp_Max, + ylab=variableInfo$parameter_desc[1],xlab="" ) +par(new=TRUE) +plot(temperatureAndFlow$Date, temperatureAndFlow$Flow, + col="red",type="l",xaxt="n",yaxt="n",xlab="",ylab="",axes=FALSE + ) +axis(4,col="red",col.axis="red") +mtext(variableInfo$parameter_desc[2],side=4,line=3,col="red") +title(paste(siteInfo$station_nm,"2012")) +legend("topleft", variableInfo$param_units, + col=c("black","red"),lty=c(NA,1),pch=c(1,NA)) +``` + + +There are occasions where NWIS values are not reported as numbers, instead there might be text describing a certain event such as "Ice". Any value that cannot be converted to a number will be reported as NA in this package (not including remark code columns). + + +## Unit Data + +Any data collected at regular time intervals (such as 15-minute or hourly) are known as "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 `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. + +```{r label=readNWISuv, eval=FALSE} + +parameterCd <- "00060" # Discharge +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 UTC (Coordinated Universal Time), so midnight EST will be 5 hours earlier in the dateTime column (the previous day, at 7pm). + +To override the UTC timezone, specify a valid timezone in the tz argument. Default is "", which will keep the dateTime column in UTC. Other valid timezones are: + +``` +America/New_York +America/Chicago +America/Denver +America/Los_Angeles +America/Anchorage +America/Honolulu +America/Jamaica +America/Managua +America/Phoenix +America/Metlakatla +``` + +Data are retrieved from [https://waterservices.usgs.gov/rest/IV-Test-Tool.html](https://waterservices.usgs.gov/rest/IV-Test-Tool.html). There are occasions where NWIS values are not reported as numbers, instead a common example is "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 discussed further in [metadata](#embedded-metadata) section. + + +## Water Quality Data + +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 `readNWISqw`, with the input arguments: `siteNumber`, `parameterCd`, `startDate`, and `endDate`. Additionally, the argument `expanded` 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 "reshape", that converts the expanded dataset to a "wide" format (each requested parameter code gets individual columns). The defaults are `expanded=TRUE`, and `reshape=FALSE`. + +```{r label=getQW, echo=TRUE, eval=FALSE} + +# Dissolved Nitrate parameter codes: +parameterCd <- c("00618","71851") +startDate <- "1985-10-01" +endDate <- "2012-09-30" + +dfLong <- readNWISqw(siteNumber, parameterCd, + startDate, endDate) + +# Or the wide return: +dfWide <- readNWISqw(siteNumber, parameterCd, + startDate, endDate, reshape=TRUE) + +``` + +Site information and measured parameter information is attached to the data frame as attributes. This is discussed further in the [metadata](#embedded-metadata) section. Additional metadata, such as information about the column names can be found by using the `comment` function, also described in the [metadata](#embedded-metadata) section. + +```{r qwmeta, echo=TRUE, eval=FALSE} + +comment(dfLong) + +``` + + +## Groundwater Level Data + +Groundwater level measurements can be obtained with the `readNWISgwl` function. Information on the returned data can be found with the `comment` function, and attached attributes as described in the [metadata](#embedded-metadata) section. + +```{r gwlexample, echo=TRUE, eval=FALSE} +siteNumber <- "434400121275801" +groundWater <- readNWISgwl(siteNumber) +``` + + +## Peak Flow Data + +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 `readNWISpeak` function. Information on the returned data can be found with the `comment` function and attached attributes as described in the [metadata](#embedded-metadata) section. + +```{r peakexample, echo=TRUE, eval=FALSE} +siteNumber <- '01594440' +peakData <- readNWISpeak(siteNumber) + +``` + + +## Rating Curve Data + +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 `comment` function and attached attributes as described in the [metadata](#embedded-metadata) section. + +Rating curves can be obtained with the `readNWISrating` function. + +```{r ratingexample, echo=TRUE, eval=FALSE} +ratingData <- readNWISrating(siteNumber, "base") +attr(ratingData, "RATING") + +``` + + +## Surface-Water Measurement Data + +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 `comment` function and attached attributes as described in the [metadata](#embedded-metadata) section. + +Surface-water measurement data can be obtained with the `readNWISmeas` function. + +```{r surfexample, echo=TRUE, eval=FALSE} +surfaceData <- readNWISmeas(siteNumber) + +``` + + +## Water Use Data +Retrieves water use data from USGS Water Use Data for the Nation. See [https://waterdata.usgs.gov/nwis/wu](https://waterdata.usgs.gov/nwis/wu) for more information. All available use categories for the supplied arguments are retrieved. + +```{r eval=FALSE} +allegheny <- readNWISuse(stateCd = "Pennsylvania", + countyCd = "Allegheny") + + +national <- readNWISuse(stateCd = NULL, + countyCd = NULL, + transform = TRUE) + +``` + +## Statistics Data +Retrieves site statistics from the USGS Statistics Web Service beta. + +```{r eval=FALSE} +discharge_stats <- readNWISstat(siteNumbers=c("02319394"), + parameterCd=c("00060"), + statReportType="annual") + +``` + + +# Water Quality Portal Web Retrievals + +There are additional water quality data sets available from the [Water Quality Data Portal](https://www.waterqualitydata.us/). These data sets can be housed in either the STORET database (data from EPA), NWIS database (data from USGS), STEWARDS database (data from USDA), and additional databases are slated to be included in the future. Because only USGS uses parameter codes, a "characteristic name" must be supplied. The `readWQPqw` function can take either a USGS parameter code, or a more general characteristic name in the parameterCd input argument. The Water Quality Data Portal includes data discovery tools and information on characteristic names. The following example retrieves specific conductance from a DNR site in Wisconsin. + + +```{r label=getQWData, echo=TRUE, eval=FALSE} +specificCond <- readWQPqw('WIDNR_WQX-10032762', + 'Specific conductance', + '2011-05-01','2011-09-30') +``` + +A tool for finding NWIS characteristic names can be found [here](https://www.waterqualitydata.us/public_srsnames/) + + +# Generalized Retrievals + +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. + +## NWIS + +### Sites: whatNWISsites + +The function `whatNWISsites` can be used to discover NWIS sites based on any query that the NWIS Site Service offers. This is done by using the `...` argument, which allows the user to use any arbitrary input argument. We can then use the service [here](https://waterservices.usgs.gov/rest/Site-Test-Tool.html) to discover many options for searching for NWIS sites. For example, you may want to search for sites in a lat/lon bounding box, or only sites tidal streams, or sites with water quality samples, sites above a certain altitude, etc. The results of this site query generate a URL. For example, the tool provided a search within a specified bounding box, for sites that have daily discharge (parameter code = 00060) and temperature (parameter code = 00010). The generated URL is: + +[https://waterservices.usgs.gov/nwis/site/?format=rdb&bBox=-83.0,36.5,-81.0,38.5¶meterCd=00010,00060&hasDataTypeCd=dv](https://waterservices.usgs.gov/nwis/site/?format=rdb&bBox=-83.0,36.5,-81.0,38.5¶meterCd=00010,00060&hasDataTypeCd=dv) + +The following `dataRetrieval` code can be used to get those sites: + +```{r siteSearch, eval=FALSE} +sites <- whatNWISsites(bBox=c(-83.0,36.5,-81.0,38.5), + parameterCd=c("00010","00060"), + hasDataTypeCd="dv") +``` + +### Data: readNWISdata + +For NWIS data, the function `readNWISdata` can be used. The argument listed in the R help file is `...` and `service` (only for data requests). Table 5 describes the services are available. + +```{r echo=FALSE} + +Service <- c("dv","iv","gwlevels","qwdata","measurements","peak","stat") +Description <- c("Daily","Instantaneous","Groundwater Levels","Water Quality","Surface Water Measurements","Peak Flow","Statistics Service") +URL <- c("https://waterservices.usgs.gov/rest/DV-Test-Tool.html", + "https://waterservices.usgs.gov/rest/IV-Test-Tool.html", + "https://waterservices.usgs.gov/rest/GW-Levels-Test-Tool.html", + "https://nwis.waterdata.usgs.gov/nwis/qwdata", + "https://waterdata.usgs.gov/nwis/measurements/", + "https://nwis.waterdata.usgs.gov/usa/nwis/peak/", + "https://waterservices.usgs.gov/rest/Statistics-Service-Test-Tool.html") + +tableData <- data.frame(Service, + Description, + URL, + stringsAsFactors = FALSE) + + +htmlTable(tableData, + caption="Table 5: NWIS general data calls", + rnames=FALSE, align=c("l","l","l"), + col.rgroup = c("none", "#F7F7F7"), + css.cell="padding-bottom: 0.0em; padding-right: 0.5em; padding-top: 0.0em;") + +``` + + +The `...` argument allows the user to create their own queries based on the instructions found in the web links above. The links provide instructions on how to create a URL to request data. Perhaps you want sites only in Wisconsin, with a drainage area less than 50 mi2, and the most recent daily discharge data. That request would be done as follows: + +```{r dataExample, eval=FALSE} +dischargeWI <- readNWISdata(service="dv", + stateCd="WI", + parameterCd="00060", + drainAreaMin="50", + statCd="00003") + +siteInfo <- attr(dischargeWI, "siteInfo") + +``` + + +## WQP + +Just as with NWIS, the Water Quality Portal (WQP) offers a variety of ways to search for sites and request data. The possible Web service arguments for WQP site searches is found [here](https://www.waterqualitydata.us/webservices_documentation). + +### Sites: whatWQPsites + +To discover available sites in the WQP in New Jersey that have measured Chloride, use the function `whatWQPsites`. + +```{r NJChloride, eval=FALSE} + +sitesNJ <- whatWQPsites(statecode="US:34", + characteristicName="Chloride") + +``` + + +### Data: readWQPdata + +To get data from the WQP using generalized Web service calls, use the function `readWQPdata`. For example, to get all the pH data in Wisconsin: + +```{r phData, eval=FALSE} +dataPH <- readWQPdata(statecode="US:55", + characteristicName="pH") +``` + + +### Availability: whatWQPdata + +The function `whatWQPdata` returns a data frame with information on the amount of data collected at a site. For example: + +```{r eval=FALSE} +type <- "Stream" +sites <- whatWQPdata(countycode="US:55:025",siteType=type) +``` + +This returns a data frame with all of the sites that were measured in streams in Dane County, WI. Also, in that table, there is a measure of `activityCount` (how often the site was sampled), and `resultCount` (how many individual results are available). + +### Samples: whatWQPsamples + +The function `whatWQPsamples` returns information on the individual samples collected at a site. For example: + +```{r eval=FALSE} +site <- whatWQPsamples(siteid="USGS-01594440") +``` + +This returns one row for each instance that a sample was collect. + +### Metrics: whatWQPmetrics + +The function `whatWQPmetrics` provides metric information. This is only currently available for STORET data: + +```{r eval=FALSE} +type <- "Stream" +sites <- whatWQPmetrics(countycode="US:55:025",siteType=type) +``` + + +# Embedded Metadata + +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 `url` (returning a character of the url used to obtain the data), `siteInfo` (returning a data frame with information on sites), and `queryTime` (returning a POSIXct datetime) attributes. For example, the url and query time used to obtain the data can be found as follows: + +```{r meta1, eval=FALSE} + +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 data frame as attributes. To discover the available attributes: + +```{r meta2, eval=FALSE} + +names(attributes(dischargeWI)) + +``` + +For data obtained from `readNWISuv`, `readNWISdv`, `readNWISgwl` there are two attributes that are particularly useful: `siteInfo` and `variableInfo`. + +```{r meta3, eval=FALSE} + +siteInfo <- attr(dischargeWI, "siteInfo") + +variableInfo <- attr(dischargeWI, "variableInfo") + + +``` + +Data obtained from `readNWISpeak`, `readNWISmeas`, and `readNWISrating`, the `comment` attribute is useful. + +```{r meta5, eval=FALSE} +comment(peakData) + +#Which is equivalent to: +attr(peakData, "comment") +``` + + +# Getting Started in R + +This section describes the options for downloading and installing the `dataRetrieval` package. + +## New to R? + +If you are new to R, you will need to first install the latest version of R, which can be found [here] (www.R-project.org). + +At any time, you can get information about any function in R by typing a question mark before the functions name. This will open a file (in RStudio, in the Help window) that describes the function, the required arguments, and provides working examples. This will open a help file similar to the image below. To see the raw code for a particular code, type the name of the function, without parentheses. + + +``` +?readNWISpCode +``` + + +![A simple R help file](Rhelp.png) + + +Additionally, many R packages have vignette files attached (such as this paper). To view the vignette: +```{r seeVignette,eval = FALSE} +vignette(dataRetrieval) +``` + + +## R User: Installing dataRetrieval + +The following command installs `dataRetrieval` and subsequent required packages: + +```{r installFromCran,eval = FALSE} +install.packages("dataRetrieval") +``` + +After installing the package, you need to open the library each time you re-start R. This is done with the simple command: + +```{r openLibraryTest, eval=FALSE} +library(dataRetrieval) +``` + + + +# Creating Tables in Microsoft® Software from R + +There are a few steps that are required in order to create a table in Microsoft® 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: + +```{r label=getSiteApp, echo=TRUE, eval=FALSE} +availableData <- whatNWISdata(siteNumber, "dv") +dailyData <- availableData["00003" == availableData$stat_cd,] + +tableData <- with(dailyData, + data.frame( + shortName=srsname, + Start=begin_date, + End=end_date, + Count=count_nu, + Units=parameter_units) + ) +``` + +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): + + +```{r label=saveData, echo=TRUE, eval=FALSE} +write.table(tableData, file="tableData.tsv",sep="\t", + row.names = FALSE,quote=FALSE) +``` + +This will save a file in your working directory called tableData.tsv. You can see your working directory by typing `getwd()` in the R console. Opening the file in a general-purpose text editor, you should see the following: + +``` +shortName Start End Count Units +Temperature, water 2010-10-01 2012-06-24 575 deg C +Stream flow, mean. daily 1948-01-01 2013-03-13 23814 ft3/s +Specific conductance 2010-10-01 2012-06-24 551 uS/cm 25C +Suspended sediment concentration (SSC) 1980-10-01 1991-09-30 3651 mg/l +Suspended sediment discharge 1980-10-01 1991-09-30 3652 tons/day +``` + +Next, follow the steps below to open this file in Excel: + +1. Open Excel +2. Click on the File tab +3. Click on the Open option +4. Navigate to the working directory (as shown in the results of `getwd()`) +5. Next to the File name text box, change the drop down type to All Files (*.*) +6. Double click tableData.tsv +7. A text import wizard will open up, in the first window, choose the Delimited radio button if it is not automatically picked, then click on Next. +8. In the second window, click on the Tab delimiter if it is not automatically checked, then click Finished. +9. Use the many formatting tools within Excel to customize the table + +From Excel, it is simple to copy and paste the tables in other Microsoft® software. An example using one of the default Excel table formats is here. Additional formatting could be required in Excel, for example converting u to $\mu$. + +![A simple table produced in Microsoft ® Excel.](table1.png) + + +# Disclaimer +This information is preliminary and is subject to revision. It is being provided to meet the need for timely best science. The information is provided on the condition that neither the U.S. Geological Survey nor the U.S. Government may be held liable for any damages resulting from the authorized or unauthorized use of the information. + + diff --git a/inst/doc/dataRetrieval.Rnw b/inst/doc/dataRetrieval.Rnw deleted file mode 100644 index 16dfa930..00000000 --- a/inst/doc/dataRetrieval.Rnw +++ /dev/null @@ -1,960 +0,0 @@ -%\VignetteIndexEntry{Introduction to the dataRetrieval package} -%\VignetteEngine{knitr::knitr} -%\VignetteDepends{} -%\VignetteSuggests{xtable, testthat} -%\VignetteImports{XML, httr, reshape2,lubridate,utils,stats} -%\VignettePackage{dataRetrieval} - -\documentclass[a4paper,11pt]{article} - -\usepackage{amsmath} -\usepackage{times} -\usepackage{hyperref} -\usepackage[numbers, round]{natbib} -\usepackage[american]{babel} -\usepackage{authblk} -\usepackage{subfig} -\usepackage{placeins} -\usepackage{footnote} -\usepackage{tabularx} -\usepackage{threeparttable} -\usepackage{parskip} - -\usepackage{csquotes} -\usepackage{setspace} - -% \doublespacing - -\renewcommand{\topfraction}{0.85} -\renewcommand{\textfraction}{0.1} -\usepackage{graphicx} - - -\usepackage{mathptmx}% Times Roman font -\usepackage[scaled=.90]{helvet}% Helvetica, served as a model for arial - -% \usepackage{indentfirst} -% \setlength\parindent{20pt} -\setlength{\parskip}{0pt} - -\usepackage{courier} - -\usepackage{titlesec} -\usepackage{titletoc} - -\titleformat{\section} - {\normalfont\sffamily\bfseries\LARGE} - {\thesection}{0.5em}{} -\titleformat{\subsection} - {\normalfont\sffamily\bfseries\Large} - {\thesubsection}{0.5em}{} -\titleformat{\subsubsection} - {\normalfont\sffamily\large} - {\thesubsubsection}{0.5em}{} - -\titlecontents{section} -[2em] % adjust left margin -{\sffamily} % font formatting -{\contentslabel{2.3em}} % section label and offset -{\hspace*{-2.3em}} -{\titlerule*[0.25pc]{.}\contentspage} - -\titlecontents{subsection} -[4.6em] % adjust left margin -{\sffamily} % font formatting -{\contentslabel{2.3em}} % section label and offset -{\hspace*{-2.3em}} -{\titlerule*[0.25pc]{.}\contentspage} - -\titlecontents{subsubsection} -[6.9em] % adjust left margin -{\sffamily} % font formatting -{\contentslabel{2.3em}} % section label and offset -{\hspace*{-2.3em}} -{\titlerule*[0.25pc]{.}\contentspage} - -\titlecontents{table} -[0em] % adjust left margin -{\sffamily} % font formatting -{Table\hspace*{2em} \contentslabel {2em}} % section label and offset -{\hspace*{4em}} -{\titlerule*[0.25pc]{.}\contentspage} - -\titlecontents{figure} -[0em] % adjust left margin -{\sffamily} % font formatting -{Figure\hspace*{2em} \contentslabel {2em}} % section label and offset -{\hspace*{4em}} -{\titlerule*[0.25pc]{.}\contentspage} - -%Italisize and change font of urls: -\urlstyle{sf} -\renewcommand\UrlFont\itshape - -\usepackage{caption} -\captionsetup{ - font={sf}, - labelfont={bf,sf}, - labelsep=period, - justification=justified, - singlelinecheck=false -} - - - -\textwidth=6.2in -\textheight=8.5in -\parskip=.3cm -\oddsidemargin=.1in -\evensidemargin=.1in -\headheight=-.3in - - -%------------------------------------------------------------ -% newcommand -%------------------------------------------------------------ -\newcommand{\scscst}{\scriptscriptstyle} -\newcommand{\scst}{\scriptstyle} -\newcommand{\Robject}[1]{{\texttt{#1}}} -\newcommand{\Rfunction}[1]{{\texttt{#1}}} -\newcommand{\Rclass}[1]{\textit{#1}} -\newcommand{\Rpackage}[1]{\textit{#1}} -\newcommand{\Rexpression}[1]{\texttt{#1}} -\newcommand{\Rmethod}[1]{{\texttt{#1}}} -\newcommand{\Rfunarg}[1]{{\texttt{#1}}} - -\begin{document} - -<>= -library(xtable) -options(continue=" ") -options(width=60) -library(knitr) - -@ - -\renewenvironment{knitrout}{\begin{singlespace}}{\end{singlespace}} -\renewcommand*\listfigurename{Figures} - -\renewcommand*\listtablename{Tables} - - -%------------------------------------------------------------ -\title{The dataRetrieval R package} -%------------------------------------------------------------ -\author[1]{Laura A. De Cicco} -\author[1]{Robert M. Hirsch} -\affil[1]{United States Geological Survey} - - -<>= -opts_chunk$set(highlight=TRUE, tidy=TRUE, keep.space=TRUE, keep.blank.space=FALSE, keep.comment=TRUE, tidy=FALSE,comment="") -knit_hooks$set(inline = function(x) { - if (is.numeric(x)) round(x, 3)}) -knit_hooks$set(crop = hook_pdfcrop) - -bold.colHeaders <- function(x) { - x <- gsub("\\^(\\d)","$\\^\\1$",x) - x <- gsub("\\%","\\\\%",x) - x <- gsub("\\_"," ",x) - returnX <- paste("\\multicolumn{1}{c}{\\textbf{\\textsf{", x, "}}}", sep = "") -} -addSpace <- function(x) ifelse(x != "1", "[5pt]","") -library(dataRetrieval) -@ - -\noindent{\huge\textsf{\textbf{The dataRetrieval R package}}} - -\noindent\textsf{By Laura A. De Cicco and Robert M. Hirsch} - -\noindent\textsf{\today} - -% \maketitle -% -% \newpage - -\tableofcontents -\listoffigures -\listoftables - -\newpage - -%------------------------------------------------------------ -\section{Introduction to dataRetrieval} -%------------------------------------------------------------ -The dataRetrieval package was created to simplify the process of loading hydrologic data into the R environment. It is designed to retrieve the major data types of U.S. Geological Survey (USGS) hydrologic data that are available on the Web, as well as data from the Water Quality Portal (WQP), which currently houses water quality data from the Environmental Protection Agency (EPA), U.S. Department of Agriculture (USDA), and USGS. Direct USGS data is obtained from a service called the National Water Information System (NWIS). - -For information on getting started in R and installing the package, see (\ref{sec:appendix1}): Getting Started. Any use of trade, firm, or product names is for descriptive purposes only and does not imply endorsement by the U.S. Government. - -A quick workflow for USGS dataRetrieval functions: - -<>= -library(dataRetrieval) -# Choptank River near Greensboro, MD -siteNumber <- "01491000" -ChoptankInfo <- readNWISsite(siteNumber) -parameterCd <- "00060" - -#Raw daily data: -rawDailyData <- readNWISdv(siteNumber,parameterCd, - "1980-01-01","2010-01-01") - -# Sample data Nitrate: -parameterCd <- "00618" -qwData <- readNWISqw(siteNumber,parameterCd, - "1980-01-01","2010-01-01") - -pCode <- readNWISpCode(parameterCd) - -@ - -USGS data are made available through the National Water Information System (NWIS). - -Table \ref{tab:func} describes the functions available in the dataRetrieval package. - -\begin{table}[!ht] -\begin{minipage}{\linewidth} -{\footnotesize -\caption{dataRetrieval functions} -\label{tab:func} -\begin{tabular}{lll} - \hline -\multicolumn{1}{c}{\textbf{\textsf{Function Name}}} & -\multicolumn{1}{c}{\textbf{\textsf{Arguments}}} & -\multicolumn{1}{c}{\textbf{\textsf{Description}}} \\ [0pt] - \hline - \texttt{readNWISdata} & \texttt{...} & NWIS data using user-specified queries\\ - & service & \\ - [5pt]\texttt{readNWISdv} & siteNumber & NWIS daily data\\ - & parameterCd & \\ - & startDate & \\ - & endDate & \\ - & statCd & \\ - [5pt]\texttt{readNWISqw} & siteNumber & NWIS water quality data\\ - & parameterCd & \\ - & startDate & \\ - & endDate & \\ - & expanded & \\ - [5pt]\texttt{readNWISuv} & siteNumber & NWIS instantaneous value data\\ - & parameterCd & \\ - & startDate & \\ - & endDate & \\ - [5pt]\texttt{readNWISrating} & siteNumber & NWIS rating table for active streamgage \\ - & type & \\ - [5pt]\texttt{readNWISmeas} & siteNumber & NWIS surface-water measurements \\ - & startDate & \\ - & endDate & \\ - [5pt]\texttt{readNWISpeak} & siteNumber & NWIS peak flow data \\ - & startDate & \\ - & endDate & \\ - [5pt]\texttt{readNWISgwl} & siteNumber & NWIS groundwater level measurements \\ - & startDate & \\ - & endDate & \\ - [5pt]\texttt{readNWISpCode} & parameterCd & NWIS parameter code information\\ - [5pt]\texttt{readNWISsite} & siteNumber & NWIS site information \\ - [5pt]\texttt{whatNWISsites} & \texttt{...} & NWIS site search using user-specified queries \\ - [5pt]\texttt{whatNWISdata} & siteNumber & NWIS data availability, including period of record and count \\ - & service & \\ - [5pt]\texttt{readWQPdata} & \texttt{...} & WQP data using user-specified queries \\ - [5pt]\texttt{readWQPqw} & siteNumber & WQP data \\ - & parameterCd (or characteristic name) & \\ - & startDate & \\ - & endDate & \\ - [5pt]\texttt{whatWQPsites} & \texttt{...} & WQP site search using user-specified queries \\ - \hline -\end{tabular} -} -\end{minipage} -\end{table} - -\clearpage - -%------------------------------------------------------------ -\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 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 for surface-water sites and 15 digits for groundwater sites. 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{https://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}. - -Not every station will measure all parameters. A short list of commonly measured parameters is shown in Table \ref{tab:params}. - -<>= -pCode <- c('00060', '00065', '00010','00045','00400') -shortName <- c("Discharge [ft$^3$/s]","Gage height [ft]","Temperature [C]", "Precipitation [in]", "pH") - -data.df <- data.frame(pCode, shortName, stringsAsFactors=FALSE) - -print(xtable(data.df, - label="tab:params", - caption="Common USGS Parameter Codes"), - caption.placement="top", - size = "\\footnotesize", - latex.environment=NULL, - sanitize.text.function = function(x) {x}, - sanitize.colnames.function = bold.colHeaders, - sanitize.rownames.function = addSpace - ) - -@ - -Two output columns that may not be obvious are \enquote{srsname} and \enquote{casrn}. Srsname stands for \enquote{Substance Registry Services}. More information on the srs name can be found here: - -\url{http://ofmpub.epa.gov/sor_internet/registry/substreg/home/overview/home.do} - -Casrn stands for \enquote{Chemical Abstracts Service (CAS) Registry Number}. More information on CAS can be found here: - -\url{http://www.cas.org/content/chemical-substances/faqs} - -For unit values data (sensor data measured at regular time intervals such as 15 minutes or hourly), knowing the parameter code and siteNumber is enough to make a request for data. For most variables that are measured on a continuous basis, the USGS also stores the historical data as daily values. These daily values are statistical summaries of the continuous data, e.g. maximum, minimum, mean, or median. The different statistics are specified by a 5-digit statistics code. - -Some common codes are shown in Table \ref{tab:stat}. - -<>= -StatCode <- c('00001', '00002', '00003','00008') -shortName <- c("Maximum","Minimum","Mean", "Median") - -data.df <- data.frame(StatCode, shortName, stringsAsFactors=FALSE) - -print(xtable(data.df,label="tab:stat", - caption="Commonly used USGS Stat Codes"), - caption.placement="top", - size = "\\footnotesize", - latex.environment=NULL, - sanitize.colnames.function = bold.colHeaders, - sanitize.rownames.function = addSpace - ) - -@ - -Examples for using these siteNumbers, parameter codes, and stat codes will be presented in subsequent sections. - -\FloatBarrier - -%------------------------------------------------------------ -\subsection{Site Information} -\label{sec:usgsSite} -%------------------------------------------------------------ - -%------------------------------------------------------------ -\subsubsection{readNWISsite} -\label{sec:usgsSiteFileData} -%------------------------------------------------------------ -Use the \texttt{readNWISsite} function to obtain all of the information available for a particular USGS site (or sites) such as full station name, drainage area, latitude, and longitude. \texttt{readNWISsite} can also access information about multiple sites with a vector input. - - -<>= -siteNumbers <- c("01491000","01645000") -siteINFO <- readNWISsite(siteNumbers) -@ - -Site information is obtained from: -\url{https://waterservices.usgs.gov/rest/Site-Test-Tool.html} - -Information on the returned data can be found with the \texttt{comment} function as described in section \ref{sec:metadata}. - -<>= -comment(siteINFO) -@ - - - -\FloatBarrier - -%------------------------------------------------------------ -\subsubsection{whatNWISdata} -\label{sec:usgsDataAvailability} -%------------------------------------------------------------ -To discover what data is available for a particular USGS site, including measured parameters, period of record, and number of samples (count), use the \texttt{whatNWISdata} function. It is possible to limit the retrieval information to a subset of services. The possible choices for services are: \texttt{"}dv\texttt{"} (daily values), \texttt{"}uv\texttt{"}, \texttt{"}rt\texttt{"}, or \texttt{"}iv\texttt{"} (unit values), \texttt{"}qw\texttt{"} (water-quality), \texttt{"}sv\texttt{"} (sites visits), \texttt{"}pk\texttt{"} (peak measurements), \texttt{"}gw\texttt{"} (groundwater levels), \texttt{"}ad\texttt{"} (sites included in USGS Annual Water Data Reports External Link), \texttt{"}aw\texttt{"} (sites monitored by the USGS Active Groundwater Level Network External Link), and \texttt{"}id\texttt{"} (historical instantaneous values). - -In the following example, we limit the retrieved data to only daily data. The default for \texttt{"}service\texttt{"} is \enquote{all}, which returns all of the available data for that site. Likewise, there are arguments for parameter code (\texttt{parameterCd}) and statistic code (\texttt{statCd}) to filter the results. The default for both is to return all possible values (\enquote{all}). The returned \texttt{"}count\_nu\texttt{"} for \texttt{"}uv\texttt{"} data is the count of days with returned data, not the actual count of returned values. - - -<>= -# Continuing from the previous example: -# This pulls out just the daily, mean data: - -dailyDataAvailable <- whatNWISdata(siteNumbers, - service="dv", statCd="00003") - - -@ - -<>= -tableData <- with(dailyDataAvailable, - data.frame( - siteNumber= site_no, - srsname=srsname, - startDate=as.character(begin_date), - endDate=as.character(end_date), - count=as.character(count_nu), - units=parameter_units, -# statCd = stat_cd, - stringsAsFactors=FALSE) - ) - -tableData$units[which(tableData$units == "ft3/s")] <- "ft$^3$/s" -tableData$units[which(tableData$units == "uS/cm @25C")] <- "$\\mu$S/cm @25C" - - -print(xtable(tableData,label="tab:gda", - caption="Reformatted version of output from \\texttt{whatNWISdata} function for the Choptank River near Greensboro, MD, and from Seneca Creek at Dawsonville, MD from the daily values service [Some columns deleted for space considerations]"), - caption.placement="top", - size = "\\footnotesize", - latex.environment=NULL, - sanitize.text.function = function(x) {x}, - sanitize.colnames.function = bold.colHeaders, - sanitize.rownames.function = addSpace - ) - -@ - -\begin{table}[ht] -\caption{Reformatted version of output from \texttt{whatNWISdata} function for the Choptank River near Greensboro, MD, and from Seneca Creek at Dawsonville, MD from the daily values service [Some columns deleted for space considerations]} -\label{tab:gda} -{\footnotesize -\begin{tabular}{rllllll} - \hline - & \multicolumn{1}{c}{\textbf{\textsf{siteNumber}}} & \multicolumn{1}{c}{\textbf{\textsf{srsname}}} & \multicolumn{1}{c}{\textbf{\textsf{startDate}}} & \multicolumn{1}{c}{\textbf{\textsf{endDate}}} & \multicolumn{1}{c}{\textbf{\textsf{count}}} & \multicolumn{1}{c}{\textbf{\textsf{units}}} \\ - \hline - & 01491000 & Temperature, water & 2010-10-01 & 2012-05-09 & 529 & deg C \\ - [5pt] & 01645000 & Stream flow, mean. daily & 1930-09-26 & 2015-02-19 & 30828 & ft$^3$/s \\ - [5pt] & 01491000 & Stream flow, mean. daily & 1948-01-01 & 2015-02-19 & 24522 & ft$^3$/s \\ - [5pt] & 01491000 & Specific conductance & 2010-10-01 & 2012-05-09 & 527 & $\mu$S/cm @25C \\ - [5pt] & 01491000 & Suspended sediment concentration (SSC) & 1980-10-01 & 1991-09-30 & 3651 & mg/l \\ - [5pt] & 01491000 & Suspended sediment discharge & 1980-10-01 & 1991-09-30 & 3652 & tons/day \\ - \hline -\end{tabular} -} -\end{table} - -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 - -%------------------------------------------------------------ -\subsection{Parameter Information} -\label{sec:usgsParams} -%------------------------------------------------------------ -To obtain all of the available information concerning a measured parameter (or multiple parameters), use the \texttt{readNWISpCode} function: - -<>= -# Using defaults: -parameterCd <- "00618" -parameterINFO <- readNWISpCode(parameterCd) -@ - - -\FloatBarrier - -%------------------------------------------------------------ -\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. Daily data is pulled from \url{https://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. - -<>= - -# Choptank River near Greensboro, MD: -siteNumber <- "01491000" -parameterCd <- "00060" # Discharge -startDate <- "2009-10-01" -endDate <- "2012-09-30" - -discharge <- readNWISdv(siteNumber, - parameterCd, startDate, endDate) -@ - -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). - -Another example would be a request for mean and maximum daily temperature and discharge in early 2012: - -<>= -siteNumber <- "01491000" -parameterCd <- c("00010","00060") # Temperature and discharge -statCd <- c("00001","00003") # Mean and maximum -startDate <- "2012-01-01" -endDate <- "2012-05-01" - -temperatureAndFlow <- readNWISdv(siteNumber, parameterCd, - startDate, endDate, statCd=statCd) - -@ - -<>= -filePath <- system.file("extdata", package="dataRetrieval") -fileName <- "temperatureAndFlow.RData" -fullPath <- file.path(filePath, fileName) -load(fullPath) - -@ - -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}. - - -<>= -names(temperatureAndFlow) - -temperatureAndFlow <- renameNWISColumns(temperatureAndFlow) -names(temperatureAndFlow) - -@ - -<>= -#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}): - -<>= -variableInfo <- attr(temperatureAndFlow, "variableInfo") -siteInfo <- attr(temperatureAndFlow, "siteInfo") - -par(mar=c(5,5,5,5)) #sets the size of the plot window - -plot(temperatureAndFlow$Date, temperatureAndFlow$Wtemp_Max, - ylab=variableInfo$parameter_desc[1],xlab="" ) -par(new=TRUE) -plot(temperatureAndFlow$Date, temperatureAndFlow$Flow, - col="red",type="l",xaxt="n",yaxt="n",xlab="",ylab="",axes=FALSE - ) -axis(4,col="red",col.axis="red") -mtext(variableInfo$parameter_desc[2],side=4,line=3,col="red") -title(paste(siteInfo$station_nm,"2012")) -legend("topleft", variableInfo$param_units, - col=c("black","red"),lty=c(NA,1),pch=c(1,NA)) -@ - - -There are occasions where NWIS values are not reported as numbers, instead there might be text describing a certain event such as \enquote{Ice.} Any value that cannot be converted to a number will be reported as NA in this package (not including remark code columns). - -\FloatBarrier - -%------------------------------------------------------------ -\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. - -<>= - -parameterCd <- "00060" # Discharge -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). - -To override the UTC timezone, specify a valid timezone in the tz argument. Default is \texttt{""}, which will keep the dateTime column in UTC. Other valid timezones are: - -\begin{verbatim} -America/New_York -America/Chicago -America/Denver -America/Los_Angeles -America/Anchorage -America/Honolulu -America/Jamaica -America/Managua -America/Phoenix -America/Metlakatla -\end{verbatim} - -Data are retrieved from \url{https://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 - - -\FloatBarrier - -%------------------------------------------------------------ -\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). The defaults are expanded=TRUE, and reshape=FALSE. - -<>= - -# Dissolved Nitrate parameter codes: -parameterCd <- c("00618","71851") -startDate <- "1985-10-01" -endDate <- "2012-09-30" - -dfLong <- readNWISqw(siteNumber, parameterCd, - startDate, endDate) - -# Or the wide return: -# dfWide <- readNWISqw(siteNumber, parameterCd, -# startDate, endDate, reshape=TRUE) - -@ - -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}. - -<>= - -comment(dfLong) - -@ - -\FloatBarrier - -%------------------------------------------------------------ -\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, and attached attributes as described in section \ref{sec:metadata}. - -<>= -siteNumber <- "434400121275801" -groundWater <- readNWISgwl(siteNumber) -@ - -%------------------------------------------------------------ -\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 and attached attributes as described in section \ref{sec:metadata}. - -<>= -siteNumber <- '01594440' -peakData <- readNWISpeak(siteNumber) - -@ - - -%------------------------------------------------------------ -\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 and attached attributes as described in section \ref{sec:metadata}. - -Rating curves can be obtained with the \texttt{readNWISrating} function. - -<>= -ratingData <- readNWISrating(siteNumber, "base") -attr(ratingData, "RATING") - -@ - - - -%------------------------------------------------------------ -\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 and attached attributes as described in section \ref{sec:metadata}. - -Surface-water measurement data can be obtained with the \texttt{readNWISmeas} function. - -<>= -surfaceData <- readNWISmeas(siteNumber) - -@ - - -%------------------------------------------------------------ -\section{Water Quality Portal Web Retrievals} -\label{sec:usgsSTORET} -%------------------------------------------------------------ -There are additional water quality data sets available from the Water Quality Data Portal (\url{https://www.waterqualitydata.us/}). These data sets can be housed in either the STORET database (data from EPA), NWIS database (data from USGS), STEWARDS database (data from USDA), and additional databases are slated to be included in the future. Because only USGS uses parameter codes, a \texttt{"}characteristic name\texttt{"} must be supplied. The \texttt{readWQPqw} function can take either a USGS parameter code, or a more general characteristic name in the parameterCd input argument. The Water Quality Data Portal includes data discovery tools and information on characteristic names. The following example retrieves specific conductance from a DNR site in Wisconsin. - - -<>= -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{https://www.waterqualitydata.us/public_srsnames/} - -\FloatBarrier - -%------------------------------------------------------------ -\section{Generalized Retrievals} -\label{sec:general} -%------------------------------------------------------------ -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} -\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: - -\url{https://waterservices.usgs.gov/rest/Site-Test-Tool.html} - -to discover many options for searching for NWIS sites. For example, you may want to search for sites in a lat/lon bounding box, or only sites tidal streams, or sites with water quality samples, sites above a certain altitude, etc. The results of this site query generate a URL. For example, the tool provided a search within a specified bounding box, for sites that have daily discharge (parameter code = 00060) and temperature (parameter code = 00010). The generated URL is: - -\url{https://waterservices.usgs.gov/nwis/site/?format=rdb&bBox=-83.0,36.5,-81.0,38.5¶meterCd=00010,00060&hasDataTypeCd=dv} - -The following dataRetrieval code can be used to get those sites: - -<>= -sites <- whatNWISsites(bBox=c(-83.0,36.5,-81.0,38.5), - parameterCd=c("00010","00060"), - hasDataTypeCd="dv") -@ - - -%------------------------------------------------------------ -\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. - -\begin{table}[!ht] -\begin{minipage}{\linewidth} -{\footnotesize -\caption{NWIS general data calls} -\label{tab:NWISGeneral} -\begin{tabular}{lll} - \hline -\multicolumn{1}{c}{\textbf{\textsf{Service}}} & -\multicolumn{1}{c}{\textbf{\textsf{Description}}} & -\multicolumn{1}{c}{\textbf{\textsf{Reference URL}}} \\ [0pt] - \hline - daily values & dv & \url{https://waterservices.usgs.gov/rest/DV-Test-Tool.html}\\ - [5pt]instantaneous & iv & \url{https://waterservices.usgs.gov/rest/IV-Test-Tool.html}\\ - [5pt]groundwater levels & gwlevels & \url{https://waterservices.usgs.gov/rest/GW-Levels-Test-Tool.html}\\ - [5pt]water quality & qwdata & \url{https://nwis.waterdata.usgs.gov/nwis/qwdata}\\ - \hline -\end{tabular} -} -\end{minipage} -\end{table} - -The \texttt{"..."} argument allows the user to create their own queries based on the instructions found in the web links above. The links provide instructions on how to create a URL to request data. Perhaps you want sites only in Wisconsin, with a drainage area less than 50 mi$^2$, and the most recent daily dischage data. That request would be done as follows: - -<>= -dischargeWI <- readNWISdata(service="dv", - stateCd="WI", - parameterCd="00060", - drainAreaMin="50", - statCd="00003") - -siteInfo <- attr(dischargeWI, "siteInfo") - -@ - -%------------------------------------------------------------ -\subsubsection{WQP Sites} -\label{sec:WQPGenSite} -%------------------------------------------------------------ - -Just as with NWIS, the Water Quality Portal (WQP) offers a variety of ways to search for sites and request data. The possible Web service arguments for WQP site searches is found here: - -\url{https://www.waterqualitydata.us/webservices_documentation} - -To discover available sites in the WQP in New Jersey that have measured Chloride, use the function \texttt{whatWQPsites}. - -<>= - -sitesNJ <- whatWQPsites(statecode="US:34", - characteristicName="Chloride") - -@ - - -%------------------------------------------------------------ -\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: - -<>= - -dataPH <- readWQPdata(statecode="US:55", - characteristicName="pH") - -@ - - - -\FloatBarrier - -\clearpage - -%------------------------------------------------------------ -\section{Embedded Metadata} -\label{sec:metadata} -%------------------------------------------------------------ -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: - -<>= - -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 data frame as attributes. To discover the available attributes: - -<>= - -names(attributes(dischargeWI)) - -@ - -For data obtained from \texttt{readNWISuv}, \texttt{readNWISdv}, \texttt{readNWISgwl} there are two attributes that are particularly useful: \texttt{siteInfo} and \texttt{variableInfo}. - -<>= - -siteInfo <- attr(dischargeWI, "siteInfo") - -variableInfo <- attr(dischargeWI, "variableInfo") - - -@ - -Data obtained from \texttt{readNWISpeak}, \texttt{readNWISmeas}, and \texttt{readNWISrating}, the \texttt{comment} attribute is useful. - -<>= -comment(peakData) - -#Which is equivalent to: -# attr(peakData, "comment") -@ - - - -%------------------------------------------------------------ -\section{Getting Started in R} -\label{sec:appendix1} -%------------------------------------------------------------ -This section describes the options for downloading and installing the dataRetrieval package. - -%------------------------------------------------------------ -\subsection{New to R?} -%------------------------------------------------------------ -If you are new to R, you will need to first install the latest version of R, which can be found here: \url{http://www.r-project.org/}. - -At any time, you can get information about any function in R by typing a question mark before the functions name. This will open a file (in RStudio, in the Help window) that describes the function, the required arguments, and provides working examples. This will open a help file similar to Figure \ref{fig:help}. To see the raw code for a particular code, type the name of the function, without parentheses. - - -<>= -?readNWISpCode -@ - -\FloatBarrier - - -\begin{figure}[ht!] -\centering - \resizebox{0.95\textwidth}{!}{\includegraphics{Rhelp.png}} -\caption{A simple R help file} -\label{fig:help} -\end{figure} - -Additionally, many R packages have vignette files attached (such as this paper). To view the vignette: -<>= -vignette(dataRetrieval) -@ - -\FloatBarrier -\clearpage -%------------------------------------------------------------ -\subsection{R User: Installing dataRetrieval} -%------------------------------------------------------------ -The following command installs dataRetrieval and subsequent required packages: - -<>= -install.packages("dataRetrieval") -@ - -After installing the package, you need to open the library each time you re-start R. This is done with the simple command: -<>= -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 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: - -<>= -availableData <- whatNWISdata(siteNumber, "dv") -dailyData <- availableData["00003" == availableData$stat_cd,] - -tableData <- with(dailyData, - data.frame( - shortName=srsname, - Start=begin_date, - End=end_date, - Count=count_nu, - Units=parameter_units) - ) -@ - -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): - - -<>= -write.table(tableData, file="tableData.tsv",sep="\t", - row.names = FALSE,quote=FALSE) -@ - -This will save a file in your working directory called tableData.tsv. You can see your working directory by typing getwd() in the R console. Opening the file in a general-purpose text editor, you should see the following: - -\begin{verbatim} -shortName Start End Count Units -Temperature, water 2010-10-01 2012-06-24 575 deg C -Stream flow, mean. daily 1948-01-01 2013-03-13 23814 ft3/s -Specific conductance 2010-10-01 2012-06-24 551 uS/cm @25C -Suspended sediment concentration (SSC) 1980-10-01 1991-09-30 3651 mg/l -Suspended sediment discharge 1980-10-01 1991-09-30 3652 tons/day -\end{verbatim} - -Next, follow the steps below to open this file in Excel: -\begin{enumerate} -\item Open Excel -\item Click on the File tab -\item Click on the Open option -\item Navigate to the working directory (as shown in the results of \texttt{getwd()}) -\item Next to the File name text box, change the dropdown type to All Files (*.*) -\item Double click tableData.tsv -\item A text import wizard will open up, in the first window, choose the Delimited radio button if it is not automatically picked, then click on Next. -\item In the second window, click on the Tab delimiter if it is not automatically checked, then click Finished. -\item Use the many formatting tools within Excel to customize the table -\end{enumerate} - -From Excel, it is simple to copy and paste the tables in other Microsoft\textregistered\ software. An example using one of the default Excel table formats is here. Additional formatting could be requried in Excel, for example converting u to $\mu$. - -\begin{figure}[ht!] -\centering - \resizebox{0.9\textwidth}{!}{\includegraphics{table1.png}} -\caption{A simple table produced in Microsoft\textregistered\ Excel.} -\label{overflow} -\end{figure} - -\clearpage - -%------------------------------------- -\section{Disclaimer} -%------------------------------------ -This information is preliminary and is subject to revision. It is being provided to meet the need for timely best science. The information is provided on the condition that neither the U.S. Geological Survey nor the U.S. Government may be held liable for any damages resulting from the authorized or unauthorized use of the information. - - -\end{document} diff --git a/inst/doc/dataRetrieval.html b/inst/doc/dataRetrieval.html new file mode 100644 index 00000000..ed74ed15 --- /dev/null +++ b/inst/doc/dataRetrieval.html @@ -0,0 +1,903 @@ + + + + + + + + + + + + + + + +Introduction to the dataRetrieval package + + + + + + + + + + + + + + + + + +

Introduction to the dataRetrieval package

+

Laura A. DeCicco and Robert M. Hirsch

+

19 May, 2017

+ + +
+ +
+ +

The dataRetrieval package was created to simplify the process of loading hydrologic data into the R environment. It is designed to retrieve the major data types of U.S. Geological Survey (USGS) hydrologic data that are available on the Web, as well as data from the Water Quality Portal (WQP), which currently houses water quality data from the Environmental Protection Agency (EPA), U.S. Department of Agriculture (USDA), and USGS. Direct USGS data is obtained from a service called the National Water Information System (NWIS).

+

For information on getting started in R and installing the package, see Getting Started. Any use of trade, firm, or product names is for descriptive purposes only and does not imply endorsement by the U.S. Government.

+

A quick workflow for USGS dataRetrieval functions:

+
library(dataRetrieval)
+# Choptank River near Greensboro, MD
+siteNumber <- "01491000"
+ChoptankInfo <- readNWISsite(siteNumber)
+parameterCd <- "00060"
+
+# Raw daily data:
+rawDailyData <- readNWISdv(siteNumber, parameterCd, "1980-01-01", 
+    "2010-01-01")
+
+# Sample data Nitrate:
+parameterCd <- "00618"
+qwData <- readNWISqw(siteNumber, parameterCd, "1980-01-01", "2010-01-01")
+
+pCode <- readNWISpCode(parameterCd)
+

USGS data are made available through the National Water Information System (NWIS).

+

Table 1 describes the functions available in the dataRetrieval package.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Table 1: dataRetrieval functions
Function.NameArgumentsDescription
readNWISdata...NWIS data using user-specified queries
service
readNWISdvsiteNumberNWIS daily data
parameterCd
startDate
endDate
statCd
readNWISqwsiteNumberNWIS water quality data
parameterCd
startDate
endDate
expanded
readNWISuvsiteNumberNWIS instantaneous value data
parameterCd
startDate
endDate
readNWISratingsiteNumberNWIS rating table for active streamgage
type
readNWISmeassiteNumberNWIS surface-water measurements
startDate
endDate
readNWISpeaksiteNumberNWIS peak flow data
startDate
endDate
readNWISgwlsiteNumberNWIS groundwater level measurements
startDate
endDate
readNWISusestateCdNWIS water use
countyCd
years
categories
readNWISstatsiteNumbersNWIS statistical service
parameterCd
startDate
endDate
statReportType
statType
readNWISpCodeparameterCdNWIS parameter code information
readNWISsitesiteNumberNWIS site information
whatNWISsites...NWIS site search using user-specified queries
whatNWISdatasiteNumberNWIS data availability, including period of record and count
service
readWQPdata...WQP data using user-specified queries
readWQPqwsiteNumberWQP data
parameterCd
startDate
endDate
whatWQPsites...WQP site search using user-specified queries
+
+

1 USGS Web Retrievals

+

In this section, examples of National Water Information System (NWIS) retrievals show how to get raw data into R. This data includes site information, measured parameter information, historical daily values, unit values (which include real-time data but can also include other sensor data stored at regular time intervals), water quality data, groundwater level data, peak flow data, rating curve data, and surface-water measurement data. The section Embedded 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 siteNumber). Often (but not always), these ID’s are 8 digits for surface-water sites and 15 digits for groundwater sites. 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.

+

Once the siteNumber is known, the next required input for USGS data retrievals is the “parameter code”. This is a 5-digit code that specifies the measured parameter being requested. For example, parameter code 00631 represents “Nitrate plus nitrite, water, filtered, milligrams per liter as nitrogen”, with units of “mg/l as N”.

+

Not every station will measure all parameters. A short list of commonly measured parameters is shown in Table 2.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Table 2: Common USGS Parameter Codes
pCodeshortName
00060Discharge [ft3/s]
00065Gage height [ft]
00010Temperature [C]
00045Precipitation [in]
00400pH
+

Two output columns that may not be obvious are “srsname” and “casrn”. Srsname stands for “Substance Registry Services”. More information on the srs name can be found here.

+

Casrn stands for “Chemical Abstracts Service (CAS) Registry Number”. More information on CAS can be found here.

+

For unit values data (sensor data measured at regular time intervals such as 15 minutes or hourly), knowing the parameter code and siteNumber is enough to make a request for data. For most variables that are measured on a continuous basis, the USGS also stores the historical data as daily values. These daily values are statistical summaries of the continuous data, e.g. maximum, minimum, mean, or median. The different statistics are specified by a 5-digit statistics code.

+

Some common codes are shown in Table 3.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
+Table 3: Commonly used USGS Stat Codes
StatCodeshortName
00001Maximum
00002Minimum
00003Mean
00008Median
+

Examples for using these site numbers, parameter codes, and statistic codes will be presented in subsequent sections.

+
+

1.1 Site Information

+
+

1.1.1 readNWISsite

+

Use the readNWISsite function to obtain all of the information available for a particular USGS site (or sites) such as full station name, drainage area, latitude, and longitude. readNWISsite can also access information about multiple sites with a vector input.

+
siteNumbers <- c("01491000", "01645000")
+siteINFO <- readNWISsite(siteNumbers)
+

Site information is obtained from: https://waterservices.usgs.gov/rest/Site-Test-Tool.html

+

Information on the returned data can be found with the comment function as described in the Metadata section.

+
comment(siteINFO)
+
+
+

1.1.2 whatNWISdata

+

To discover what data is available for a particular USGS site, including measured parameters, period of record, and number of samples (count), use the whatNWISdata function. It is possible to limit the retrieval information to a subset of services. The possible choices for services are: “dv” (daily values), “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), and “id” (historical instantaneous values).

+

In the following example, we limit the retrieved data to only daily data. The default for “service” is all, which returns all of the available data for that site. Likewise, there are arguments for parameter code (parameterCd) and statistic code (statCd) to filter the results. The default for both is to return all possible values (all). The returned count_nu for “uv” data is the count of days with returned data, not the actual count of returned values.

+
# Continuing from the previous example: This pulls out just
+# the daily, mean data:
+
+dailyDataAvailable <- whatNWISdata(siteNumbers, service = "dv", 
+    statCd = "00003")
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Table 4: Reformatted version of output from the whatNWISdata function for the Choptank River near Greensboro, MD, and from Seneca Creek at Dawsonville, MD from the daily values service [Some columns deleted for space considerations]
siteNumbersrsnamestartDateendDatecountunits
01491000Temperature, water2010-10-012012-05-09529deg C
01491000Stream flow, mean daily1948-01-012017-05-1725340ft3/s
01645000Stream flow, mean daily1930-09-262017-05-1731646ft3/s
01491000Specific conductance2010-10-012012-05-09527uS/cm @25C
01491000Suspended sediment concentration (SSC)1980-10-011991-09-304017mg/l
01491000Suspended sediment discharge1980-10-011991-09-304017tons/day
+

See Creating Tables for instructions on converting an R data frame to a table in Microsoft® software Excel or Word to display a data availability table similar to Table 4. Excel, Microsoft, PowerPoint, Windows, and Word are registered trademarks of Microsoft Corporation in the United States and other countries.

+
+
+
+

1.2 Parameter Information

+

To obtain all of the available information concerning a measured parameter (or multiple parameters), use the readNWISpCode function:

+
# Using defaults:
+parameterCd <- "00618"
+parameterINFO <- readNWISpCode(parameterCd)
+
+
+

1.3 Daily Data

+

To obtain daily records of USGS data, use the readNWISdv function. The arguments for this function are siteNumber, parameterCd, startDate, endDate, and statCd (defaults to “00003”). If you want to use the default values, you do not need to list them in the function call. Daily data is pulled from https://waterservices.usgs.gov/rest/DV-Test-Tool.html.

+

The dates (start and end) must be in the format “YYYY-MM-DD” (note: the user must include the quotes). Setting the start date to “” (no space) will prompt the program to ask for the earliest date, and setting the end date to “” (no space) will prompt for the latest available date.

+
# Choptank River near Greensboro, MD:
+siteNumber <- "01491000"
+parameterCd <- "00060"  # Discharge
+startDate <- "2009-10-01"
+endDate <- "2012-09-30"
+
+discharge <- readNWISdv(siteNumber, parameterCd, startDate, endDate)
+

The column “datetime” in the returned data frame is automatically imported as a variable of class “Date” 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 “A” (approved for publication) or “P” (provisional data subject to revision).

+

Another example would be a request for mean and maximum daily temperature and discharge in early 2012:

+
siteNumber <- "01491000"
+parameterCd <- c("00010", "00060")  # Temperature and discharge
+statCd <- c("00001", "00003")  # Mean and maximum
+startDate <- "2012-01-01"
+endDate <- "2012-05-01"
+
+temperatureAndFlow <- readNWISdv(siteNumber, parameterCd, startDate, 
+    endDate, statCd = statCd)
+

The column names can be shortened and simplified using the 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 discussed further in the metadata section.

+
names(temperatureAndFlow)
+
## [1] "agency_cd"        "site_no"          "Date"            
+## [4] "X_00010_00001_cd" "X_00010_00001"    "X_00010_00003_cd"
+## [7] "X_00010_00003"    "X_00060_00003_cd" "X_00060_00003"
+
temperatureAndFlow <- renameNWISColumns(temperatureAndFlow)
+names(temperatureAndFlow)
+
## [1] "agency_cd"    "site_no"      "Date"        
+## [4] "Wtemp_Max_cd" "Wtemp_Max"    "Wtemp_cd"    
+## [7] "Wtemp"        "Flow_cd"      "Flow"
+
# Information about the data frame attributes:
+names(attributes(temperatureAndFlow))
+
## [1] "names"         "row.names"     "url"          
+## [4] "siteInfo"      "variableInfo"  "disclaimer"   
+## [7] "statisticInfo" "queryTime"     "class"
+
statInfo <- attr(temperatureAndFlow, "statisticInfo")
+variableInfo <- attr(temperatureAndFlow, "variableInfo")
+siteInfo <- attr(temperatureAndFlow, "siteInfo")
+

An example of plotting the above data:

+
variableInfo <- attr(temperatureAndFlow, "variableInfo")
+siteInfo <- attr(temperatureAndFlow, "siteInfo")
+
+par(mar = c(5, 5, 5, 5))  #sets the size of the plot window
+
+plot(temperatureAndFlow$Date, temperatureAndFlow$Wtemp_Max, ylab = variableInfo$parameter_desc[1], 
+    xlab = "")
+par(new = TRUE)
+plot(temperatureAndFlow$Date, temperatureAndFlow$Flow, col = "red", 
+    type = "l", xaxt = "n", yaxt = "n", xlab = "", ylab = "", 
+    axes = FALSE)
+axis(4, col = "red", col.axis = "red")
+mtext(variableInfo$parameter_desc[2], side = 4, line = 3, col = "red")
+title(paste(siteInfo$station_nm, "2012"))
+legend("topleft", variableInfo$param_units, col = c("black", 
+    "red"), lty = c(NA, 1), pch = c(1, NA))
+

+

There are occasions where NWIS values are not reported as numbers, instead there might be text describing a certain event such as “Ice”. Any value that cannot be converted to a number will be reported as NA in this package (not including remark code columns).

+
+
+

1.4 Unit Data

+

Any data collected at regular time intervals (such as 15-minute or hourly) are known as “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 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.

+
parameterCd <- "00060"  # Discharge
+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 UTC (Coordinated Universal Time), so midnight EST will be 5 hours earlier in the dateTime column (the previous day, at 7pm).

+

To override the UTC timezone, specify a valid timezone in the tz argument. Default is “”, which will keep the dateTime column in UTC. Other valid timezones are:

+
America/New_York
+America/Chicago
+America/Denver
+America/Los_Angeles
+America/Anchorage
+America/Honolulu
+America/Jamaica
+America/Managua
+America/Phoenix
+America/Metlakatla
+

Data are retrieved from https://waterservices.usgs.gov/rest/IV-Test-Tool.html. There are occasions where NWIS values are not reported as numbers, instead a common example is “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 discussed further in metadata section.

+
+
+

1.5 Water Quality Data

+

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 readNWISqw, with the input arguments: siteNumber, parameterCd, startDate, and endDate. Additionally, the argument expanded 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 “reshape”, that converts the expanded dataset to a “wide” format (each requested parameter code gets individual columns). The defaults are expanded=TRUE, and reshape=FALSE.

+
# Dissolved Nitrate parameter codes:
+parameterCd <- c("00618", "71851")
+startDate <- "1985-10-01"
+endDate <- "2012-09-30"
+
+dfLong <- readNWISqw(siteNumber, parameterCd, startDate, endDate)
+
+# Or the wide return:
+dfWide <- readNWISqw(siteNumber, parameterCd, startDate, endDate, 
+    reshape = TRUE)
+

Site information and measured parameter information is attached to the data frame as attributes. This is discussed further in the metadata section. Additional metadata, such as information about the column names can be found by using the comment function, also described in the metadata section.

+
comment(dfLong)
+
+
+

1.6 Groundwater Level Data

+

Groundwater level measurements can be obtained with the readNWISgwl function. Information on the returned data can be found with the comment function, and attached attributes as described in the metadata section.

+
siteNumber <- "434400121275801"
+groundWater <- readNWISgwl(siteNumber)
+
+
+

1.7 Peak Flow Data

+

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 readNWISpeak function. Information on the returned data can be found with the comment function and attached attributes as described in the metadata section.

+
siteNumber <- "01594440"
+peakData <- readNWISpeak(siteNumber)
+
+
+

1.8 Rating Curve Data

+

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 comment function and attached attributes as described in the metadata section.

+

Rating curves can be obtained with the readNWISrating function.

+
ratingData <- readNWISrating(siteNumber, "base")
+attr(ratingData, "RATING")
+
+
+

1.9 Surface-Water Measurement Data

+

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 comment function and attached attributes as described in the metadata section.

+

Surface-water measurement data can be obtained with the readNWISmeas function.

+
surfaceData <- readNWISmeas(siteNumber)
+
+
+

1.10 Water Use Data

+

Retrieves water use data from USGS Water Use Data for the Nation. See https://waterdata.usgs.gov/nwis/wu for more information. All available use categories for the supplied arguments are retrieved.

+
allegheny <- readNWISuse(stateCd = "Pennsylvania", countyCd = "Allegheny")
+
+
+national <- readNWISuse(stateCd = NULL, countyCd = NULL, transform = TRUE)
+
+
+

1.11 Statistics Data

+

Retrieves site statistics from the USGS Statistics Web Service beta.

+
discharge_stats <- readNWISstat(siteNumbers = c("02319394"), 
+    parameterCd = c("00060"), statReportType = "annual")
+
+
+
+

2 Water Quality Portal Web Retrievals

+

There are additional water quality data sets available from the Water Quality Data Portal. These data sets can be housed in either the STORET database (data from EPA), NWIS database (data from USGS), STEWARDS database (data from USDA), and additional databases are slated to be included in the future. Because only USGS uses parameter codes, a “characteristic name” must be supplied. The readWQPqw function can take either a USGS parameter code, or a more general characteristic name in the parameterCd input argument. The Water Quality Data Portal includes data discovery tools and information on characteristic names. The following example retrieves specific conductance from a DNR site in Wisconsin.

+
specificCond <- readWQPqw("WIDNR_WQX-10032762", "Specific conductance", 
+    "2011-05-01", "2011-09-30")
+

A tool for finding NWIS characteristic names can be found here

+
+
+

3 Generalized Retrievals

+

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.

+
+

3.1 NWIS

+
+

3.1.1 Sites: whatNWISsites

+

The function whatNWISsites can be used to discover NWIS sites based on any query that the NWIS Site Service offers. This is done by using the ... argument, which allows the user to use any arbitrary input argument. We can then use the service here to discover many options for searching for NWIS sites. For example, you may want to search for sites in a lat/lon bounding box, or only sites tidal streams, or sites with water quality samples, sites above a certain altitude, etc. The results of this site query generate a URL. For example, the tool provided a search within a specified bounding box, for sites that have daily discharge (parameter code = 00060) and temperature (parameter code = 00010). The generated URL is:

+

https://waterservices.usgs.gov/nwis/site/?format=rdb&bBox=-83.0,36.5,-81.0,38.5&parameterCd=00010,00060&hasDataTypeCd=dv

+

The following dataRetrieval code can be used to get those sites:

+
sites <- whatNWISsites(bBox = c(-83, 36.5, -81, 38.5), parameterCd = c("00010", 
+    "00060"), hasDataTypeCd = "dv")
+
+
+

3.1.2 Data: readNWISdata

+

For NWIS data, the function readNWISdata can be used. The argument listed in the R help file is ... and service (only for data requests). Table 5 describes the services are available.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Table 5: NWIS general data calls
ServiceDescriptionURL
dvDailyhttps://waterservices.usgs.gov/rest/DV-Test-Tool.html
ivInstantaneoushttps://waterservices.usgs.gov/rest/IV-Test-Tool.html
gwlevelsGroundwater Levelshttps://waterservices.usgs.gov/rest/GW-Levels-Test-Tool.html
qwdataWater Qualityhttps://nwis.waterdata.usgs.gov/nwis/qwdata
measurementsSurface Water Measurementshttps://waterdata.usgs.gov/nwis/measurements/
peakPeak Flowhttps://nwis.waterdata.usgs.gov/usa/nwis/peak/
statStatistics Servicehttps://waterservices.usgs.gov/rest/Statistics-Service-Test-Tool.html
+

The ... argument allows the user to create their own queries based on the instructions found in the web links above. The links provide instructions on how to create a URL to request data. Perhaps you want sites only in Wisconsin, with a drainage area less than 50 mi2, and the most recent daily discharge data. That request would be done as follows:

+
dischargeWI <- readNWISdata(service = "dv", stateCd = "WI", parameterCd = "00060", 
+    drainAreaMin = "50", statCd = "00003")
+
+siteInfo <- attr(dischargeWI, "siteInfo")
+
+
+
+

3.2 WQP

+

Just as with NWIS, the Water Quality Portal (WQP) offers a variety of ways to search for sites and request data. The possible Web service arguments for WQP site searches is found here.

+
+

3.2.1 Sites: whatWQPsites

+

To discover available sites in the WQP in New Jersey that have measured Chloride, use the function whatWQPsites.

+
sitesNJ <- whatWQPsites(statecode = "US:34", characteristicName = "Chloride")
+
+
+

3.2.2 Data: readWQPdata

+

To get data from the WQP using generalized Web service calls, use the function readWQPdata. For example, to get all the pH data in Wisconsin:

+
dataPH <- readWQPdata(statecode = "US:55", characteristicName = "pH")
+
+
+

3.2.3 Availability: whatWQPdata

+

The function whatWQPdata returns a data frame with information on the amount of data collected at a site. For example:

+
type <- "Stream"
+sites <- whatWQPdata(countycode = "US:55:025", siteType = type)
+

This returns a data frame with all of the sites that were measured in streams in Dane County, WI. Also, in that table, there is a measure of activityCount (how often the site was sampled), and resultCount (how many individual results are available).

+
+
+

3.2.4 Samples: whatWQPsamples

+

The function whatWQPsamples returns information on the individual samples collected at a site. For example:

+
site <- whatWQPsamples(siteid = "USGS-01594440")
+

This returns one row for each instance that a sample was collect.

+
+
+

3.2.5 Metrics: whatWQPmetrics

+

The function whatWQPmetrics provides metric information. This is only currently available for STORET data:

+
type <- "Stream"
+sites <- whatWQPmetrics(countycode = "US:55:025", siteType = type)
+
+
+
+
+

4 Embedded Metadata

+

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 url (returning a character of the url used to obtain the data), siteInfo (returning a data frame with information on sites), and queryTime (returning a POSIXct datetime) attributes. For example, the url and query time used to obtain the data can be found as follows:

+
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 data frame as attributes. To discover the available attributes:

+
names(attributes(dischargeWI))
+

For data obtained from readNWISuv, readNWISdv, readNWISgwl there are two attributes that are particularly useful: siteInfo and variableInfo.

+
siteInfo <- attr(dischargeWI, "siteInfo")
+
+variableInfo <- attr(dischargeWI, "variableInfo")
+

Data obtained from readNWISpeak, readNWISmeas, and readNWISrating, the comment attribute is useful.

+
comment(peakData)
+
+# Which is equivalent to:
+attr(peakData, "comment")
+
+
+

5 Getting Started in R

+

This section describes the options for downloading and installing the dataRetrieval package.

+
+

5.1 New to R?

+

If you are new to R, you will need to first install the latest version of R, which can be found [here] (www.R-project.org).

+

At any time, you can get information about any function in R by typing a question mark before the functions name. This will open a file (in RStudio, in the Help window) that describes the function, the required arguments, and provides working examples. This will open a help file similar to the image below. To see the raw code for a particular code, type the name of the function, without parentheses.

+
?readNWISpCode
+
+A simple R help file +

A simple R help file

+
+

Additionally, many R packages have vignette files attached (such as this paper). To view the vignette:

+
vignette(dataRetrieval)
+
+
+

5.2 R User: Installing dataRetrieval

+

The following command installs dataRetrieval and subsequent required packages:

+
install.packages("dataRetrieval")
+

After installing the package, you need to open the library each time you re-start R. This is done with the simple command:

+
library(dataRetrieval)
+
+
+
+

6 Creating Tables in Microsoft® Software from R

+

There are a few steps that are required in order to create a table in Microsoft® 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:

+
availableData <- whatNWISdata(siteNumber, "dv")
+dailyData <- availableData["00003" == availableData$stat_cd, 
+    ]
+
+tableData <- with(dailyData, data.frame(shortName = srsname, 
+    Start = begin_date, End = end_date, Count = count_nu, Units = parameter_units))
+

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):

+
write.table(tableData, file = "tableData.tsv", sep = "\t", row.names = FALSE, 
+    quote = FALSE)
+

This will save a file in your working directory called tableData.tsv. You can see your working directory by typing getwd() in the R console. Opening the file in a general-purpose text editor, you should see the following:

+
shortName  Start  End   Count   Units
+Temperature, water  2010-10-01  2012-06-24  575 deg C
+Stream flow, mean. daily    1948-01-01  2013-03-13  23814   ft3/s
+Specific conductance    2010-10-01  2012-06-24  551 uS/cm 25C
+Suspended sediment concentration (SSC)  1980-10-01  1991-09-30  3651    mg/l
+Suspended sediment discharge    1980-10-01  1991-09-30  3652    tons/day
+

Next, follow the steps below to open this file in Excel:

+
    +
  1. Open Excel
    2. +
  2. Click on the File tab
    3. +
  3. Click on the Open option
    4. +
  4. Navigate to the working directory (as shown in the results of getwd())
    5. +
  5. Next to the File name text box, change the drop down type to All Files (.)
    6. +
  6. Double click tableData.tsv
    7. +
  7. A text import wizard will open up, in the first window, choose the Delimited radio button if it is not automatically picked, then click on Next.
    8. +
  8. In the second window, click on the Tab delimiter if it is not automatically checked, then click Finished.
    9. +
  9. Use the many formatting tools within Excel to customize the table
    10. +
+

From Excel, it is simple to copy and paste the tables in other Microsoft® software. An example using one of the default Excel table formats is here. Additional formatting could be required in Excel, for example converting u to \(\mu\).

+
+A simple table produced in Microsoft ® Excel. +

A simple table produced in Microsoft ® Excel.

+
+
+
+

7 Disclaimer

+

This information is preliminary and is subject to revision. It is being provided to meet the need for timely best science. The information is provided on the condition that neither the U.S. Geological Survey nor the U.S. Government may be held liable for any damages resulting from the authorized or unauthorized use of the information.

+
+ + + + + + + + diff --git a/inst/doc/dataRetrieval.pdf b/inst/doc/dataRetrieval.pdf deleted file mode 100644 index 32dac5d7356075801a1053579399186181132fcb..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 246357 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%0A<$uU_d#!zK1LVTq(vk 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
  • 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 +%QAA2;=k* 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 H(4hYt1HW*> diff --git a/vignettes/dataRetrieval.Rmd b/vignettes/dataRetrieval.Rmd new file mode 100644 index 00000000..9ad527ea --- /dev/null +++ b/vignettes/dataRetrieval.Rmd @@ -0,0 +1,763 @@ +--- +title: "Introduction to the dataRetrieval package" +date: "`r format(Sys.time(), '%d %B, %Y')`" +author: Laura A. DeCicco and Robert M. Hirsch +output: + rmarkdown::html_vignette: + toc: true + number_sections: true +vignette: > + %\VignetteEngine{knitr::rmarkdown} + %\VignetteIndexEntry{Introduction to the dataRetrieval package} + \usepackage[utf8]{inputenc} +--- + + +```{r setup, include=FALSE, message=FALSE} +library(knitr) +library(dataRetrieval) + +options(continue=" ") +options(width=60) +knitr::opts_chunk$set(echo = TRUE, + warning = FALSE, + message = FALSE, + fig.height = 7, + fig.width = 7) + +opts_chunk$set(highlight=TRUE, + tidy=TRUE, + keep.space=TRUE, + keep.blank.space=FALSE, + keep.comment=TRUE) +knit_hooks$set(inline = function(x) { + if (is.numeric(x)) round(x, 3)}) +``` + +The `dataRetrieval` package was created to simplify the process of loading hydrologic data into the R environment. It is designed to retrieve the major data types of U.S. Geological Survey (USGS) hydrologic data that are available on the Web, as well as data from the Water Quality Portal (WQP), which currently houses water quality data from the Environmental Protection Agency (EPA), U.S. Department of Agriculture (USDA), and USGS. Direct USGS data is obtained from a service called the National Water Information System (NWIS). + +For information on getting started in R and installing the package, see [Getting Started](#getting-started-in-r). Any use of trade, firm, or product names is for descriptive purposes only and does not imply endorsement by the U.S. Government. + +A quick workflow for USGS `dataRetrieval` functions: + +```{r workflow, echo=TRUE,eval=FALSE} +library(dataRetrieval) +# Choptank River near Greensboro, MD +siteNumber <- "01491000" +ChoptankInfo <- readNWISsite(siteNumber) +parameterCd <- "00060" + +#Raw daily data: +rawDailyData <- readNWISdv(siteNumber,parameterCd, + "1980-01-01","2010-01-01") + +# Sample data Nitrate: +parameterCd <- "00618" +qwData <- readNWISqw(siteNumber,parameterCd, + "1980-01-01","2010-01-01") + +pCode <- readNWISpCode(parameterCd) + +``` + +USGS data are made available through the National Water Information System (NWIS). + +Table 1 describes the functions available in the `dataRetrieval` package. + +```{r echo=FALSE} + +library(htmlTable) + +Functions <- c("readNWISdata","", + "readNWISdv","","","","", + "readNWISqw","","","","", + "readNWISuv","","","", + "readNWISrating","", + "readNWISmeas","","", + "readNWISpeak","","", + "readNWISgwl","","", + "readNWISuse","","","", + "readNWISstat","","","","","", + "readNWISpCode", + "readNWISsite", + "whatNWISsites", + "whatNWISdata","", + "readWQPdata", + "readWQPqw","","","", + "whatWQPsites") +Arguments <- c("...","service", #readNWISdata + "siteNumber","parameterCd","startDate","endDate","statCd", #readNWISdv + "siteNumber","parameterCd","startDate","endDate","expanded", #readNWISqw + "siteNumber","parameterCd","startDate","endDate", #readNWISuv + "siteNumber","type", #readNWISrating + "siteNumber","startDate","endDate", #readNWISmeas + "siteNumber","startDate","endDate", #readNWISpeak + "siteNumber","startDate","endDate", #readNWISgwl + "stateCd","countyCd","years","categories", #readNWISuse + "siteNumbers","parameterCd","startDate","endDate","statReportType","statType", #readNWISstat + "parameterCd", #readNWISpCode + "siteNumber", #readNWISsite + "...", #whatNWISsites + "siteNumber","service", #whatNWISdata + "...", #readWQPdata + "siteNumber","parameterCd","startDate","endDate", #readWQPqw + "...") #whatWQPsites +Description <- c("NWIS data using user-specified queries","", #readNWISdata + "NWIS daily data","","","","", #readNWISdv + "NWIS water quality data","","","","", #readNWISqw + "NWIS instantaneous value data","","","", #readNWISuv + "NWIS rating table for active streamgage","", #readNWISrating + "NWIS surface-water measurements","","", #readNWISmeas + "NWIS peak flow data","","", #readNWISpeak + "NWIS groundwater level measurements","","", #readNWISgwl + "NWIS water use","","","", #readNWISuse + "NWIS statistical service","","","","","", #readNWISstat + "NWIS parameter code information", #readNWISpCode + "NWIS site information", #readNWISsite + "NWIS site search using user-specified queries", + "NWIS data availability, including period of record and count","", + "WQP data using user-specified queries", + "WQP data","","","", + "WQP site search using user-specified queries") + +data.df <- data.frame(`Function Name` = Functions, Arguments, Description, stringsAsFactors=FALSE) + +htmlTable(data.df, + caption="Table 1: dataRetrieval functions", + rnames=FALSE, align=c("l","l","l","l"), + col.rgroup = c("none", "#F7F7F7"), + css.cell="padding-bottom: 0.0em; padding-right: 0.5em; padding-top: 0.0em;") + +``` + + +# USGS Web Retrievals + +In this section, examples of National Water Information System (NWIS) retrievals show how to get raw data into R. This data includes [site information](#site-information), measured [parameter information](#parameter-information), historical [daily values](#daily-data), [unit values](#unit-data) (which include real-time data but can also include other sensor data stored at regular time intervals), [water quality data](#water-quality-data), [groundwater level data](#groundwater-level-data), [peak flow data](#peak-flow-data), [rating curve data](#rating-curve-data), and [surface-water measurement data](#surface-water-measurement-data). The section [Embedded Metadata](#embedded-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 `siteNumber`). Often (but not always), these ID's are 8 digits for surface-water sites and 15 digits for groundwater sites. 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](https://maps.waterdata.usgs.gov/mapper/index.html). + +Once the `siteNumber` is known, the next required input for USGS data retrievals is the "parameter code". This is a 5-digit code that specifies the measured parameter being requested. For example, parameter code 00631 represents "Nitrate plus nitrite, water, filtered, milligrams per liter as nitrogen", with units of "mg/l as N". + +Not every station will measure all parameters. A short list of commonly measured parameters is shown in Table 2. + +```{r tableParameterCodes, echo=FALSE} + + +pCode <- c('00060', '00065', '00010','00045','00400') +shortName <- c("Discharge [ft3/s]","Gage height [ft]","Temperature [C]", "Precipitation [in]", "pH") + +data.df <- data.frame(pCode, shortName, stringsAsFactors=FALSE) + +htmlTable(data.df, + caption="Table 2: Common USGS Parameter Codes", + rnames=FALSE, align=c("c","c"), col.rgroup = c("none", "#F7F7F7"), + css.cell="padding-bottom: 0.0em; padding-right: 0.5em; padding-top: 0.0em;") + + +``` + +Two output columns that may not be obvious are "srsname" and "casrn". Srsname stands for "Substance Registry Services". More information on the srs name can be found [here](http://ofmpub.epa.gov/sor_internet/registry/substreg/home/overview/home.do). + +Casrn stands for "Chemical Abstracts Service (CAS) Registry Number". More information on CAS can be found [here](http://www.cas.org/content/chemical-substances/faqs). + +For unit values data (sensor data measured at regular time intervals such as 15 minutes or hourly), knowing the parameter code and `siteNumber` is enough to make a request for data. For most variables that are measured on a continuous basis, the USGS also stores the historical data as daily values. These daily values are statistical summaries of the continuous data, e.g. maximum, minimum, mean, or median. The different statistics are specified by a 5-digit statistics code. + +Some common codes are shown in Table 3. + +```{r tableStatCodes, echo=FALSE} +StatCode <- c('00001', '00002', '00003','00008') +shortName <- c("Maximum","Minimum","Mean", "Median") + +data.df <- data.frame(StatCode, shortName, stringsAsFactors=FALSE) + +htmlTable(data.df, + caption="Table 3: Commonly used USGS Stat Codes", + rnames=FALSE, align=c("c","c"), col.rgroup = c("none", "#F7F7F7"), + css.cell="padding-bottom: 0.0em; padding-right: 0.5em; padding-top: 0.0em;") + + + +``` + +Examples for using these site numbers, parameter codes, and statistic codes will be presented in subsequent sections. + +## Site Information + + +### readNWISsite + +Use the `readNWISsite` function to obtain all of the information available for a particular USGS site (or sites) such as full station name, drainage area, latitude, and longitude. `readNWISsite` can also access information about multiple sites with a vector input. + + +```{r getSite, echo=TRUE, eval=FALSE} +siteNumbers <- c("01491000","01645000") +siteINFO <- readNWISsite(siteNumbers) +``` + +Site information is obtained from: +[https://waterservices.usgs.gov/rest/Site-Test-Tool.html](https://waterservices.usgs.gov/rest/Site-Test-Tool.html) + +Information on the returned data can be found with the `comment` function as described in the [Metadata](#embedded-metadata) section. + +```{r siteNames3, echo=TRUE, eval=FALSE} +comment(siteINFO) +``` + + +### whatNWISdata + +To discover what data is available for a particular USGS site, including measured parameters, period of record, and number of samples (count), use the `whatNWISdata` function. It is possible to limit the retrieval information to a subset of services. The possible choices for services are: "dv" (daily values), "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), and "id" (historical instantaneous values). + +In the following example, we limit the retrieved data to only daily data. The default for "service" is `all`, which returns all of the available data for that site. Likewise, there are arguments for parameter code (`parameterCd`) and statistic code (`statCd`) to filter the results. The default for both is to return all possible values (`all`). The returned `count_nu` for "uv" data is the count of days with returned data, not the actual count of returned values. + + +```{r getSiteExtended, echo=TRUE, eval=FALSE} +# Continuing from the previous example: +# This pulls out just the daily, mean data: + +dailyDataAvailable <- whatNWISdata(siteNumbers, + service="dv", statCd="00003") + + +``` + +```{r echo=FALSE} + +tableData <- data.frame( + siteNumber = c("01491000","01491000","01645000","01491000","01491000","01491000"), + srsname = c("Temperature, water","Stream flow, mean daily", + "Stream flow, mean daily", + "Specific conductance", + "Suspended sediment concentration (SSC)", + "Suspended sediment discharge" ), + startDate = c("2010-10-01","1948-01-01","1930-09-26","2010-10-01","1980-10-01","1980-10-01"), + endDate = c("2012-05-09","2017-05-17","2017-05-17","2012-05-09","1991-09-30","1991-09-30"), + count = c("529","25340","31646","527","4017","4017"), + units = c("deg C","ft3/s","ft3/s","uS/cm @25C","mg/l","tons/day"), + stringsAsFactors = FALSE) + + +htmlTable(tableData, + caption="Table 4: Reformatted version of output from the whatNWISdata function for the Choptank River near Greensboro, MD, and from Seneca Creek at Dawsonville, MD from the daily values service [Some columns deleted for space considerations]", + rnames=FALSE, + col.rgroup = c("none", "#F7F7F7"), + css.cell="padding-bottom: 0.0em; padding-right: 0.5em; padding-top: 0.0em;") + +``` + +See [Creating Tables](#creating-tables-in-microsoft-software-from-r) for instructions on converting an R data frame to a table in Microsoft® software Excel or Word to display a data availability table similar to Table 4. Excel, Microsoft, PowerPoint, Windows, and Word are registered trademarks of Microsoft Corporation in the United States and other countries. + +## Parameter Information + +To obtain all of the available information concerning a measured parameter (or multiple parameters), use the `readNWISpCode` function: + +```{r label=getPCodeInfo, echo=TRUE, eval=FALSE} +# Using defaults: +parameterCd <- "00618" +parameterINFO <- readNWISpCode(parameterCd) +``` + + +## Daily Data + +To obtain daily records of USGS data, use the `readNWISdv` function. The arguments for this function are `siteNumber`, `parameterCd`, `startDate`, `endDate`, and `statCd` (defaults to "00003"). If you want to use the default values, you do not need to list them in the function call. Daily data is pulled from [https://waterservices.usgs.gov/rest/DV-Test-Tool.html](https://waterservices.usgs.gov/rest/DV-Test-Tool.html). + +The dates (start and end) must be in the format "YYYY-MM-DD" (note: the user must include the quotes). Setting the start date to "" (no space) will prompt the program to ask for the earliest date, and setting the end date to "" (no space) will prompt for the latest available date. + +```{r label=getNWISDaily, echo=TRUE, eval=FALSE} + +# Choptank River near Greensboro, MD: +siteNumber <- "01491000" +parameterCd <- "00060" # Discharge +startDate <- "2009-10-01" +endDate <- "2012-09-30" + +discharge <- readNWISdv(siteNumber, + parameterCd, startDate, endDate) +``` + +The column "datetime" in the returned data frame is automatically imported as a variable of class "Date" 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 "A" (approved for publication) or "P" (provisional data subject to revision). + +Another example would be a request for mean and maximum daily temperature and discharge in early 2012: + +```{r label=getNWIStemperature, echo=TRUE, eval=FALSE} +siteNumber <- "01491000" +parameterCd <- c("00010","00060") # Temperature and discharge +statCd <- c("00001","00003") # Mean and maximum +startDate <- "2012-01-01" +endDate <- "2012-05-01" + +temperatureAndFlow <- readNWISdv(siteNumber, parameterCd, + startDate, endDate, statCd=statCd) + +``` + +```{r label=getNWIStemperature2, echo=FALSE, eval=TRUE} +filePath <- system.file("extdata", package="dataRetrieval") +fileName <- "temperatureAndFlow.RData" +fullPath <- file.path(filePath, fileName) +load(fullPath) + +``` + +The column names can be shortened and simplified using the `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 discussed further in the [metadata](#embedded-metadata) section. + + +```{r label=renameColumns, echo=TRUE} +names(temperatureAndFlow) + +temperatureAndFlow <- renameNWISColumns(temperatureAndFlow) +names(temperatureAndFlow) + +``` + +```{r 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: + +```{r} +variableInfo <- attr(temperatureAndFlow, "variableInfo") +siteInfo <- attr(temperatureAndFlow, "siteInfo") + +par(mar=c(5,5,5,5)) #sets the size of the plot window + +plot(temperatureAndFlow$Date, temperatureAndFlow$Wtemp_Max, + ylab=variableInfo$parameter_desc[1],xlab="" ) +par(new=TRUE) +plot(temperatureAndFlow$Date, temperatureAndFlow$Flow, + col="red",type="l",xaxt="n",yaxt="n",xlab="",ylab="",axes=FALSE + ) +axis(4,col="red",col.axis="red") +mtext(variableInfo$parameter_desc[2],side=4,line=3,col="red") +title(paste(siteInfo$station_nm,"2012")) +legend("topleft", variableInfo$param_units, + col=c("black","red"),lty=c(NA,1),pch=c(1,NA)) +``` + + +There are occasions where NWIS values are not reported as numbers, instead there might be text describing a certain event such as "Ice". Any value that cannot be converted to a number will be reported as NA in this package (not including remark code columns). + + +## Unit Data + +Any data collected at regular time intervals (such as 15-minute or hourly) are known as "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 `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. + +```{r label=readNWISuv, eval=FALSE} + +parameterCd <- "00060" # Discharge +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 UTC (Coordinated Universal Time), so midnight EST will be 5 hours earlier in the dateTime column (the previous day, at 7pm). + +To override the UTC timezone, specify a valid timezone in the tz argument. Default is "", which will keep the dateTime column in UTC. Other valid timezones are: + +``` +America/New_York +America/Chicago +America/Denver +America/Los_Angeles +America/Anchorage +America/Honolulu +America/Jamaica +America/Managua +America/Phoenix +America/Metlakatla +``` + +Data are retrieved from [https://waterservices.usgs.gov/rest/IV-Test-Tool.html](https://waterservices.usgs.gov/rest/IV-Test-Tool.html). There are occasions where NWIS values are not reported as numbers, instead a common example is "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 discussed further in [metadata](#embedded-metadata) section. + + +## Water Quality Data + +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 `readNWISqw`, with the input arguments: `siteNumber`, `parameterCd`, `startDate`, and `endDate`. Additionally, the argument `expanded` 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 "reshape", that converts the expanded dataset to a "wide" format (each requested parameter code gets individual columns). The defaults are `expanded=TRUE`, and `reshape=FALSE`. + +```{r label=getQW, echo=TRUE, eval=FALSE} + +# Dissolved Nitrate parameter codes: +parameterCd <- c("00618","71851") +startDate <- "1985-10-01" +endDate <- "2012-09-30" + +dfLong <- readNWISqw(siteNumber, parameterCd, + startDate, endDate) + +# Or the wide return: +dfWide <- readNWISqw(siteNumber, parameterCd, + startDate, endDate, reshape=TRUE) + +``` + +Site information and measured parameter information is attached to the data frame as attributes. This is discussed further in the [metadata](#embedded-metadata) section. Additional metadata, such as information about the column names can be found by using the `comment` function, also described in the [metadata](#embedded-metadata) section. + +```{r qwmeta, echo=TRUE, eval=FALSE} + +comment(dfLong) + +``` + + +## Groundwater Level Data + +Groundwater level measurements can be obtained with the `readNWISgwl` function. Information on the returned data can be found with the `comment` function, and attached attributes as described in the [metadata](#embedded-metadata) section. + +```{r gwlexample, echo=TRUE, eval=FALSE} +siteNumber <- "434400121275801" +groundWater <- readNWISgwl(siteNumber) +``` + + +## Peak Flow Data + +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 `readNWISpeak` function. Information on the returned data can be found with the `comment` function and attached attributes as described in the [metadata](#embedded-metadata) section. + +```{r peakexample, echo=TRUE, eval=FALSE} +siteNumber <- '01594440' +peakData <- readNWISpeak(siteNumber) + +``` + + +## Rating Curve Data + +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 `comment` function and attached attributes as described in the [metadata](#embedded-metadata) section. + +Rating curves can be obtained with the `readNWISrating` function. + +```{r ratingexample, echo=TRUE, eval=FALSE} +ratingData <- readNWISrating(siteNumber, "base") +attr(ratingData, "RATING") + +``` + + +## Surface-Water Measurement Data + +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 `comment` function and attached attributes as described in the [metadata](#embedded-metadata) section. + +Surface-water measurement data can be obtained with the `readNWISmeas` function. + +```{r surfexample, echo=TRUE, eval=FALSE} +surfaceData <- readNWISmeas(siteNumber) + +``` + + +## Water Use Data +Retrieves water use data from USGS Water Use Data for the Nation. See [https://waterdata.usgs.gov/nwis/wu](https://waterdata.usgs.gov/nwis/wu) for more information. All available use categories for the supplied arguments are retrieved. + +```{r eval=FALSE} +allegheny <- readNWISuse(stateCd = "Pennsylvania", + countyCd = "Allegheny") + + +national <- readNWISuse(stateCd = NULL, + countyCd = NULL, + transform = TRUE) + +``` + +## Statistics Data +Retrieves site statistics from the USGS Statistics Web Service beta. + +```{r eval=FALSE} +discharge_stats <- readNWISstat(siteNumbers=c("02319394"), + parameterCd=c("00060"), + statReportType="annual") + +``` + + +# Water Quality Portal Web Retrievals + +There are additional water quality data sets available from the [Water Quality Data Portal](https://www.waterqualitydata.us/). These data sets can be housed in either the STORET database (data from EPA), NWIS database (data from USGS), STEWARDS database (data from USDA), and additional databases are slated to be included in the future. Because only USGS uses parameter codes, a "characteristic name" must be supplied. The `readWQPqw` function can take either a USGS parameter code, or a more general characteristic name in the parameterCd input argument. The Water Quality Data Portal includes data discovery tools and information on characteristic names. The following example retrieves specific conductance from a DNR site in Wisconsin. + + +```{r label=getQWData, echo=TRUE, eval=FALSE} +specificCond <- readWQPqw('WIDNR_WQX-10032762', + 'Specific conductance', + '2011-05-01','2011-09-30') +``` + +A tool for finding NWIS characteristic names can be found [here](https://www.waterqualitydata.us/public_srsnames/) + + +# Generalized Retrievals + +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. + +## NWIS + +### Sites: whatNWISsites + +The function `whatNWISsites` can be used to discover NWIS sites based on any query that the NWIS Site Service offers. This is done by using the `...` argument, which allows the user to use any arbitrary input argument. We can then use the service [here](https://waterservices.usgs.gov/rest/Site-Test-Tool.html) to discover many options for searching for NWIS sites. For example, you may want to search for sites in a lat/lon bounding box, or only sites tidal streams, or sites with water quality samples, sites above a certain altitude, etc. The results of this site query generate a URL. For example, the tool provided a search within a specified bounding box, for sites that have daily discharge (parameter code = 00060) and temperature (parameter code = 00010). The generated URL is: + +[https://waterservices.usgs.gov/nwis/site/?format=rdb&bBox=-83.0,36.5,-81.0,38.5¶meterCd=00010,00060&hasDataTypeCd=dv](https://waterservices.usgs.gov/nwis/site/?format=rdb&bBox=-83.0,36.5,-81.0,38.5¶meterCd=00010,00060&hasDataTypeCd=dv) + +The following `dataRetrieval` code can be used to get those sites: + +```{r siteSearch, eval=FALSE} +sites <- whatNWISsites(bBox=c(-83.0,36.5,-81.0,38.5), + parameterCd=c("00010","00060"), + hasDataTypeCd="dv") +``` + +### Data: readNWISdata + +For NWIS data, the function `readNWISdata` can be used. The argument listed in the R help file is `...` and `service` (only for data requests). Table 5 describes the services are available. + +```{r echo=FALSE} + +Service <- c("dv","iv","gwlevels","qwdata","measurements","peak","stat") +Description <- c("Daily","Instantaneous","Groundwater Levels","Water Quality","Surface Water Measurements","Peak Flow","Statistics Service") +URL <- c("https://waterservices.usgs.gov/rest/DV-Test-Tool.html", + "https://waterservices.usgs.gov/rest/IV-Test-Tool.html", + "https://waterservices.usgs.gov/rest/GW-Levels-Test-Tool.html", + "https://nwis.waterdata.usgs.gov/nwis/qwdata", + "https://waterdata.usgs.gov/nwis/measurements/", + "https://nwis.waterdata.usgs.gov/usa/nwis/peak/", + "https://waterservices.usgs.gov/rest/Statistics-Service-Test-Tool.html") + +tableData <- data.frame(Service, + Description, + URL, + stringsAsFactors = FALSE) + + +htmlTable(tableData, + caption="Table 5: NWIS general data calls", + rnames=FALSE, align=c("l","l","l"), + col.rgroup = c("none", "#F7F7F7"), + css.cell="padding-bottom: 0.0em; padding-right: 0.5em; padding-top: 0.0em;") + +``` + + +The `...` argument allows the user to create their own queries based on the instructions found in the web links above. The links provide instructions on how to create a URL to request data. Perhaps you want sites only in Wisconsin, with a drainage area less than 50 mi2, and the most recent daily discharge data. That request would be done as follows: + +```{r dataExample, eval=FALSE} +dischargeWI <- readNWISdata(service="dv", + stateCd="WI", + parameterCd="00060", + drainAreaMin="50", + statCd="00003") + +siteInfo <- attr(dischargeWI, "siteInfo") + +``` + + +## WQP + +Just as with NWIS, the Water Quality Portal (WQP) offers a variety of ways to search for sites and request data. The possible Web service arguments for WQP site searches is found [here](https://www.waterqualitydata.us/webservices_documentation). + +### Sites: whatWQPsites + +To discover available sites in the WQP in New Jersey that have measured Chloride, use the function `whatWQPsites`. + +```{r NJChloride, eval=FALSE} + +sitesNJ <- whatWQPsites(statecode="US:34", + characteristicName="Chloride") + +``` + + +### Data: readWQPdata + +To get data from the WQP using generalized Web service calls, use the function `readWQPdata`. For example, to get all the pH data in Wisconsin: + +```{r phData, eval=FALSE} +dataPH <- readWQPdata(statecode="US:55", + characteristicName="pH") +``` + + +### Availability: whatWQPdata + +The function `whatWQPdata` returns a data frame with information on the amount of data collected at a site. For example: + +```{r eval=FALSE} +type <- "Stream" +sites <- whatWQPdata(countycode="US:55:025",siteType=type) +``` + +This returns a data frame with all of the sites that were measured in streams in Dane County, WI. Also, in that table, there is a measure of `activityCount` (how often the site was sampled), and `resultCount` (how many individual results are available). + +### Samples: whatWQPsamples + +The function `whatWQPsamples` returns information on the individual samples collected at a site. For example: + +```{r eval=FALSE} +site <- whatWQPsamples(siteid="USGS-01594440") +``` + +This returns one row for each instance that a sample was collect. + +### Metrics: whatWQPmetrics + +The function `whatWQPmetrics` provides metric information. This is only currently available for STORET data: + +```{r eval=FALSE} +type <- "Stream" +sites <- whatWQPmetrics(countycode="US:55:025",siteType=type) +``` + + +# Embedded Metadata + +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 `url` (returning a character of the url used to obtain the data), `siteInfo` (returning a data frame with information on sites), and `queryTime` (returning a POSIXct datetime) attributes. For example, the url and query time used to obtain the data can be found as follows: + +```{r meta1, eval=FALSE} + +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 data frame as attributes. To discover the available attributes: + +```{r meta2, eval=FALSE} + +names(attributes(dischargeWI)) + +``` + +For data obtained from `readNWISuv`, `readNWISdv`, `readNWISgwl` there are two attributes that are particularly useful: `siteInfo` and `variableInfo`. + +```{r meta3, eval=FALSE} + +siteInfo <- attr(dischargeWI, "siteInfo") + +variableInfo <- attr(dischargeWI, "variableInfo") + + +``` + +Data obtained from `readNWISpeak`, `readNWISmeas`, and `readNWISrating`, the `comment` attribute is useful. + +```{r meta5, eval=FALSE} +comment(peakData) + +#Which is equivalent to: +attr(peakData, "comment") +``` + + +# Getting Started in R + +This section describes the options for downloading and installing the `dataRetrieval` package. + +## New to R? + +If you are new to R, you will need to first install the latest version of R, which can be found [here] (www.R-project.org). + +At any time, you can get information about any function in R by typing a question mark before the functions name. This will open a file (in RStudio, in the Help window) that describes the function, the required arguments, and provides working examples. This will open a help file similar to the image below. To see the raw code for a particular code, type the name of the function, without parentheses. + + +``` +?readNWISpCode +``` + + +![A simple R help file](Rhelp.png) + + +Additionally, many R packages have vignette files attached (such as this paper). To view the vignette: +```{r seeVignette,eval = FALSE} +vignette(dataRetrieval) +``` + + +## R User: Installing dataRetrieval + +The following command installs `dataRetrieval` and subsequent required packages: + +```{r installFromCran,eval = FALSE} +install.packages("dataRetrieval") +``` + +After installing the package, you need to open the library each time you re-start R. This is done with the simple command: + +```{r openLibraryTest, eval=FALSE} +library(dataRetrieval) +``` + + + +# Creating Tables in Microsoft® Software from R + +There are a few steps that are required in order to create a table in Microsoft® 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: + +```{r label=getSiteApp, echo=TRUE, eval=FALSE} +availableData <- whatNWISdata(siteNumber, "dv") +dailyData <- availableData["00003" == availableData$stat_cd,] + +tableData <- with(dailyData, + data.frame( + shortName=srsname, + Start=begin_date, + End=end_date, + Count=count_nu, + Units=parameter_units) + ) +``` + +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): + + +```{r label=saveData, echo=TRUE, eval=FALSE} +write.table(tableData, file="tableData.tsv",sep="\t", + row.names = FALSE,quote=FALSE) +``` + +This will save a file in your working directory called tableData.tsv. You can see your working directory by typing `getwd()` in the R console. Opening the file in a general-purpose text editor, you should see the following: + +``` +shortName Start End Count Units +Temperature, water 2010-10-01 2012-06-24 575 deg C +Stream flow, mean. daily 1948-01-01 2013-03-13 23814 ft3/s +Specific conductance 2010-10-01 2012-06-24 551 uS/cm 25C +Suspended sediment concentration (SSC) 1980-10-01 1991-09-30 3651 mg/l +Suspended sediment discharge 1980-10-01 1991-09-30 3652 tons/day +``` + +Next, follow the steps below to open this file in Excel: + +1. Open Excel +2. Click on the File tab +3. Click on the Open option +4. Navigate to the working directory (as shown in the results of `getwd()`) +5. Next to the File name text box, change the drop down type to All Files (*.*) +6. Double click tableData.tsv +7. A text import wizard will open up, in the first window, choose the Delimited radio button if it is not automatically picked, then click on Next. +8. In the second window, click on the Tab delimiter if it is not automatically checked, then click Finished. +9. Use the many formatting tools within Excel to customize the table + +From Excel, it is simple to copy and paste the tables in other Microsoft® software. An example using one of the default Excel table formats is here. Additional formatting could be required in Excel, for example converting u to $\mu$. + +![A simple table produced in Microsoft ® Excel.](table1.png) + + +# Disclaimer +This information is preliminary and is subject to revision. It is being provided to meet the need for timely best science. The information is provided on the condition that neither the U.S. Geological Survey nor the U.S. Government may be held liable for any damages resulting from the authorized or unauthorized use of the information. + + diff --git a/vignettes/dataRetrieval.Rnw b/vignettes/dataRetrieval.Rnw deleted file mode 100644 index 16dfa930..00000000 --- a/vignettes/dataRetrieval.Rnw +++ /dev/null @@ -1,960 +0,0 @@ -%\VignetteIndexEntry{Introduction to the dataRetrieval package} -%\VignetteEngine{knitr::knitr} -%\VignetteDepends{} -%\VignetteSuggests{xtable, testthat} -%\VignetteImports{XML, httr, reshape2,lubridate,utils,stats} -%\VignettePackage{dataRetrieval} - -\documentclass[a4paper,11pt]{article} - -\usepackage{amsmath} -\usepackage{times} -\usepackage{hyperref} -\usepackage[numbers, round]{natbib} -\usepackage[american]{babel} -\usepackage{authblk} -\usepackage{subfig} -\usepackage{placeins} -\usepackage{footnote} -\usepackage{tabularx} -\usepackage{threeparttable} -\usepackage{parskip} - -\usepackage{csquotes} -\usepackage{setspace} - -% \doublespacing - -\renewcommand{\topfraction}{0.85} -\renewcommand{\textfraction}{0.1} -\usepackage{graphicx} - - -\usepackage{mathptmx}% Times Roman font -\usepackage[scaled=.90]{helvet}% Helvetica, served as a model for arial - -% \usepackage{indentfirst} -% \setlength\parindent{20pt} -\setlength{\parskip}{0pt} - -\usepackage{courier} - -\usepackage{titlesec} -\usepackage{titletoc} - -\titleformat{\section} - {\normalfont\sffamily\bfseries\LARGE} - {\thesection}{0.5em}{} -\titleformat{\subsection} - {\normalfont\sffamily\bfseries\Large} - {\thesubsection}{0.5em}{} -\titleformat{\subsubsection} - {\normalfont\sffamily\large} - {\thesubsubsection}{0.5em}{} - -\titlecontents{section} -[2em] % adjust left margin -{\sffamily} % font formatting -{\contentslabel{2.3em}} % section label and offset -{\hspace*{-2.3em}} -{\titlerule*[0.25pc]{.}\contentspage} - -\titlecontents{subsection} -[4.6em] % adjust left margin -{\sffamily} % font formatting -{\contentslabel{2.3em}} % section label and offset -{\hspace*{-2.3em}} -{\titlerule*[0.25pc]{.}\contentspage} - -\titlecontents{subsubsection} -[6.9em] % adjust left margin -{\sffamily} % font formatting -{\contentslabel{2.3em}} % section label and offset -{\hspace*{-2.3em}} -{\titlerule*[0.25pc]{.}\contentspage} - -\titlecontents{table} -[0em] % adjust left margin -{\sffamily} % font formatting -{Table\hspace*{2em} \contentslabel {2em}} % section label and offset -{\hspace*{4em}} -{\titlerule*[0.25pc]{.}\contentspage} - -\titlecontents{figure} -[0em] % adjust left margin -{\sffamily} % font formatting -{Figure\hspace*{2em} \contentslabel {2em}} % section label and offset -{\hspace*{4em}} -{\titlerule*[0.25pc]{.}\contentspage} - -%Italisize and change font of urls: -\urlstyle{sf} -\renewcommand\UrlFont\itshape - -\usepackage{caption} -\captionsetup{ - font={sf}, - labelfont={bf,sf}, - labelsep=period, - justification=justified, - singlelinecheck=false -} - - - -\textwidth=6.2in -\textheight=8.5in -\parskip=.3cm -\oddsidemargin=.1in -\evensidemargin=.1in -\headheight=-.3in - - -%------------------------------------------------------------ -% newcommand -%------------------------------------------------------------ -\newcommand{\scscst}{\scriptscriptstyle} -\newcommand{\scst}{\scriptstyle} -\newcommand{\Robject}[1]{{\texttt{#1}}} -\newcommand{\Rfunction}[1]{{\texttt{#1}}} -\newcommand{\Rclass}[1]{\textit{#1}} -\newcommand{\Rpackage}[1]{\textit{#1}} -\newcommand{\Rexpression}[1]{\texttt{#1}} -\newcommand{\Rmethod}[1]{{\texttt{#1}}} -\newcommand{\Rfunarg}[1]{{\texttt{#1}}} - -\begin{document} - -<>= -library(xtable) -options(continue=" ") -options(width=60) -library(knitr) - -@ - -\renewenvironment{knitrout}{\begin{singlespace}}{\end{singlespace}} -\renewcommand*\listfigurename{Figures} - -\renewcommand*\listtablename{Tables} - - -%------------------------------------------------------------ -\title{The dataRetrieval R package} -%------------------------------------------------------------ -\author[1]{Laura A. De Cicco} -\author[1]{Robert M. Hirsch} -\affil[1]{United States Geological Survey} - - -<>= -opts_chunk$set(highlight=TRUE, tidy=TRUE, keep.space=TRUE, keep.blank.space=FALSE, keep.comment=TRUE, tidy=FALSE,comment="") -knit_hooks$set(inline = function(x) { - if (is.numeric(x)) round(x, 3)}) -knit_hooks$set(crop = hook_pdfcrop) - -bold.colHeaders <- function(x) { - x <- gsub("\\^(\\d)","$\\^\\1$",x) - x <- gsub("\\%","\\\\%",x) - x <- gsub("\\_"," ",x) - returnX <- paste("\\multicolumn{1}{c}{\\textbf{\\textsf{", x, "}}}", sep = "") -} -addSpace <- function(x) ifelse(x != "1", "[5pt]","") -library(dataRetrieval) -@ - -\noindent{\huge\textsf{\textbf{The dataRetrieval R package}}} - -\noindent\textsf{By Laura A. De Cicco and Robert M. Hirsch} - -\noindent\textsf{\today} - -% \maketitle -% -% \newpage - -\tableofcontents -\listoffigures -\listoftables - -\newpage - -%------------------------------------------------------------ -\section{Introduction to dataRetrieval} -%------------------------------------------------------------ -The dataRetrieval package was created to simplify the process of loading hydrologic data into the R environment. It is designed to retrieve the major data types of U.S. Geological Survey (USGS) hydrologic data that are available on the Web, as well as data from the Water Quality Portal (WQP), which currently houses water quality data from the Environmental Protection Agency (EPA), U.S. Department of Agriculture (USDA), and USGS. Direct USGS data is obtained from a service called the National Water Information System (NWIS). - -For information on getting started in R and installing the package, see (\ref{sec:appendix1}): Getting Started. Any use of trade, firm, or product names is for descriptive purposes only and does not imply endorsement by the U.S. Government. - -A quick workflow for USGS dataRetrieval functions: - -<>= -library(dataRetrieval) -# Choptank River near Greensboro, MD -siteNumber <- "01491000" -ChoptankInfo <- readNWISsite(siteNumber) -parameterCd <- "00060" - -#Raw daily data: -rawDailyData <- readNWISdv(siteNumber,parameterCd, - "1980-01-01","2010-01-01") - -# Sample data Nitrate: -parameterCd <- "00618" -qwData <- readNWISqw(siteNumber,parameterCd, - "1980-01-01","2010-01-01") - -pCode <- readNWISpCode(parameterCd) - -@ - -USGS data are made available through the National Water Information System (NWIS). - -Table \ref{tab:func} describes the functions available in the dataRetrieval package. - -\begin{table}[!ht] -\begin{minipage}{\linewidth} -{\footnotesize -\caption{dataRetrieval functions} -\label{tab:func} -\begin{tabular}{lll} - \hline -\multicolumn{1}{c}{\textbf{\textsf{Function Name}}} & -\multicolumn{1}{c}{\textbf{\textsf{Arguments}}} & -\multicolumn{1}{c}{\textbf{\textsf{Description}}} \\ [0pt] - \hline - \texttt{readNWISdata} & \texttt{...} & NWIS data using user-specified queries\\ - & service & \\ - [5pt]\texttt{readNWISdv} & siteNumber & NWIS daily data\\ - & parameterCd & \\ - & startDate & \\ - & endDate & \\ - & statCd & \\ - [5pt]\texttt{readNWISqw} & siteNumber & NWIS water quality data\\ - & parameterCd & \\ - & startDate & \\ - & endDate & \\ - & expanded & \\ - [5pt]\texttt{readNWISuv} & siteNumber & NWIS instantaneous value data\\ - & parameterCd & \\ - & startDate & \\ - & endDate & \\ - [5pt]\texttt{readNWISrating} & siteNumber & NWIS rating table for active streamgage \\ - & type & \\ - [5pt]\texttt{readNWISmeas} & siteNumber & NWIS surface-water measurements \\ - & startDate & \\ - & endDate & \\ - [5pt]\texttt{readNWISpeak} & siteNumber & NWIS peak flow data \\ - & startDate & \\ - & endDate & \\ - [5pt]\texttt{readNWISgwl} & siteNumber & NWIS groundwater level measurements \\ - & startDate & \\ - & endDate & \\ - [5pt]\texttt{readNWISpCode} & parameterCd & NWIS parameter code information\\ - [5pt]\texttt{readNWISsite} & siteNumber & NWIS site information \\ - [5pt]\texttt{whatNWISsites} & \texttt{...} & NWIS site search using user-specified queries \\ - [5pt]\texttt{whatNWISdata} & siteNumber & NWIS data availability, including period of record and count \\ - & service & \\ - [5pt]\texttt{readWQPdata} & \texttt{...} & WQP data using user-specified queries \\ - [5pt]\texttt{readWQPqw} & siteNumber & WQP data \\ - & parameterCd (or characteristic name) & \\ - & startDate & \\ - & endDate & \\ - [5pt]\texttt{whatWQPsites} & \texttt{...} & WQP site search using user-specified queries \\ - \hline -\end{tabular} -} -\end{minipage} -\end{table} - -\clearpage - -%------------------------------------------------------------ -\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 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 for surface-water sites and 15 digits for groundwater sites. 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{https://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}. - -Not every station will measure all parameters. A short list of commonly measured parameters is shown in Table \ref{tab:params}. - -<>= -pCode <- c('00060', '00065', '00010','00045','00400') -shortName <- c("Discharge [ft$^3$/s]","Gage height [ft]","Temperature [C]", "Precipitation [in]", "pH") - -data.df <- data.frame(pCode, shortName, stringsAsFactors=FALSE) - -print(xtable(data.df, - label="tab:params", - caption="Common USGS Parameter Codes"), - caption.placement="top", - size = "\\footnotesize", - latex.environment=NULL, - sanitize.text.function = function(x) {x}, - sanitize.colnames.function = bold.colHeaders, - sanitize.rownames.function = addSpace - ) - -@ - -Two output columns that may not be obvious are \enquote{srsname} and \enquote{casrn}. Srsname stands for \enquote{Substance Registry Services}. More information on the srs name can be found here: - -\url{http://ofmpub.epa.gov/sor_internet/registry/substreg/home/overview/home.do} - -Casrn stands for \enquote{Chemical Abstracts Service (CAS) Registry Number}. More information on CAS can be found here: - -\url{http://www.cas.org/content/chemical-substances/faqs} - -For unit values data (sensor data measured at regular time intervals such as 15 minutes or hourly), knowing the parameter code and siteNumber is enough to make a request for data. For most variables that are measured on a continuous basis, the USGS also stores the historical data as daily values. These daily values are statistical summaries of the continuous data, e.g. maximum, minimum, mean, or median. The different statistics are specified by a 5-digit statistics code. - -Some common codes are shown in Table \ref{tab:stat}. - -<>= -StatCode <- c('00001', '00002', '00003','00008') -shortName <- c("Maximum","Minimum","Mean", "Median") - -data.df <- data.frame(StatCode, shortName, stringsAsFactors=FALSE) - -print(xtable(data.df,label="tab:stat", - caption="Commonly used USGS Stat Codes"), - caption.placement="top", - size = "\\footnotesize", - latex.environment=NULL, - sanitize.colnames.function = bold.colHeaders, - sanitize.rownames.function = addSpace - ) - -@ - -Examples for using these siteNumbers, parameter codes, and stat codes will be presented in subsequent sections. - -\FloatBarrier - -%------------------------------------------------------------ -\subsection{Site Information} -\label{sec:usgsSite} -%------------------------------------------------------------ - -%------------------------------------------------------------ -\subsubsection{readNWISsite} -\label{sec:usgsSiteFileData} -%------------------------------------------------------------ -Use the \texttt{readNWISsite} function to obtain all of the information available for a particular USGS site (or sites) such as full station name, drainage area, latitude, and longitude. \texttt{readNWISsite} can also access information about multiple sites with a vector input. - - -<>= -siteNumbers <- c("01491000","01645000") -siteINFO <- readNWISsite(siteNumbers) -@ - -Site information is obtained from: -\url{https://waterservices.usgs.gov/rest/Site-Test-Tool.html} - -Information on the returned data can be found with the \texttt{comment} function as described in section \ref{sec:metadata}. - -<>= -comment(siteINFO) -@ - - - -\FloatBarrier - -%------------------------------------------------------------ -\subsubsection{whatNWISdata} -\label{sec:usgsDataAvailability} -%------------------------------------------------------------ -To discover what data is available for a particular USGS site, including measured parameters, period of record, and number of samples (count), use the \texttt{whatNWISdata} function. It is possible to limit the retrieval information to a subset of services. The possible choices for services are: \texttt{"}dv\texttt{"} (daily values), \texttt{"}uv\texttt{"}, \texttt{"}rt\texttt{"}, or \texttt{"}iv\texttt{"} (unit values), \texttt{"}qw\texttt{"} (water-quality), \texttt{"}sv\texttt{"} (sites visits), \texttt{"}pk\texttt{"} (peak measurements), \texttt{"}gw\texttt{"} (groundwater levels), \texttt{"}ad\texttt{"} (sites included in USGS Annual Water Data Reports External Link), \texttt{"}aw\texttt{"} (sites monitored by the USGS Active Groundwater Level Network External Link), and \texttt{"}id\texttt{"} (historical instantaneous values). - -In the following example, we limit the retrieved data to only daily data. The default for \texttt{"}service\texttt{"} is \enquote{all}, which returns all of the available data for that site. Likewise, there are arguments for parameter code (\texttt{parameterCd}) and statistic code (\texttt{statCd}) to filter the results. The default for both is to return all possible values (\enquote{all}). The returned \texttt{"}count\_nu\texttt{"} for \texttt{"}uv\texttt{"} data is the count of days with returned data, not the actual count of returned values. - - -<>= -# Continuing from the previous example: -# This pulls out just the daily, mean data: - -dailyDataAvailable <- whatNWISdata(siteNumbers, - service="dv", statCd="00003") - - -@ - -<>= -tableData <- with(dailyDataAvailable, - data.frame( - siteNumber= site_no, - srsname=srsname, - startDate=as.character(begin_date), - endDate=as.character(end_date), - count=as.character(count_nu), - units=parameter_units, -# statCd = stat_cd, - stringsAsFactors=FALSE) - ) - -tableData$units[which(tableData$units == "ft3/s")] <- "ft$^3$/s" -tableData$units[which(tableData$units == "uS/cm @25C")] <- "$\\mu$S/cm @25C" - - -print(xtable(tableData,label="tab:gda", - caption="Reformatted version of output from \\texttt{whatNWISdata} function for the Choptank River near Greensboro, MD, and from Seneca Creek at Dawsonville, MD from the daily values service [Some columns deleted for space considerations]"), - caption.placement="top", - size = "\\footnotesize", - latex.environment=NULL, - sanitize.text.function = function(x) {x}, - sanitize.colnames.function = bold.colHeaders, - sanitize.rownames.function = addSpace - ) - -@ - -\begin{table}[ht] -\caption{Reformatted version of output from \texttt{whatNWISdata} function for the Choptank River near Greensboro, MD, and from Seneca Creek at Dawsonville, MD from the daily values service [Some columns deleted for space considerations]} -\label{tab:gda} -{\footnotesize -\begin{tabular}{rllllll} - \hline - & \multicolumn{1}{c}{\textbf{\textsf{siteNumber}}} & \multicolumn{1}{c}{\textbf{\textsf{srsname}}} & \multicolumn{1}{c}{\textbf{\textsf{startDate}}} & \multicolumn{1}{c}{\textbf{\textsf{endDate}}} & \multicolumn{1}{c}{\textbf{\textsf{count}}} & \multicolumn{1}{c}{\textbf{\textsf{units}}} \\ - \hline - & 01491000 & Temperature, water & 2010-10-01 & 2012-05-09 & 529 & deg C \\ - [5pt] & 01645000 & Stream flow, mean. daily & 1930-09-26 & 2015-02-19 & 30828 & ft$^3$/s \\ - [5pt] & 01491000 & Stream flow, mean. daily & 1948-01-01 & 2015-02-19 & 24522 & ft$^3$/s \\ - [5pt] & 01491000 & Specific conductance & 2010-10-01 & 2012-05-09 & 527 & $\mu$S/cm @25C \\ - [5pt] & 01491000 & Suspended sediment concentration (SSC) & 1980-10-01 & 1991-09-30 & 3651 & mg/l \\ - [5pt] & 01491000 & Suspended sediment discharge & 1980-10-01 & 1991-09-30 & 3652 & tons/day \\ - \hline -\end{tabular} -} -\end{table} - -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 - -%------------------------------------------------------------ -\subsection{Parameter Information} -\label{sec:usgsParams} -%------------------------------------------------------------ -To obtain all of the available information concerning a measured parameter (or multiple parameters), use the \texttt{readNWISpCode} function: - -<>= -# Using defaults: -parameterCd <- "00618" -parameterINFO <- readNWISpCode(parameterCd) -@ - - -\FloatBarrier - -%------------------------------------------------------------ -\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. Daily data is pulled from \url{https://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. - -<>= - -# Choptank River near Greensboro, MD: -siteNumber <- "01491000" -parameterCd <- "00060" # Discharge -startDate <- "2009-10-01" -endDate <- "2012-09-30" - -discharge <- readNWISdv(siteNumber, - parameterCd, startDate, endDate) -@ - -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). - -Another example would be a request for mean and maximum daily temperature and discharge in early 2012: - -<>= -siteNumber <- "01491000" -parameterCd <- c("00010","00060") # Temperature and discharge -statCd <- c("00001","00003") # Mean and maximum -startDate <- "2012-01-01" -endDate <- "2012-05-01" - -temperatureAndFlow <- readNWISdv(siteNumber, parameterCd, - startDate, endDate, statCd=statCd) - -@ - -<>= -filePath <- system.file("extdata", package="dataRetrieval") -fileName <- "temperatureAndFlow.RData" -fullPath <- file.path(filePath, fileName) -load(fullPath) - -@ - -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}. - - -<>= -names(temperatureAndFlow) - -temperatureAndFlow <- renameNWISColumns(temperatureAndFlow) -names(temperatureAndFlow) - -@ - -<>= -#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}): - -<>= -variableInfo <- attr(temperatureAndFlow, "variableInfo") -siteInfo <- attr(temperatureAndFlow, "siteInfo") - -par(mar=c(5,5,5,5)) #sets the size of the plot window - -plot(temperatureAndFlow$Date, temperatureAndFlow$Wtemp_Max, - ylab=variableInfo$parameter_desc[1],xlab="" ) -par(new=TRUE) -plot(temperatureAndFlow$Date, temperatureAndFlow$Flow, - col="red",type="l",xaxt="n",yaxt="n",xlab="",ylab="",axes=FALSE - ) -axis(4,col="red",col.axis="red") -mtext(variableInfo$parameter_desc[2],side=4,line=3,col="red") -title(paste(siteInfo$station_nm,"2012")) -legend("topleft", variableInfo$param_units, - col=c("black","red"),lty=c(NA,1),pch=c(1,NA)) -@ - - -There are occasions where NWIS values are not reported as numbers, instead there might be text describing a certain event such as \enquote{Ice.} Any value that cannot be converted to a number will be reported as NA in this package (not including remark code columns). - -\FloatBarrier - -%------------------------------------------------------------ -\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. - -<>= - -parameterCd <- "00060" # Discharge -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). - -To override the UTC timezone, specify a valid timezone in the tz argument. Default is \texttt{""}, which will keep the dateTime column in UTC. Other valid timezones are: - -\begin{verbatim} -America/New_York -America/Chicago -America/Denver -America/Los_Angeles -America/Anchorage -America/Honolulu -America/Jamaica -America/Managua -America/Phoenix -America/Metlakatla -\end{verbatim} - -Data are retrieved from \url{https://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 - - -\FloatBarrier - -%------------------------------------------------------------ -\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). The defaults are expanded=TRUE, and reshape=FALSE. - -<>= - -# Dissolved Nitrate parameter codes: -parameterCd <- c("00618","71851") -startDate <- "1985-10-01" -endDate <- "2012-09-30" - -dfLong <- readNWISqw(siteNumber, parameterCd, - startDate, endDate) - -# Or the wide return: -# dfWide <- readNWISqw(siteNumber, parameterCd, -# startDate, endDate, reshape=TRUE) - -@ - -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}. - -<>= - -comment(dfLong) - -@ - -\FloatBarrier - -%------------------------------------------------------------ -\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, and attached attributes as described in section \ref{sec:metadata}. - -<>= -siteNumber <- "434400121275801" -groundWater <- readNWISgwl(siteNumber) -@ - -%------------------------------------------------------------ -\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 and attached attributes as described in section \ref{sec:metadata}. - -<>= -siteNumber <- '01594440' -peakData <- readNWISpeak(siteNumber) - -@ - - -%------------------------------------------------------------ -\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 and attached attributes as described in section \ref{sec:metadata}. - -Rating curves can be obtained with the \texttt{readNWISrating} function. - -<>= -ratingData <- readNWISrating(siteNumber, "base") -attr(ratingData, "RATING") - -@ - - - -%------------------------------------------------------------ -\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 and attached attributes as described in section \ref{sec:metadata}. - -Surface-water measurement data can be obtained with the \texttt{readNWISmeas} function. - -<>= -surfaceData <- readNWISmeas(siteNumber) - -@ - - -%------------------------------------------------------------ -\section{Water Quality Portal Web Retrievals} -\label{sec:usgsSTORET} -%------------------------------------------------------------ -There are additional water quality data sets available from the Water Quality Data Portal (\url{https://www.waterqualitydata.us/}). These data sets can be housed in either the STORET database (data from EPA), NWIS database (data from USGS), STEWARDS database (data from USDA), and additional databases are slated to be included in the future. Because only USGS uses parameter codes, a \texttt{"}characteristic name\texttt{"} must be supplied. The \texttt{readWQPqw} function can take either a USGS parameter code, or a more general characteristic name in the parameterCd input argument. The Water Quality Data Portal includes data discovery tools and information on characteristic names. The following example retrieves specific conductance from a DNR site in Wisconsin. - - -<>= -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{https://www.waterqualitydata.us/public_srsnames/} - -\FloatBarrier - -%------------------------------------------------------------ -\section{Generalized Retrievals} -\label{sec:general} -%------------------------------------------------------------ -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} -\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: - -\url{https://waterservices.usgs.gov/rest/Site-Test-Tool.html} - -to discover many options for searching for NWIS sites. For example, you may want to search for sites in a lat/lon bounding box, or only sites tidal streams, or sites with water quality samples, sites above a certain altitude, etc. The results of this site query generate a URL. For example, the tool provided a search within a specified bounding box, for sites that have daily discharge (parameter code = 00060) and temperature (parameter code = 00010). The generated URL is: - -\url{https://waterservices.usgs.gov/nwis/site/?format=rdb&bBox=-83.0,36.5,-81.0,38.5¶meterCd=00010,00060&hasDataTypeCd=dv} - -The following dataRetrieval code can be used to get those sites: - -<>= -sites <- whatNWISsites(bBox=c(-83.0,36.5,-81.0,38.5), - parameterCd=c("00010","00060"), - hasDataTypeCd="dv") -@ - - -%------------------------------------------------------------ -\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. - -\begin{table}[!ht] -\begin{minipage}{\linewidth} -{\footnotesize -\caption{NWIS general data calls} -\label{tab:NWISGeneral} -\begin{tabular}{lll} - \hline -\multicolumn{1}{c}{\textbf{\textsf{Service}}} & -\multicolumn{1}{c}{\textbf{\textsf{Description}}} & -\multicolumn{1}{c}{\textbf{\textsf{Reference URL}}} \\ [0pt] - \hline - daily values & dv & \url{https://waterservices.usgs.gov/rest/DV-Test-Tool.html}\\ - [5pt]instantaneous & iv & \url{https://waterservices.usgs.gov/rest/IV-Test-Tool.html}\\ - [5pt]groundwater levels & gwlevels & \url{https://waterservices.usgs.gov/rest/GW-Levels-Test-Tool.html}\\ - [5pt]water quality & qwdata & \url{https://nwis.waterdata.usgs.gov/nwis/qwdata}\\ - \hline -\end{tabular} -} -\end{minipage} -\end{table} - -The \texttt{"..."} argument allows the user to create their own queries based on the instructions found in the web links above. The links provide instructions on how to create a URL to request data. Perhaps you want sites only in Wisconsin, with a drainage area less than 50 mi$^2$, and the most recent daily dischage data. That request would be done as follows: - -<>= -dischargeWI <- readNWISdata(service="dv", - stateCd="WI", - parameterCd="00060", - drainAreaMin="50", - statCd="00003") - -siteInfo <- attr(dischargeWI, "siteInfo") - -@ - -%------------------------------------------------------------ -\subsubsection{WQP Sites} -\label{sec:WQPGenSite} -%------------------------------------------------------------ - -Just as with NWIS, the Water Quality Portal (WQP) offers a variety of ways to search for sites and request data. The possible Web service arguments for WQP site searches is found here: - -\url{https://www.waterqualitydata.us/webservices_documentation} - -To discover available sites in the WQP in New Jersey that have measured Chloride, use the function \texttt{whatWQPsites}. - -<>= - -sitesNJ <- whatWQPsites(statecode="US:34", - characteristicName="Chloride") - -@ - - -%------------------------------------------------------------ -\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: - -<>= - -dataPH <- readWQPdata(statecode="US:55", - characteristicName="pH") - -@ - - - -\FloatBarrier - -\clearpage - -%------------------------------------------------------------ -\section{Embedded Metadata} -\label{sec:metadata} -%------------------------------------------------------------ -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: - -<>= - -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 data frame as attributes. To discover the available attributes: - -<>= - -names(attributes(dischargeWI)) - -@ - -For data obtained from \texttt{readNWISuv}, \texttt{readNWISdv}, \texttt{readNWISgwl} there are two attributes that are particularly useful: \texttt{siteInfo} and \texttt{variableInfo}. - -<>= - -siteInfo <- attr(dischargeWI, "siteInfo") - -variableInfo <- attr(dischargeWI, "variableInfo") - - -@ - -Data obtained from \texttt{readNWISpeak}, \texttt{readNWISmeas}, and \texttt{readNWISrating}, the \texttt{comment} attribute is useful. - -<>= -comment(peakData) - -#Which is equivalent to: -# attr(peakData, "comment") -@ - - - -%------------------------------------------------------------ -\section{Getting Started in R} -\label{sec:appendix1} -%------------------------------------------------------------ -This section describes the options for downloading and installing the dataRetrieval package. - -%------------------------------------------------------------ -\subsection{New to R?} -%------------------------------------------------------------ -If you are new to R, you will need to first install the latest version of R, which can be found here: \url{http://www.r-project.org/}. - -At any time, you can get information about any function in R by typing a question mark before the functions name. This will open a file (in RStudio, in the Help window) that describes the function, the required arguments, and provides working examples. This will open a help file similar to Figure \ref{fig:help}. To see the raw code for a particular code, type the name of the function, without parentheses. - - -<>= -?readNWISpCode -@ - -\FloatBarrier - - -\begin{figure}[ht!] -\centering - \resizebox{0.95\textwidth}{!}{\includegraphics{Rhelp.png}} -\caption{A simple R help file} -\label{fig:help} -\end{figure} - -Additionally, many R packages have vignette files attached (such as this paper). To view the vignette: -<>= -vignette(dataRetrieval) -@ - -\FloatBarrier -\clearpage -%------------------------------------------------------------ -\subsection{R User: Installing dataRetrieval} -%------------------------------------------------------------ -The following command installs dataRetrieval and subsequent required packages: - -<>= -install.packages("dataRetrieval") -@ - -After installing the package, you need to open the library each time you re-start R. This is done with the simple command: -<>= -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 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: - -<>= -availableData <- whatNWISdata(siteNumber, "dv") -dailyData <- availableData["00003" == availableData$stat_cd,] - -tableData <- with(dailyData, - data.frame( - shortName=srsname, - Start=begin_date, - End=end_date, - Count=count_nu, - Units=parameter_units) - ) -@ - -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): - - -<>= -write.table(tableData, file="tableData.tsv",sep="\t", - row.names = FALSE,quote=FALSE) -@ - -This will save a file in your working directory called tableData.tsv. You can see your working directory by typing getwd() in the R console. Opening the file in a general-purpose text editor, you should see the following: - -\begin{verbatim} -shortName Start End Count Units -Temperature, water 2010-10-01 2012-06-24 575 deg C -Stream flow, mean. daily 1948-01-01 2013-03-13 23814 ft3/s -Specific conductance 2010-10-01 2012-06-24 551 uS/cm @25C -Suspended sediment concentration (SSC) 1980-10-01 1991-09-30 3651 mg/l -Suspended sediment discharge 1980-10-01 1991-09-30 3652 tons/day -\end{verbatim} - -Next, follow the steps below to open this file in Excel: -\begin{enumerate} -\item Open Excel -\item Click on the File tab -\item Click on the Open option -\item Navigate to the working directory (as shown in the results of \texttt{getwd()}) -\item Next to the File name text box, change the dropdown type to All Files (*.*) -\item Double click tableData.tsv -\item A text import wizard will open up, in the first window, choose the Delimited radio button if it is not automatically picked, then click on Next. -\item In the second window, click on the Tab delimiter if it is not automatically checked, then click Finished. -\item Use the many formatting tools within Excel to customize the table -\end{enumerate} - -From Excel, it is simple to copy and paste the tables in other Microsoft\textregistered\ software. An example using one of the default Excel table formats is here. Additional formatting could be requried in Excel, for example converting u to $\mu$. - -\begin{figure}[ht!] -\centering - \resizebox{0.9\textwidth}{!}{\includegraphics{table1.png}} -\caption{A simple table produced in Microsoft\textregistered\ Excel.} -\label{overflow} -\end{figure} - -\clearpage - -%------------------------------------- -\section{Disclaimer} -%------------------------------------ -This information is preliminary and is subject to revision. It is being provided to meet the need for timely best science. The information is provided on the condition that neither the U.S. Geological Survey nor the U.S. Government may be held liable for any damages resulting from the authorized or unauthorized use of the information. - - -\end{document} diff --git a/vignettes/figure/egretEx.pdf b/vignettes/figure/egretEx.pdf deleted file mode 100644 index 87e7eaa2180bcea11e601464052ae1271f4246c3..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 45187 zcmZ_0cRbsB^gn)Ym#d1aimFvr)NUyiG1^j!qH0TPHq<7u=WSJOYK0QCM%9e1_7I_ z-qW>lwFlmMc3lN#?)=Ke5`JCF&DGh>6?p9_%;}|@B@{-vDy8?^maM2T4SC1*O(s1OEK24vwwDurp#{Yxbgv0&+ z&f|ES&W@esS*wKf$Cw+O^*^3$u3%;*=U>TFJ0sf}cfH!+oMk}CY|C|4(h91PI709{ zjwYP+jGP`Auc+9WLJ?fGzVq7tLt9590YfLd3a6NnM)F}W;bdn2bkFp7ex#3Zitx{h zZ&+_^JQdh7Jzi&-Asi1AWXJK1CnHX$Ckp=AsM90J$>GW(fpCoIJ8OD+ScS?da=G#) z`b@T;Un2<2S}~$H-1^P(R z3g?B{uB0hX#OjDyIMw43!vO_4Ee9nyW|xKNlOJUrOFX+?LG*km5)V{cpU}$6Gq<9m z`kEICowZq%bs8)=MnBQ6)b>nv(^*fxwuen|z%QX?=H*bgGDVv4+n|S(Tqpe?>3PiLQsoawj zY|t9NsF<%ll#7~MRB`04>J_$s3QCje&3s93FB2G)_-pQpqV@mzE%gwfH-+jqxbz4O z@V!AhWqGk|PAf@UP3;4DOtikDNiY43VUF!~PGp&X#5^vzy9aY2C`Y?$ZYUfFajKl> z?hxQkU*GqGr-i*U?;fQ0mg6CO>J_6=+f8+P3fo~cS2e=h(txU|q>itGx}}!+33*e5PNSCZ*XTtx}M? z3T4}kOE&yH=V63(p4X&?PsdPKrS#$xFZ$v1s^Pr)CF_4=oh}Y(MNQegt3zgRtPJT? zDjUtd^cifCPw$B+jXYGp4^yhB;ilK1-^<>w73nkFikS9*q-|x;iEVu9 z^=&`AKj9F=UUN}hkQBjyl!#-5NOi#DX_p;o=07bpH|*#`Mwi$tE=6{+SZk)lrA5~u zygJ4ejn)ROBP7!2-z(@C&==?c+oV~=DPUj5nOmCD@e-8+TYj`!Sk*E2#;H@eW+TNi zbK($OzF1R?>+|8Kss_Il``)_L z-8Jx{(FIOhGY)Nj{ijCpsAA>L^d*J!*xZ7gu3W6$TM=vOB`8~VjK$9TpJpZ5xFaEq zWEv_$nsypha<0u@TD11_z%tNRl-|nUs4Hh6LhBy_J0z9n-Yan^?T%cUz(`%xDs$|9 zq0>6)-AKj_HW-=ut=28AHEt`eEg%0iG=aXU!gU#;3txK^r*D>iZz97!b6uXV+AbLz zJZTIW{m)=ULccgVW-yI)x!{NWKe9vY%8>#WEqmI&s#eqXM4b;R-7R;)8XeM*pXLOV z+CTNY=BBQx5n8{C-FVh#W^7$RYHzMNw)wi|Rs1=?#8We4bN%qcyBG4kQXM5(7Cl_Z zGDj9>JMRPzJO5#gYCGf6;K`Bz)*oe=hbQgQgYE`>U%NQENXdOkGD5Q`>y)406zqnXBXM(=Lk-{M$z&^4;#x(bR@-@ z*6yUee);x@#OeOaZ(Q`IEx}I)cK4p7>E4_Fd3GYZ2Cc?&{61{^JNL3|x~7>NYiO-r zyKg=|{w2Ec+}`!J3kelEH*+l0Yj@M^>A#giR%48Qzq;0rDEz)GEz!T9vR&7rn7aGI z&$Y1ftl*>gJ#}lp$E31!89Nn=Ks8@u_LNBWG0nI-z<8fA=KnUPhQtUDiC#v+J?pgK zZ9&ht?JFq;a!;Rm4l>ohBf2Ng89r-O;d42}vx6(sNxhhL`Let}hX#GfTDNfwjQHN3 zEE2J?sI_Q=IzGvCpWv>_#gu3cdyY!u%4oum>$;reAvi3)q2zFJ8WQdd5Lgh>lJJ$GiO&oKX9WI^e<8lm`QnhLK9t?>lgdXa_b4XpPp=^xK$YUz|IYP z3AC8#cVYh`WKm%HQ}5${)a*WgS2S^W&V59d)^wNxF)nb?MY&s7fC$k5N12W`KTli&U;X#072q50$&tXRIxmC6Zvc*s8IB#I8mWyo~9o zcG>!fY31O4DV@}fb&yP(TtKUnXj z-KUEVsodug31t_lvX4(d^s#kgxgo`x3BWnoUA5_u$dRql)*Bh`M?!A zcvXE(R0?sP^ZK@;Qw21={ji>erWdazS7A-?9>*8s z>~dFe;kk~T*(|`>s(AMyUH;}w6aAd0Y7l*wVj+phZA9MV#xL!0Gcd{DZ0?dP-el0m zPb+5B2&7lhcd2g_N2khHe_NR)_k7q%_3Q|T_CB+och;1BV3X?7q1TnN%V?geMjW_~ zM&`2H&E_R?@O=Fp2{=wHuMN9(pg}kB7gs)MrngJ`*U{K|^;`wFM&It*$XIN8^AIni z%^mE|!ggGyA;uQ(|L73^T`Vy9^U)^{Brh*+$t_BluJ;X>ZU1^;SypM|I(+U0bmW_~ z`pn3n!BdwgcBJ^(aJWSR$6{w*3T&kO8-0DNR%jzUjuwHm$F_imgf2J`bgmr!EgO9k zefX4uFqJ>If`T8nm(c4W5^1~F)Nv=TG>e4KbDVkGYZ2(^`xckEqGUOKgt3`fmWY>?UY$x~0NS|g-s*9Be zjvJapM-Cx=!7!&NuIP&03-b~>eSC?g{)BA6CllF#>RoIV;dUPSnlgKVVwBeXJ;`p)L_Ot` zbLJmFlT^@i2;Bnnwq_Y6!vbwx_X2YOdT78?%$@3I>tOw73by@VVMbXjvJFvSs>vPO z3|AApdna2jdnj+h#Go$ntt4GZm;SIIn8f<#PbjZ|mN88Xqu-R733Yu(D<^tH9OAAL z-{(qC)a|)EnD;y!)uIlU&nnG~&i(CPmMzEpcj3NGK=7Q1LeWF_nq5D?iH+@P`{?YL z>QISbPxEdHdq`OlB>ULv4+s$DR5dgwrk*Er(hRC^Y-(p&+a}TwSPONc|{BLQRCGhKLXMs z21Nb+Tzf;KBFD<}t&OrQ_ey2aDrISeE@J*S8}KjkC{xl#n_h0r{P^(lu_aFJ=<% zQ7z^$TGICETk9{$9f5Nnph>5kuX&lQQFEI|@rG%IrK>Be3BRL+K9>a5_Ux`Y__Q5Q zoB2vgVXAU9QABY_Yp=76Kenzr*t04{@Vi}vrDI~0WR<#DZI^Zb$}bqlu`)MX!zk0R}Qf7PwEsXl?Xb3N|$EwOnF5)U;Wj8m1Izr!tDtMu(3$}pMQ=Yl5h z7&xxy=JzEW$uri`fhTuBkuq!@+-hY6L2fbW9G=Qsj=l8{x;|{~^Sj?jj)ZDOo9Rxx zR~Iug^+tO^^HE7{Q%`W5`{cwKZ%QM44TZlH18IjC9d@n7LIYK5*@LPP z_=%-d*wej2_a(0TH-aLH)NyC4%!jUK6h{Z~J|nJL!~cUK~>o_76E0c z!u>(}0aJ>xSK@vk@3aP=D{&=qhZ=%O@1L&A->{t29T=QziWTL$3|@wFUCunZQW*3T z>vPD5G3}jC-3lF?cIzYzT%uuSz&|oC5GXd)=`~Rl&Rt+0n?fRJAi&+y{4oYSj|77o zk|HEUr_}H}CLQ)mfHmh2N}1JmN!Or?15Dzj(*Xgz$lBifu&seL>X! z#L$KShHjbk4(`(vLe(cp%Z^MIlPpj{vw=QhScy71fxZxtGy1x#?QPBeYKE&7x_fSX zy)|BZn)RN1{wv3OD=Wi(Q|))QqkUJRI0St+?k`RBT!tO2QLE?G3@fwK{Oe&~a_1?O zg^Ne;SKhUeBy?|;CXpZw+F^4le$g)`%c7lpyl}BPh))Ka%Z_j@t8pxFdo70^!~7;m zenyh$WB&qDprti(9B!$BlJhDcRaocvF4b99qzojRvKNd6wI`cE(aEN6I+GPq>+^~m z^bmr4%Gwwce{b%po4gMbPez zJuIY=W^JAlH-kJ^-^lfS_|)5N?mw~E8CU7uZG+~=3RHQ5R|C;+d)dB z*mu6YPbGlP^2Z}{`?~i({V#J9Y2^KZkSX4jsgALhr_O@-o$;sTK$j98f&*2 z()AcS58{{NnHH`RHNwD{0W^-}MuSRp}u(g0`qIITICiX~C59ZM>G-F>EL>5!x=*eB{hPGwl{K=S$E+jY$!Kwvyl zpAOQF$O~qDCr{xA{wGQ_@gx3?wJJ$71L|g~?f$07n|;++$X*E?WWV9mxdek2{mlXL z8kG;J<@_QN-p`WI;JBk#?>qeiBS=ChWSghPiXo*ptr?jc90kF?)4;qGCtm5QhOz=QWl_O>N(@sS47NJB?-+`{Alk2J?OMCgmQIUvIj6k5BrvqYz$!l z#C-O@ga0hG(m56WTIO#ol2MGpoi$G#7=4C3Pk3e)&1&z3|M-&QG0&f5`iUXW_+mGR zu_S=swCN7?`-V;EK;Fyp_Xgm0W~{(|^^Kfnr@UJdW61y!YRol!?H9|1z0JB;xv71r zm(<~o*ez-f56dBm9K~Nf?w>+uaqQLzkZy$qx|J7iKG4NaXMU*>=qtUnNBXo6ezz}d z7PryfY1EnH>c0rJmI^C-F|zdUj5DuFL{YJ3*BM?qP212^+4)C6%A{6&qVd!A!M=~f z#?%^|=buyFgNpj8&TBKqV9^u^L)^m%vXK(-S5D)CnVziiiDtflQZpMM* zG#T$AGsG~AW3o)2Hkl`e9;jOY_--`jCej~fF#e&dSOq^U!jYFkLR84@XZXmX3o7_#G@BDou3JH@Ww!GN(pUcXRVbP@ESJZPu{!T1E-KraUOw``1 zZ$)c%rE<3?(&%sE>=u*zL+!*wQR(s#26YH0rorB?00R5LyIQ!fLU%(#u@Uy~of~Ga zhLJ_=N`nTx-8@R9fttFtk2NT@H*qL-C3o>v=sg8W+FJYB%l}7V<;&DbL3&kZP0<*} zi7t3$h}&1<`<=X_+q@RMZ{5`N*<6Y{7!X3H2oA5ufIS+K%#F$Y5TBO|Cr?}&Hjt62 zE6QAUY$jZa@pTW?sJ%wIv6LLyJ0m?}0jEhX98ar8-bj7;GtUK3&l``-@uxG_8wXz^ zMPLdXftr`I^+IoCFr-U8GgE!!_+=`K$#Bm989s(h?I#Pm`^jUcWWWSSb8cTyz|@Q| zSdYmXoB9c_y*Kb=XH;JfBcO=mX~QKu4CeSmdg>JfyEipJ9o+e__{!jj2J`}S%cJcF zohOX2CAPVTsB1BZ!sSWVbAC@3nsE+-`qE$;W=su#yDDjx{7rvO2FQy$)&eW79ljN- z4m+aVjeYDeBoj3x9&Ot;IENh0D5lNi#5giow%4SHt39O z+MtuwaUyVfqSPE!WhSbEhvvr=>5kzc*&B2iIs)e~ZS~HXy=;$FAs?^QP%7)&z31%m z-aPM@2$-;*0WS#8y{UXrKJQCYaQ z&$WugTRn4&Z1KKHFCPD*o;7=4OM=4_*W9lHO!-f8%Zcz^Qr06_I^@--(*^MyEt1EZ zSdFC}Sl2Y0pm6Rq_HP$^fms}#5I<(!(dQ5ELLkM(sLb`I`!Z8UTxh9lbT;nxGClqe z^qx08c^`98uoUrLLb&)Du8cR|MC#U>5NM-nnPMZydu!G9volQ%A_PucLk>EYB%q{i z691OT&W$F&OTUEr7CB1e{zR;z7?4&FN{072{_Vv}pC^rr7>&1*H;#G0Vsv8zS^fXr+9bJ*XlC z6zi0f?{rA*Fc^Xrw@Ojp&KLY9uVEhceFn{vPn>&YviRE4^dXtZm8+8QnCiR!>^Hbyc`hupUii5iHJ0}MwGajL7o|A=#!jrX!u1BKF+wo);3&T^Ho!WE! zBTX~)`Kt#n09W|aC=`6Jv<3)E=Le-X(PdOHCi zPblC^QqD<(bhycd={8@j9+cw}h37~Z0Dp4!N~3A}Dlp?q5%HGmu4#Ry)q`ECLd9v| zRPv&bhxZGB5FI@1hqxz&R#*5OHAuJmV|pL&{2e_T8Iu3?QwCg?b=@O{Lnx1OkCqeN zCI!*UUtQQDPh?JEE>aRXx>{%t3Rrm0*@5K-R zreVPkE8?XipJ*b#6Gea``UpYnlks{T$F-{p2QQ@W-9v^ftlR@k;z}n6lcAgi5LHJu zp2gcC8ZpBA8<)KsXAdSDoaa_ofh@&Maj8m--D0c7V138gJQZdt4SScNury)S;3!Nc z23bz5(L=|V*8h-2)*u217 zIW-;*O)S1&^4kZFhU0m)5scAJ%q&%}O%)GEn}gP7_sd{9hIRT|?kGm5v_caG}OAlh3plw^dV zd8h#Muv(E61gpr3ue_7J+q0|a6lr<3HZw`6z1ep^LRMs~wxT}S&6(?c zfyMLlIl3oJTDf&c@xb;*Nd`>ks_X)PS*i6$cc`uzW><--s9zzYdngNG~_ZwIYo*WIIe(AxqzsN#Gt_rrevRblo#SnMj$d5llCWyUC?IQTf zh+x18kb6cJPfw@H*M>HB5FFww|M84$;3*E$Q&*B zk;Q{up|~&bs2t7`+-IO9bjS>${_SlFenhxDVTZH{nlRElZ->8$m9&U>za2$oq1rCZ zjJ#ZuVMz4GfWl7HfnS<&qQ9}WlNdeo-y*|2 zBTz+Aeev_od&9%)rK=c~5}`L~ChTQYz$)%pR5befw7m|9nwgufm0&$(Z;*@I`X1j( zzHj*K7ZQ0J1gty-Zu~~|#3l)zYGSlVpW3AJh%Va1jz|4s{TrrxUz67vamB8;A>Nn= zdg(@iaqea`j@5hPOU61sr&tawrDutyU+v7n8;Pk;C`dSi*k`s#o-@LakOU>)@M6su zX;U4n-Oe#LG_{}rh4VkGc2_Ih$(Mkp`!EF6a@RC| zon0^Ow;rQ+Z|+m>1RAz-Y|{F?WZ1=Wu>ReHRo4Ou*ueyh!vfZrvusSc(Oiwa9g(Up z8W~ckUqlORwjC`Tt#p-xXIPIC0z<5K;>o1r)q4puOQAYT%+-Sl zmajaokii}`zjDU?x&T7L0=rfJ%Z4mY{=NMdHc7R-=sM8?on5(&l?Dk5FP3YVhIO@- znvz>1{S@)Z?w#8E?fxqB*KeRTGw9u9W#EtGHNflFgZytl0e89F5EIVLNX>u~K{d_= z^G92ya{TW{{v>`yqrPLL)G`-!KN!Y8P4?5*)gwlu+I&ayTpIG;>sZ09oonX#{0Mhn zgdd*tyX?NvN$usoI6CjN#4f>Wc+oX_k@{h)>auwjUJb^|J=|q7Yy&X*2VDshH&oHxc26+ zg2Elo6F4jZ6Zy%)9Y?7?AB4MwmAyYj-U(IDZ#PoP)q*^^F&_fDf*9I)o;q`BuJyY6 z^)q2m`o7`Z-=kddDY^emXt7wjn=JyF6r=NX2o;TNwF^cf7%d)5fPzz7k*&z%4kC>2%?@^L5p&=3Be$_+aAk7Cr&dDB3l;AKIgGizPWJt~Cm+*2n0l?Ixq zCs1X4jG~^K&kjBzU^jc;huv<$aQk=xDeK0rp3HIAw%~8KXvR)| z)m*V99uFV?Q%qn;x$TnY($4n;X@6Vl)6`K=2{kzUVY*4NsgM1`UQ+|gAFdMWxm!|y zFN#HI;7BU~yApvCl6sviF2%h=N4|=wB|_YlNv*MQC8Au#bKkhtj{o~mo^%R}Zi*F* zA;cmhYKKC4I-R;ow^Iq?{E5GKVecn7%VQ&!U|8NIC2I8OGxzOI!d=u+BIBNeDFo}G z$>b6%tG)Pj1Of6Z5`oO=#!w38=xgtcG+(l%r%?y7n!3AzGeMP>u-Jv?Df7_TId%|Rmf;5Sooofw??2&?LlR?%fO`f3&O zhKr75T3R`KWz&t?^zL>4cOU;4wZf@cTj^1Jjkx~6VuP7**QSoecm<(y+Dq$6!xfT5 zvW~&z_bD80j1H*OQ!%SuQ)N<{!bo?I@hfg@R-^??*~y8SuH@Ep_!aJR9T-PrM!Z`Q zrSpU&1>eFh7t@t3V#Op^16F78@=iq>@MJ&4VS4Rx>#XpbGM6);q`&{l>0WrvT%E%< z1LDn5U@OtIImbeEtb}uvVo#Wu=m0?IuSD_$`puw-&E?GQKTdc!+%-rbOYY|S&uvZ&fEv`b&1l`o2MPW+HokmSiBO5Z2is* zi3aI)SVNRA7R+DSE0tR;9s%+Mg@NG7WK*dEI78x1I*V|b4S8$LqI2rK31ygfris=# zWKvo95byz%eI5a-Hgs>}1uC$LIw=m0^{px{Q?k$eXJ@V_g4xf-&%JCQNpdQXo0N>bm=eQ;M1t2}ewAt8mfupb*_LtjzHrYtf1NM#uEYvXC`yls5#l zeq8V8-SyhEsCW~vho2qMCfn3Tn;okOdgYs-pWdZz`) zj(8?+Elu0kYn{gEQXi#G>xrz%!9p8bF7K5wG2&z0=dscnMo~X9aWV5Hl_+r4S`ktE zu2&%ajS>yc@Z`w02mZ$9F}3O@yUypzQK$0Bfb=XAYs+l;*)6paVap|1d802r#N$9=Q*h5axYYwkmd zI~UHgws$aR$K>w4zn3b5^3w^kV9A+w?EhS57G-N0K5+Fz23n1x;hc>?RgPU)Vehkd z^L=GzDYxicKOtpU#`XEVRtm#gUZ(HRnJGS7bGa2grz%?PpMqGmgI8b-jQ#?;j>D5h z07jE$U#1?fsk0Pq{Qgl?4$N{QJ_FzO;N-q}4CEcz zC7ba%zaBo*8cg-h$C)-0_Lq6g%vIm>00|Z9<#P}9PZUX|OxY{zucGMC>s#O6AcImA z4@2>SW3p%as#_#vV+TI8OT^ZUYd&IEx9v8Vo{`;-w(L=D#&9k-{wai77O~^fJ5gFl zYJ%*lZ3;&(N4I^0L@6~N?rqNcl15iahDFvtbQ=Tn6CW4TUL;Jk#`gZK7oGr~p}A+I z$A4-grOb?V;_I-hfRK7$M%Ifo?!Hd@iv?d;!H-}U_PpBY!mV}jt+N~eG8&)(D#S5d z3lW3-Po;^i?2<5lydGdLPQm272p0lmvl;M+xE@nw+_^?>L~4suh#NnN z=>x^R2d7`|dn~JPI>f4Gz4vhSjwj@L8Auf@9a-bsI+%hJY24rtahk>m+Us|8#6Ide z9QWz`3D@b!xQ=SXQGDA2a{5+=r7->~n#jyc#w~N3GEWEy=g#@7HFx!tIE)R(2Dc zI=7;#p-!p5s?h8;@vQp`78mFqywdbs5*Kr}%NTEX|FBnbICi4-ONbY}rr_&rF*igo zifqj9MXGfBDU&HtaU{<>v9eG2O>rW+S$zp9{l#V3b;ejvSgHn3ld6|1}moZC}btcHiH zdn2?yrrH3tW0TC~jY<0^T(DJp&iXp}bE?Zsy->Q{ktls|6>C!6id=-7P8xNUdZ5hN z@cp9FS&u(j0zBf|<4^vYPk_=y0fV(e{Q zzYUUn2)(zTWI&(J@4R~Af2!A+n~nqZn}W0e^NZGWyGc$14gm;enZb&c+?wDwzPMLYk!|_D2TUo zWx(cM(GrV(>n6OOql%|(Vx!rJ*cAJ*+(_4 zM7FOn_El}}oD2w?uf5iPuw`>r)35PDU2TviKc_v&WZJVn`@W>=A?Csl-F>Yh^HoLNWg#_5g+>_Wl41BD}u=_j$y zQ|zI{Z}FPf-iFqQ0Had(xJ^OP z@z;9RPY2K)JeS-WkjqivaOi?`upKWp<&)42(@_DtPfsU?EbFNb&)!(OKC}G#a@FNi&JWL-Y|`-MfSE+X09QFswGfpg2ReOsoW+aslfv(vC+VGV zo#txF4oXnpxU-)=@knd@uhp2oA+q(}Q=E@+1q~;GV~2}Wj(T_8%-Dm)j^qo~lqGLO zX+0O)p!b)Tbs2`~Q~S2pQGGvy6uwkw7qiJPx1(b9SJ_qarT6ky|H(Q3_m5K+3b`8p zZs)rWV`pLl{0st>JNLmZ+T~hqGTk-T7v4HE_cuH<#@?)ma%HbW_x`)pev;^G(NX)V~6-&&EIv~ zTvV`;JH_np-MZ_7HY@Y09)0ATb^60c2+=LepJdml#G($4jA3Ixir-QyTj}uMnhfjt zXb_6gBtFPgl4anX3H?!L%UJF?$u_1`i2O`QS_7(klLn|Sr_MxowV;c@83+EVu- za&69_Og~oCilbcW{opD)Uz&92*?rU`qyjIjW>1af$ke`(wt1O!?v?CosR!YU^(7iZ z-8RerZcGJYfivjT7uLw5uH7O_s|D{5*s0&z+h)|TCR|#w;D2vO_1~ay;$zwGtG&gh zbyZf0X(qhM4DZSlI{7n{WdFXV^--gL#>>f`u>zJXbFiIWo_0F#17@jWuH|=4Njp1v z`Vp8fn0dk+TW{r*>RMs>#O^GJBiQFe33J-%Ayc{I)d~K1tkgz|Yqp916HZdZ$OO9IFt< zj5rfeaaJAIsEIf0*iyq?oRc3}wlSXmD0eRHU%%y?Q#SHBS3Wc8V!UpA~RL{0iGSY%c4f~64`dvc(T zS&(gfAH5$w_n{fS_?eFVrD-I;=DBv1{8Ov@k!Q$8im#Qt_!_%c3|(0x)2V3%WyQ1u zzr+m=HKm_s?H-Al8h3ea?Wrml550vBb6o;A`r7nuxVS^LPC+r6rWxU>7zkVE60;14 zR(a9<3L4_W3`PGft~Q5geia|`|FOqy;De9A*AgIwHKI2@F!wk<!#g8C z`)-NUdpL|aYlYe~=y;}HFI+qPG8-Mj;@U8y$&K{CBKiCIUIF`C8A{pT84llm?-P&3 zqYH{yV!!qsVGe&#Re}PKp3Fvy#yN9qg}%hGvaFuoju4*d2bmU6B*OlxT8;RS{pNnI zeoj{ZyRYga=~aidK0{zuD@Vj3Lfl|k>qUXkE_cwIwwNEB8=CJxY&6!b;cA8cxDFYC zAgQ(&HJrPr_&rO-_eXlxw(@4aWx&4m)z9j8azxN4J#J50&o;lM zI{koteH!wJAd3?As;VzJJ)u7(1d!2vsp7q<8MlyN5lrxQ<03A!9_x^ORdW0&S;$_! z+_F(s?x@zo$aEvPQNI1I1^M9IQpo`F;BuI%iInS=MX8-z$LYuU%}V~ToydT^pd(?g z^yriHm)r{0cjgBl`q$+15{QcB0Yg&9{IYxK$v%Y~EA3aW6Vq8_%GZS;N~$)SrRS)(<1ze6@_mxzml0 z!oMFoQ49P~yPREFz(8EspWFQ?YeAj?O2FZr08d~sw(_g&;Ze@Z1F`9uWQHX@cA0XI zWi;LzQc3Sks~7PJu3PFj$7gd>udFJY=b>9f6SKPh$I{4Wkd8~g)LITDOovSME-rin z?@}*44C$4wK^|beZLC>jYU?0ToaU+BfO1ectf@pb^m~DQ^yD7~GGF9{hoin9xfdiR z!ozaf#3cBkIwrPG*)HvCa~Ls~>`S|%>u_?{X}_ZFU6cFs-R9B<(>6mQUL$J_6cQ40 z!IxiRp)EY{<^(GP7k_}Wcz50H$cKJ39?egqB4}D-yNNwD()`ef;>VkXrExc^>VCI@ z<%6E`=uzQ};k)z8X=U+w@|taVt4jXAmQ z{pM{{AbHlDWPf-;B5`jp@18?drni1sX7ogw8c9k4YMweH+6Ve-qH6g3OIE2|{s#)R z+kMESxbX^u^iWELPhCt)%&2D`EnVc$_SgZ<%Fds!f-?$r^DK*McE1h^FYew8k)enN zDEO7&0D70aW2@dCG$Xtry~c;4ADUq9&J`-ji0!-DtU6HwwUkxCe_XG83^di9e5x8f zqZJ`;@x;A%ZcHX6HuO$ng%($w`onU@IbQAtYTQSdtOL?f?iubgrwz2~Y8-_?&d;w3 zp8Sp|ksR19nKk;g=PiYGyuJW+}Vh`iJ%VJ|?DV`Km zpGy(g*w3+ULy|=4&UQ%YGc!3Q-&@5ljV7?egxf-B1<`|y4aYen|3EemjVcK(f8?S) zl~;s^-_f!Hjb3=~@|*K^;FXYAH$c3`dOlpO>%-U^!)H2PEn>YcTP)ZDEt9>c1;G?5 z%NQt5*s3dgrL~WP9%~qg+p1iyedC$iXXh>#TVT7YOR0O2FUw8li8miJhE@U*;V?0 zss;_pc6*iN{cVx=#-KS`s8*J~EP!sy(VYDJL{d*IgzdLlue-dSv0Au!d)?|6RYe zrAgm^l@l(}pEL6G?qF`ckN^8b_xLfUnV$+@2_cKFk^^B~_o#i{gq-M&5(JPpS zJupIWn%u+M->`|$-1)RU{W{j&@13tPv(Zn7!rrUgW;}BqXeT=kgTDRMELZ6|@m5zd z%B_Cstx2m-oXn(aVa5>i|jQreHP6@jaRFd@%N`L66_`h*1 z81L7Y@C5?1Rimr{w6&rA(nl6_!&j(Lo-++8Hx*k|^BlZz zzToj|?OMw~i{3Mf_ZiH$@L%j3v&Vl^YXJWTy;pP%jV${lS0?U}(|^fJ zpL3z!F|6vPG};lU>rA|vhLS~CO@8w^_Ue-N-Uyx9ok1q*$E`b5wn6YF0ZJb^&+6H7 zi*?>qEzpU$&qSr2)pDan7pihDZ~2$hi^Bn5yeS@60)Iac`&rUB%iOqDoE1~R?=`G3 zlY4&tLqz)nDGT$MTtlb|pXIQK*Fe2+8RbxJMx~ysS`VKc^)Oa0TZ*l^WrLPpjtGsq zgY`Slgy@{Y-TcR%ARf6O(jCx#?H6(T9TAD|`PqBtbl~5o0&zL*-SiO?CXHS4Li+%6 z+YQUPOXM#>?d{rvW4G%0CjvnaDFo#(GtG2?^wrY_P+Dh^1U*{(MG}*Q$cW?ad!C%( zopV0lD)J-)oYiRU%b23O9lITYLfp^Za`0$rG1{Shtn}YNjWxEz`6;4xXsml#&^TP0 z4Plf}MdXsPZoYmuexgtp=(d?;ENj&!SDdBv%_ZeDC5S-SU)EJ(Mq?DYEvY~3k0gkY zo%QKS1N&x%Ph&*LGea|mFIxdIkO;(0eLWdV`~-wHiG53A<;%HXS*cfFD{c!dNKV#1c7KG-L}8=O7LgIKRrR9@=s5R0)`GhB2lopY*r z#}3MR>z3CsXm<#->J)J3xfh54vIE8ZvOB*{znkdT*u$uvr(YGOajsjntK4d%k?gQJ z6bn{hZM^M)_*rw2^~wL;UpI`fAw7+`azySaF{yb!D43ZjI#(;MHo7|pYis@oSb)1A z`XBb(p>p}{%K*XQ(+&RF3ISaS+`U}?CsLCreesu29J!3XR zd_rLkm3yGj`AXv;!CJw9+CMeT(SdC{Q&wcVqCnLO&+i2DH#Zz2!(IBo#3j$sOXjxQ5@E(aavtp{pd{n(pw1rfjKRxQm7ayR@h zvzybO{_8SgTvB9-5?-73KLYJ@!kFaUv)?*sRHBi&ZYKkIjy1PIrHs_--4f+5kh*8U z_Ob^5yLrx5U0W<+LR>l!{Ut5C>w-sL0`HpbMbHx?p#OJfY2GNAou)Rco31u{xp%pw zkW%>{6<@TY<Qta(T*xSpna7nlSX`a*5nc+l9M*Qhcs?_xydkH;h z07%ok^~MFs>N>Kq5P{KjNOAHG@!yqr{f3!MTS*JA55|KNxKh}krTC86nhZZ5%(A;M z?Ni8%pR2JO(eI=ZZ)04E-?Nx8Q{XKyyxz9DcK=%xV4PPR*4T4IgaZ(jUB*9q? zxcv6;4JTA4vMQEg#Ush4;wq(0P9(8A3jUHJa-&52@61*T4wx|uq&=z_KYTyv5D%d(f|cl~Fv;ro#s@LEJj+0XT4-hGAf0uaBop_`%i>$efE}(W3KyCj(RM z4@uRZ@AjI$8IUnzFLDc=m+=((KXknZIGb(wHvV>Mt7s{zR_&^h(%MCpUOI zc?7Nzy&thtpen}(T&`ZnO@r2`R`<@(0j}|T%o%WG=+np5_{H;MYY+jJMlZI^ ziJp%q)N}(tP5VqiR4CNQzrAACZzA8dy#CC!@c^1_hMw0gt9Omrwth7l6p6F1OD5#1lzUeZ<^+NDl?KF9gg(tk7&~#tM zfvhtf(~u|Sw*;(LH+Bj3li$8QIqWz>VBNmbx;DTo!dS@BSHSoAmA^{n%jlr1i@}^O zwDTx0N~s-MKfjj&F2s;f97h}^4@UZi9|w;iO+PLM7rw3 zCg-#BvFuK|uRdm?XzO2%@zQoqYl6?bR+E~Ff1loceGRr9=dnaOSc zBOC&fA_S~_n<7lFcF6Bzri}nlF-qY;ck4m&RV&*iU$Q#{^=M)=;jWoafr@4#CH5OT zFqUq6aHArAO-KjxIc^j#O{g0BGqU>c#%K`obsN63Xlzq28lR^`U5jV+XDskpqOF}d zf3}?d?I+?8<3@dyt3hQ=3F3Ow@pke+nnj2QwzWTBb-9;GcFxAdQ%Iqu|5M`42V}p9 z>YvaUJ;qns##b4EK_#gV9W{I2W&@dcDdS`OV9%|{@ab2%Jvg}8{uX`0>)oWA&XPZ9 zp=C*LCfm)P1Jmpuv}W-GzQj+J7A(*&T~F!IAXha!tUU9DYuVV!XBI9MR+jY`8R&Wg za(At*T}u$_*!m~+0z4ED)k$KUrnJGW9^-jv7V6qbLy_tf7a$LffaRHffxU=;7GcfSi0=Yf84adzK^-|dYb$S|8{7_7LdY~ za`lYg$Mqn@fF{6y6l3=M4;VJ#xCk@#JDsn>u|70$&mXt*Y)0vwb>0$h zXzG?x*SOZB7x*7Qv1p;>;c=vty5J}+T4D>m#WYFq%nE7zaVA zWtu$881zP0uLJ0dWe8qz8Bpt8aI80BhkEAdDylTpDIk8E|AXTpL*cSlvpyzLsS>|O z{!@J&P58K#k_iam=GTppYHFUtJ^=8V(&0|JyM6s19bDP`1vyT)g$XcVS0Ds*=K@`F zQ2Vc_&yzzaM|F6j>nA13%R`k)Dh+^Q+#SqU8YKt@EE1f~Byh6N97*L*mu0K&Y~}5h zOrI?;^}Y*LjC2%--vb5zp0bS$2g#C5&E|%``0|gX3cDVCsAQzeFPOiO@JTf5O#Z!I z@a!P|574`Q+`kpbh+h9%)p{o*_iM8b@QKyW`d{dps_Yl{^z%Qsaua&Xy1W2DqtAam zUkWz^&}ag`OoW~450fRmAhE2uy>|&8!3_xt2%p3E?m#liJodqu1$)E0^K2KB)7|-( z^2k6Ir3_sHeFsn~14EXW@Av4E1LJL5j?4RM(l-qWd6f%{Rs}+>di%!kqJ5p3F!^34 zpv9}o;_HCJG~`}?8`I)Mt-hG;a82kvoAHXC}ArmEFwYLZL z13-h_y#57&mn;D8ZEyT?WZ4+;@KsA2t;}`^ujY_?9nA*a4(p$GbgLyT=?spdTNa0X zoGtk@Krt)@wZX&92%@))F7@`=f zIEn!u1N0plr?twJ%A9^NG9VIjyI>eRYaxSa`W7*Sh2&-0AbeeQ^|-0FJrOsIA=fYf z5r_W7`X>24b*WSF#Gwf$C2fXl-MvMfM@roT=v;Cx{lPC(_Q6(X@+P_9PlG3*=CQZg zQdu_Si!k#D&OAtBw^ER4*I0S^@Brbmr*j2daQIP~f0?3(Bn-w#xT81x*ke2+I=p++K}|u@}Gov zj?B}|C@lH78)fRoHx`fxnrb_EwH2wvgH-QgRAa~)06Q)wn`ofCf<;hn%H}OU5@ym!{BULrK5H5zElKRon)lft4bB9Bz z_WC>e)a>oQ1nXUAv5r4W>XbPvvr&)ccXD~h{vYw%KT2Zgou=TJnvk>**qj|(Li%Kq zj20aaq5tEntt^BM5Yhr^Dfp_|)YC?QJ$&2q9r`adVL?b_eaN`x4uAsG8*pQFbO%ib-qnW64)?Q0r~ zDA7U1zJB&h(cUu-RI1JBE^%0X_1}mUzLpqp_#=7myqyznuiDFJ4&jLEYUsmL(NQAR zb3IdH$B?vF!F*~7vPW3G>Gf)T_?xpR^Knvq!O!`DN9KX)4D980{lf9+{IKa3^>2E> z&S{2`!nLL>X|d!206PR_!6@)lO(ZTvKe)Gv!NlZ?VFR0sq~{fxxOU~j zm|u7%NZNHk4`JnS)`InD02odTwZ%qWFM?eCw?^IX>wRJUO{`*sR*GxMA$>T<`1S4E ze%w)p6#44F@f`nC*v}SP%az8_AdVBBg?ac6ADuU-w7^G!(x-2a@jLDheebeH5H_+* zC%^0nB(VO`;{nXht-_pt3IMpzjWiBXh^?2>B-F%DD z899zSvbC*;?5nUvC1TN|z0J0q$>Ak`rj%Fx#}HSsB1vhQc~ zpb363z?EUR=u70U*mI5qLYM_VrrfqOVoQc8;kCPr+8G1#^wfN^{jhXJcm*|bCU(mf zLMv*whAE~|5u(WWuj;pdc68GNiA^E2i}HMCjX}qaxBF2af-g{*2sbHCq-1P|WK)|X>8Izh+fH`(zp~7HX^FXpV{U}R{P0d%%L|DrA+ zUz;j@xcTdPW5cylnz0)4xF7F{H99@3%h?}Pq%BRyNTI84>b1~UUi#2^Oz2-)|7nSB z&c*#^Dakg!Z^OF+Yl4do2ZE~hQn*rlUqWCDU_v&^;L=a44f+2hQvGL%6#TYpp62}e z4T_sW%<5mQF!%F%k_Vos$YAei_EYg7b3&mMZ9mQ{LXu2%;2zl2|3KI5=J-lViFJ9=kph0Wm1VViVv&s?##DhU6If!skVcy()PGN=xHA7DuQm62;M*IW2rX3D6(S>ww$l$ka#(SnyC`S4kxIn)?3s2iUVC)HLk6!&rRvH>4)Xw&vLk{z(ny<-Di2SMLY2KKb4r_^Alsa+GDa{AXYkxnt3Qq`yS_nd{;B zccbQ;qgAP5cq1R{))<$=iFQEqW_h|*J}tNKulTnH6Vw_xNsl6?ef2Lh(MLvqH_=&> zc+En1OD%;kdCxNnxQ3*KMi;JL&n>#w!0(UykA!|ym*_<0>YU-;`5h!ytV!KIQJv=@ zftR%03TzAkN{MsJRaMl^Ma7zpcCc1}0+5hG>;hurN(++D3`&v`lW1#<-dE{8RL+c6 zK#Ul*NYCRar6~O}^f`Dts51I`Z|l7Rj5KYRp_IU4CtUjU)F`bLXOVc=MBY6y$}_aT zQ<*97M+jZwS<|-FRIxTr%(5$y{Ua~J3{ArbK+E>z+c(r^)ge-d((3o1sjvO#^?~e_ zoFDn{L3e)-V}B1DKuF4tBxL-9_3=K%i;E}CQt*53E7@G9bE(2vuW&&Xpn1wg%eI(; z@+VUH6ZRP`3`O%0cz6}tYM$@ChXjYSK%@P17z*q?!%ycGuw=WO$0fPAzBZxezb-p# z_uq9em1Xfo593GfK(J`9NhwR+v44gUu~2A$IQ7xjC#@CqhQr9Hog8*C58xaGIB=?d zBL=UOnq?W!^lm$M64K3Ptfuv4V^S6X*Gf!zoP6(MHxCZ;@s4gpT@(^7qPLI}Tf;T* zY50Qf>t4V$Y&*RyjZ&W^rYAfPS|yA(ZI%L_mM`nR?NjH%n@I`{!1%i6K%+`un!r?;g>w^j-*!O>~T5pBA4 z8$UBo=hC2wAys{OiRtqL#Qz9+EvAoJO+ufF$~;o%pY@Xax1XOH6_ihVEOfO(s#(~CkO!kPY%9fY@lZIvsl}l4OMhI$5zWwEIt)RD_Xlac;j_YcGwz<60 zXSlZrp}mRb#U2-~ac3I;N5)&2Q9LTB2@xS(B9?q*pXh8$QbZ-9cl0@k_3h}goaZ~8 zC8==I^`dkq&&lKU=pA0`KbkkF{dfO^Y}}t>`#{>O4Tw_hZOYyEB*$*?3~#O{MaWi+a|4Oc*tu95CE{)P z-bW~q=k5G$*qlP1gqh-pku#g(8n1?g2cl>~o-qM3 z7b9z+_p@led!t-7G4w2~bvyH%CCYYTf1I6E*K5*wXlnVxSQn;_^`9YhV#;z_sOi!w z@@N_04DqaRpxY2Iep@}GMz^h!7n=Y|zJYWy@`uPC0_WZ~1^v+T+ebwGaV#HW8^mv%*o%~1)lyM$oktlylTamTs z+sZ>*ry**)A1Q$ri4bkU+`yINu}6e6fCTg^IQueMT_5>t)#W+iW)&a7t#C8?;pXkK zr##2P_$1bX9+IToS>LAE2-lg}T&uXYFNjyY>i8B>L{@_1RyLfGhwz-*YfuOg zDpa4W3e$7yf5B0->jjc&7C!U*eVg4|EP-{IxeRZLKt)J0ymV;dWUktu$-h?>0-zVn z!_!a`6`g?LA6-Ia3D#3Rq=rO*f%((?45YA$s9e{w0ihQWJ+e+u+kRIm3xD_+*J#|F zqTbFXC25r@AV~WAz6|M)?b{!dOG+YaYvQf*4R*hK2EY1^3t#ImRx%3c=<39}zSOYO zCh-8ZPuDSyHcq&Kg|c1MpZdn}S$zW;@}?DV9l+?bv93VW%d1XDBtG7=@$e4C*G>YC zapS4H=ubNcq1#s>@XdXte-&?t>U*vjQZ+Dn*Hh3<;?oyboJ+%6Hz2Vd^I8v!v{f`3 z+z*PJKVsi|Y?X7Z>$roB<7A7g&O%l}qk|4E!c`o{S}D)49Mtn_uB0-1x|4%kAPCaOcZ8dr34 z?r&X?;M(4OnYE+;jde{%gsmDk1ijz4-*;Y7ba-A|4AO!kWYxE9U^&37sd$R^9#R9^weNbvHMar6C)A1rfZByFYgv{COh2aZ-nc`EFNf7NBv}82Mc7TNtV}f? z!CtQJ42LrxH4h%av_BOlr@T}o z`QLL7w5J4t^IY7etxR^3u1M%ZgoNKa3f4ToW$qsB+X_mYDE^X^SL!A3$#VX0#KS(% z$!B%az{m<~G1on#+>&b>f4EXd1ULQ&GsP@K%9-c0Ww=gMf;n)K&o~%f<5`*|t5yGE zkO~1ZITqc2DR`hltvD9HXVi&&{7sj=gTI+vrKs;0@1=3KbW+zBs1L9d^aD>J`aFq( zGH7B;eT9Dwk_Av(0R>rUp+N>0amhwoNIt>883Lzix2VTd|2ZRztltKMcnH&sWO2F`7{Zpa& z(=k<`Y+WGKuWwDMG1k8?i^I>m>dXQSRpeWagglqZ5UV>@jH-fu1rXA_YkNIUsWe#R ztc~OR;SZLN6}6I9Avz}ZNeR${k(s=EBN9;|Nn3&2K4->oj|NT&9$eMfYhVkHnoVG? zr5;gF$O8d6WPHlAgn7~J)9))6-m+W`D^bKA7Ju6vE` ztm?4*o3MS8kgJ_U9X>P&f+-D>bJ0yx)(s3w}(T-9v?s~#|du)kx@ z`oM;Va6`^iQ1qeKi+yAfs(&%m|JKINa2M8Nqu{tMc?U+$0 zzL$wfmWb1=E1n%ubQvJp1HgYbKUx1UZQx1|n|{g3cihwpiLLNN77(^qKY$yEL!93z z+kZlaMef$7S0_>>c*LtBpf3SJ_s=u*4C1=+tm2UW&ZG%T_##`QBpUmbWB9QPrMPi9 zTO9?|>^kNACr6Gmk;Sl_vu;+4fx}Y})|Ccmr2JzX53FeTm=svs50=3KQLpPGGiY0X zsfZ6Bmx$o}G>gJ7wZ$Yz?pz+` ztN**I68wez3*oHYyc2Ua^9L+}ta~pHb3>0=Ch z0j4a~=nTmH_((ule2c~m)&O?znE$y;1fu%!VY*9DV75?4pw->=ZXxE3z&=Cq7b*=_ z9`i0eC?Z5_*pEIa*5?hy0bdWB$7xl4*nxyt-|-n*T4K=L-wl7*CsE2lbMma%WH(+2 zpm+H4Vz`3y%D^?B4qnWr#a*yvRs}UQ@EHBcTmj45vktOtK`j(uc6^w2$Mfbwn&zRF zI3hcJ-|JPgb08lwCy#imovB)n4i0$?^l7jW0aG+~3_V~r0+f3tjH)V=agNkgnVr;H z6{E)aK&V>`jdM(Uz)`iMvsZxglb9nzZ@^g0b?;)tHR7B5&2K)s8;h z%IjeRYC@K}&Y>7gYo?Y(7z!|7dE6k@=m+$M-C}25D!h>vdB;XnZ_nv1-$Z4Q?}s&I4jc(|K7<7JFA5#L#=~{8bQ>)TQa}B|WHKzp!P9P#>tDkVAoAxsAOYLwUk%L7<0~%{p*BV{vw9$}L<+zQ zP<8WB)6doGf+Pa~9Gey#o)Xt>Q+OI81;|9bk(f`nKX0V}J(OkBXWbIlw|*PMEp#hx z4H;C-6oJ^lWqN>U|CUM~jj<-Y{bBj#)!!Gcy}*xmsS(EAmm!AaNigmkNn@|8ZGNnL zBh{=#XEVLENc~VOI1e#8hQy?41f?PADjF8#bW?Y0ssc(Meb6Ukz=61Rx_~T{{oB0; z8dqWa(U#^zi-Q=qH3x!gbbR{Ji9NP|Gj(9fN!WeyO23tnboI~V)7PldI`ObMlQF*G zJDOJN+4p0$d+z^a>M>4l8^$pTAF&k{*AG5ij0L+w&GN-e`;5fBEsyO9IDsbgT>ZE) zW@u*)({qAvNw@Z!q#TzdXEl#od@l6cH{PC#@P-nR4fF%XBV=#=26wxLVA`>%iYov7 zyZI=g245!2X%&zhYLlwyA`246|Ny5$j& z#>BrkF>H_!zpK(@sOq!UHdItcGiG^Am_&_rq^4UghK z(y-;V(>FMi2VPH0!>fiCidJL8ZS>9fW^(PreOz^qu@wQuwuoH!%qHvi;|V4tKKq#z z$>U7Mm5qX*7+u@qlAK|7z3_COHHVOG`#vG}{YPUH4RZ4tKI5fR0Y0Qs_daB$!!($( z5Hk4D51QG#SG7ufX|%QlhFv~NkG4K(sx0#G2r#yYT}OJ+>l^5%Zg*Kw8k$+zVN(v< znu}4z$3D3tsqQeJ{d_b^ekjgPtKQ@y|FplW{qd&9=K%ksSwcQL&VQ@5M*eX5cLV#3 zu%^u84IF#(VJlYSL{4_@_ixk`yX>6oZ(Q%`bS8JQ&9G&2#OF*lnD1`D>Be+Gz|l&C z#_2&UksY-^yV+OTe6+Q>Np^$3iY#fQ0U$Z}tp-??1obj^=#Ls>l-SZBiSN({i}lyA4duNX#NLLO+0V*=Jz0{3 ze_MLEGcMN4Z%&ldK}07q&ri7-_0UCKz?68 zZd-ca<76ulmbN-qW25Rg&vuf1dGRVe|M+|pg=5P8^}&{zDT$I>jyseq5+u+!+&kFM zbo|lfqxgu`BHX@k5hIpWgsya>u|BCEMkzfA~l&dAd2F zey{g;#?r??S(Zi2_Mvx2`mM#`XQ`W8xtDXB_q#q7%iz8pMw^SnFHmu+d8W2nx%PXI zTYbrlm3{%wBp!`#EZf_^7_Y?E2Oaxijd7O$cw$0|)fz_xb!zruXhwV54(5cDTf)=c&wgeNntrAV?c z+9MwoPY|Zmb~<;8ICl1M@5ZIt%(BEXTkzkl)ouNT^Tp zuGX0GO3CMXQr2<3H)~2zp=iWVz8$0o%eb!swXWUUT(cmz5{hqW(^>DiJs7`-6 z@%U#jVj8s59Um}L2cCTF=t8~6TUsEo__F^TZv6JyKMj@Ka#b%)Z!$a(IfBo>swh!D zBp1I8%CG$HmH8UbrW)LTHDED+EWbEJk)g(=`Hap`)Vk<&8ZBi;xG z-6@|R55pLJiMcnb@*T$dd;s~2Gl)@K>bF!)5c$pMi^t@g^h8_WGU9d_$NA28DVOL< z61(jNQ;Ux4h4piD`|Dw3)&|L_I~Y zS>-Pr%#~S6KQum;{zieL3t-nLUnSU|TC_a8OP{c&=(ZE<37niK78K-Iim1gmz|sVz(p_m;6I1GcUluh?Mz|^w#*|_qQV% zeM!VO``ESO%w7eXMdtYuA$(+$-d4Ydm#GG1{Ya_8Ye3>~z;~MxlYvOC`&t*O;b{A; zK5u%AK8^kF%5icjrBnXjU1XSk)P>`mY0Iwy_R39cL020`Wc$Ym{{ERo9l#9$L=DWU z#1=DfV;Tok)1yen2gvn0tJRZgV4}hV(#>q9af8MNGyIpv_#WP{B;=OhImyN=SKCLM zM&h5~XCf}!yj{JRTdd(w%5g+3Hb;ETMNm2%uU~)|)J#Scm3tq?$_@Xu;#+a+=YdcD z>z@XnNvj5n6QeOyoRCa4>(PDI_x|~pUP+>UkD|tMRhpfEaAFg7JB@W5z98_>;@wG; zi`KOz@5+EoMSIU{GPjN7liQibCZ70QbpQpDL;6u3HBMplcZspHoH5--B`HB zc*Vh@f&1Fq5UR>?4Rf_jJj>z9MZ~j+iV&Ycf1^YIrED7`vMD+YzsB2w&Mj|CdXtPR z14^qBhcSqZ<1Rwcq)#2Iln)3ySV0#3_i*aWfRi|^v2Lj8)BGU#(=IWDHKA@S``9~d zVd9x=I1UMCjG6Q(>eG8koS4p%8QYj20ssveF=~!O-ibPKQ9Lj-5e)O+uG5ib_{Imk z($W`=pTfZvWIsytWp!c=8qgIvb~ z$SikP%im}ZVRJg`qjDDD9Bv-a5ruCZ*?YI+N>ZDwPmTTV)o%Um^ZjAh9tNB#Gu-5+ z77i!o{$6nxEXMxypD63v?NYDT?a@+^Xv&G@eYUK07+(!slWTmlKfdyL#vZE8e?e*E zzO#)HB@Y7;Vfr=Lo*NB}FLUyJqCC&wJ<5g9Azw!M6> zHc_VUJ`h_@oGRr%kV33sECkBIle-vp1c~COe~Kq{x{u5)5-#I7452K(deYyWz^Pju z_i;yyc?fKuU>r3Z7Ek-~`?Ebm-K=aOD1wW9G*)$~Gr@^gI$?}3gM<)d7${G~vwt~C zTq7zSl8J1~tP!KlX3;Z9H6jE~gyeY$e$=m-1Y278FbZQlm)yh?(>~F#iyBvm8?avo=e@3DDAX6d_MUad>~Bv`J{A*zD7uFlG#Ay!}9s|u0WENCvfw= zu&>9H0S@uN6-5h}AsaqxUHfGzwI9Vn36A)&a zy1rs1q@qrSR05XO1D1n4?mc>(`;(B$a`}YX<`*&Udg-T5*0U=}%&lv>g#qU_y{<`A z_2I8fTp)2)GI|rWU43jS8AVp%M?8EzFqgJ{&Sks^MuvfF=6+Pl;#4RK{|uy)H`2Hd z?n^+uGcN+BHiEQWR+%Z20bcVIMq*vV?TVK?uX#Z*pbbRG_hTUZ{TPyayXOjg=rj_) z#B;9cb)1k@560w!G3{VPybxVi!X|a_V=LqOCNp4o4L<uNw&p>vl+PzD0hiZ)t|F65_Q#Id^qoN@F%z8Vr^p zU#eNs2kH!!1pDiH8I}(#PCJQSN$xVunGy4cOnVV(2;{#1BRH4?A&Sn>?tYE~xt2ot zigPM-vx$rG_l-5q=RQowHk$P{nMKYZ6^IaLA_QrsO%J9tkJyp?O6nAuS zb#%#=VA`E<(PCJasC#E8h0f3`tdr1RddarKOGD9Fo;&*ub3f>&J zt;(A*f;H+9_%N4~z!wt>d}+6jGM1YrSlXc8y|iKIJ?Et+NRSxX*zbtvbJ^-F0ltI*~tX7#bT((bbg>=T%pC7~U!$xHS(PJ6@G<@aO%C1zvCGMy(He z*EUuE|9*OP2w>x5J3Gyy*Ajx)5?UvP^v^%*pHz1a6=LKrhcW=0RgL1hb#BFyr-hsN zM6xu^4#%&N>}!J_AlMbCNBQ={(l7GSPz+tcP}-}=(x z`tkbDCq?IsxiL*&I?mR$UCuhP)5vhe~p@A?&)>I!9LT2K1o@LHo>^Jnxx z@!0|s%)y^P@=?N|?gmKpM za=KlzO10YiFyIlo7uDC_hg}7JxpMaVCk<Ajrp_g01#UU zO1dStMwu@?s;JN1)rUJfG8FGn^ZG zC5bkfLA!eJExm5VK8HFnro)Lf`T7@Um@;Cy$%$vM`@s_KGu?NOlZl+C7 zTC=mrYxbg-)wVEdz9s5n<1oqaeZK`lR;waOMt8%I!D_mG@PUU~9jW>7L-R;oak{*| zA3IXkkAYbl?r+xc^W+)!(~gKQ>SlF*3@cLFPJ`z&n9J_-;~%6C+Y#UGn(P@vd{xFk z;+>#8(c>8~uz=vfE5O#DIMS6kQm#*?JS02jypKkUrhz%9lw4{f6l)`17+6YLFC3S1 ztSdyE*n1VFcob#xeg{r3TRt}&baMtNNeO04i)p=w2=xhn5BX$DrlnZFgddv}_33)A z`l+=DyLr5_C%0rud$aHXw2jQ=ZRoZ(d&p4ulfPf#6=SMUD>-D(pVe}D{bjX3^0~hV z2Xm1mb5T@oc{Hp@8U^7%L7qc#cF7V(CB6nBF zsx+@GLFTgD%1YT-eA(F9EA3Qu1HR{=9u2`#hGBP>L1Qb9yNPNCV9sM6spED7l4bzE zaX@myOIP%b!n^N@kHfbISSj1cboxDlx?gYTa?t5=$P_8?76mD_dlxAnP{zmj6Wbdh&1^RpBzD)_mB#}miAEQ2$C|GL=m8HLNfQ9Uz0C&>a?8hhuQ2VDmIGJmG&Zl zca0DCw5U7)Q+5iJdhDk4*f9n0Y;`|r6qOrxj0ZFRuPvZL*o#z ziAEX!;+En3edk3Mn(c`s4~JTqWLnG( z_3yeB4rE>^ru4;OW*?)|660VNgQlsCyv7Q~QFI6hmyViTAGn1ytWQJsdU%*5o8>vZsN*D`*kBl``*7@0)HMcQS< zmf0fc@O#%fyXWsT*HSBjUWUI4_Y{_{sWPgSNmxcG)te1YBVTxYs(_h$phc&Vsvbr4 zG9669E+VV`CXWNkj&hY+c6soi3X64!1vmSoQ2V4%h}~~sC1n^Nk47y)49JvdB97r) zMWTWyc<0A6#U6h&t=H#k=~~X7J*u8P&pmqwUdlI52-rN?PV^ zyMl;r-@dUxJA{6#iDA)42<9-ljk4>^htKZ@_#7ogi0pxhUT*w$m%(h~=^ z#Zo(bso-Q07Hg7H(fU_4Urh5YRt8~O2H_jj@Civup-=r;h{fJ`Qm5Jb5x?{>1S#4ZC*fK@-td z$b1ph-w*5Tr%9R-tBH>_YHogVbjkhG+Ln>|(8fb0C~p{h#Bd56Z+?(&*BtTWX8c*u zH@Q`8Z@5VX)lkBEx>Ro}Ry%*Jlxx@jWpM%PIs9VvxTMk!C!!d6y*x6EuX@wl>dJhg zP}JwrR>yJpId~bRW=ZN35`M`^Rb(#NvYgM#N~7Og12I^H{cRG|WEQ^hV1OXkA?&vE zyrcD^5BkP94fm?XKQoP?`pca8%OnlFx!t$HTjXyVv+6ln5^9z*1=#j&>KLxlr>KEHs+ zgJc*#<5NgG?;h`Y91%}P?B|*iQ-MaD2BmO%z_yx+5j6o2jc(?)8vt@ z$2%l&;n&smgh2t0-$@8rN0$Q9OZ9i`bS+fjeH4YqixM4n=F&A?mspcXK5a5^dIm`V z&rbEMWZI4*3+em&-AgYJliV83DwIwV5guy5YLO1&mxj^)dV_;r@KxD$axwZ$a)fDd z!?fI*b6zxa|NZ1C?{_ZOzo>Q3UP~0??ICkbyrGzvX5mY*@8Q_HMx!7Q?EXgk)x~5~ zbmj_#;_nl10;BI&cZXIoRg<7RIy$zi`G#TRZL1~lPJzC6xFQIj?eJp|eAgQ}dC1bF zW|$GF%!|6cKw-z%uzg}LqOHLL(s!295uJang3neL&R6BsfaIm!Z(n>J{l=_NX}gT2 zDds3Ud|rfOOtAR(WVkbr4?i0e$DEf9_PTyY_fATH1@>;L$2cuKA6H|A+wHzeBhC zg||i7NurIE5o2KU2bcgOdkga(bw`&k5|bG8-(iPT~B zlXMBG;Z&AveKL44RMcm1?fhcD?v|0xHm~jJ!cJQ9-|IXkeR1G{T*Hg4^PGPRlEOum z=J|Z;C@(U5F9X=o&I3FDL6e#TtHg&@@~Dn@+N@U=K4yY+!UQZ?T&!4U>>o5TGG2x2 zQJ=#~b|vU4JLGUl6i90Uk10sIbU*?pMXQ~Q1hrl$m&ldwy6aM7hv}w8TD&UP)^FuFO*Kg7Sg#vsigIR8BKs&@8FwRLYFOOd_d z6|pP;JgSExJ(JWulLj{bYUM)cUKeuqObV^U-JdhD?CE^)ADwS5GUtD1YW0RYZ=$BY_;fgk7$1rSB87d(k_HF2v(m9 z;De@eY1$(cy=J#!8=a10CO*C7kLvv_7lZWUexuC^)4EG_H^oDZcMd-h_p3K`yGeZO z)is^v!Mb8l7qE~mA13>%=mLNXWj+Lp8HUY`aFbI%9e|wu$U2%OjO-N9Cr_W-_&^KhhUxr*niisuGFR&@o(>NOQ} z0R|LRHZ2PET2rv2CCGnXec;TVYJ7RHIT|gD6CCvC#(YMQxCT#dR5*NIb#MkQSxxfxy!ZEhAerRpIGHYU(`!tw6 zb&Rg|O16JONbeMR zS9{$pmTRtMUaRl4ht;_&w*j>1KfRZjSa3WdY~R;u_Dv67aB0Y>PkGh(X;V4t ztzZ7k()+MirA6wcMLBu~j%op+RsLU-+7dT;nzRT8HVMRtH@zR+cA!9I!ylb=leNL1 zZ_Drd?T4I~L|#=WRhDAvOA56TLKgN<=DS>^>Myz6uu;TU|IiI)A3iyDx$4tph;Zn9 z>el7*w?NoD2oqoq?tPl$3YGcPGZ^WPyEcDCfbaa;Qs{e~H{iNHM<%Ph46`tfA_Wh~ zrRvaU44Go&!Ue5Zlg%zh)AfyGb*UEbvOWB${CI)cc;p?1%p-Lp00qxqq(%Ch1N1&2 z2X+0khW}~r#xZ&KFC6ja{)ye7G3S;as}IR^-=D7;)JAUK^y6s8g%fE8$nBFI0Mt_e z?jca^%z>?qvNue#Z;ZA-s_=3>7Yx4QUl!R@i0x<g?EGnaV$=PKqW)}>f7TCR34xQ4 ziX`L<5^`w`ARElW*Ua|A{nkQOc&Zo+qVH2X?h6Y%q1NGO%$01+y)mPO4iax&FZxtrKhm^(hjy9%c^r%+7Mg>3+?2vf zg?EUtc$qOXiXz^y(tYUVo%<%kn8TPKp;y0V6P54LXTOvy>D{FWieBQ8K3mHC`Eu?0JboWtM56&L%mr-6%9{B z1_g_tj2AL%Ymdwn_R(%@gY88chFtf_$yu4*^X#^90Y#dXxsQ9~bwR#)RYvcMHLfgj zP*8c>F}`PQ?;hASN60nCm1TDdRQ!$?r@fjjwoiq{tn4Ls^5il@ea%a*6*ntm`ta$*VeC^H&CYLBlyr0FZ%Z<8Mlpk4UE5tTFK~ZJ{{&ZTJt&@tD_6Az+S9yU^Ej;LS5-H z`#+U^2UJr{yRM3WB8Y&3fIvj5lmOB}K)Qf*={*Fb21w{7BE1OGM35>?dhZaF7CKU; zBfS%9=x{gw=ljn+|5@vXmH1M;VY}JxGV>7-9p9ZfA8q-jl9BAG8~`fC?$N4K~el>^rpT6oLO#>NCT1~3dQ2<8@(P5qp) z>TR>x@6q3{rv>|ndaNX$`ed>dI_2JpF>t%9+iyZhHa*=tO_`iHVNE4P9ho*AIdJ0k zGiqMzA(LJulDlWgdp})(|0J2Z0Slci{KSN9$&VwJxT?mhBtSJJj)$y*`NSkNOw_cmI?8wP7*yA^B}xqGrknV4ty zzSK;u{aABm*NG?Evdq&>WsTQ!sU0rcr8T|X&}X-34(G&_agN2#ESc2cmqQoLe;Fe- zqhfk%<(V!Rqlo7;pW!6khSuD;fcDyLLbPZz>R{SLgl;iyoe;^r$0Oc0Mcb2%o?4<5 ztp>Gqu#fAgwdwx~+>2`Z`hCz54QhH)O@ah_<~kVM@BzCa6E?*-&fy(FC3#PM&9gn695 za>;XakV|>Vs1sY}eCU6;Q{pTw$oz| zDLUig)rGGdQ(-`k72m;bVeOmkSAGE-B&8Y2B@WZ3bHb)`h|SVKO7;_E?EM$-oUo6hZ7eai;hKq@h`S(;AzuUhvwlLV-oqn)|FL%bW^f%&9 z=2|Ms(lUI)Lz7xF7Z+#5DT_9bC+1fZ8(A zgD4X=!WW$D;)Sv7?t(nj^-TiA86G9aN}KfT66qc?hJn$C~zCpO#Ie~Y)@>cn6K$6{t@9d}s!$amx4b887>-MGSE>fVMF_?zKM7rfLx zi;TZTqH}Rq%w5N8FPtd|e$&=p0{6E!r-}1O>52iNnEME=Xoal%AI5RGZx?<3^3$R- zXSlNwWtTzt2xx-ho3~>HSbA%Rw5PW4Wx_jg(k(f;Gu5ym8U0f|oHb!NPfkrb%B{?$ zsYGwixbg`SJ>BS+6zQVc!KFl1pFd(#;ZeZ9wy&-0+;^ul%KUQG{8F9=DG@%OG?}FM ztU!|adg2dIcDdy5shh4H)3Zvj&U(}ZGcqXTwIKqVuT)nK(vK?CyC~P`!0U9L85RIB z7jPsWbL36hWw@Bk0$jABmr_efIqsFvTf7O9>!D1Nk?EGJq%*bgm= z8$>33b{L%uKt7A$b49a=6Kd1G>%%+Ks}wZOaoJ)UDR;~AqF4)MC_6#3!vzs-qf%uw-mOw-InKGQgW)`b_N8N*Af`$dNy48_Qq|T+=h*F@7==v~33S}IE(MBJ!?OsTFi39rP_fZK36dkZm z8VEX%P<5!7&3^be7bkIeOh2*^Rzz#u`q(HvG#73^(Vg~qMwz=|x^2fLbdKg-rw*KY z0v3UN`n&hh_-&X|d9A(HRrZB!#q5(UsiLnNFPZ-;@B?Df5k<9j+XzdQ_Q(0MK(MV% zhp%i?Aha}(vpr8Wd}L*QjkwVy{4EfYTZa@FDHMlu_R&Y#iK->ZI60DU3IRJyMFN&j zc1d384@{lRABUHh7(wYQqmoq`J{1v>C} znwG2Fi;_^_OpNy6QU1^oK#n9&QG(va^0Pr6DhS|Ru9OrT@ zhFUxsDupUo3cHSvn2pYI%HHy`HMg<%+j?DOL^_XtK8Mb0iG14}`KUQ^Nki9e<90CJ zv$G;;AQ0zIr|3^NR7-S!bdTccB|U>>$F8KUJK?9-!sIm{TYl0bSzC=m7r^|~5BK7+ z41of5f??7^PhYg@np0RtvG&mqth+us0%7@H|r5MzarFLnYQq|RdAR%ITq_w#-F7GXkqT`!tU&(_sJo$UG6_4i|`I4 zowM|uxSxfH#$E>#PmBs9p2*8(8(7af<=$OVA1VdSQG28tSbucN<%?G=RO76atsS0- zF|huf{O~Lyop9)N;2HoFq_-q_l;D*EY=GE&fU&-an?P>gL*3rWZQ65oBH`8FIFY<_ z!$*k)KWj|5As-1LNxP3p`ueU(on}VT*)1%;MW5wNLI!b__;nL9ZZ_xfirt_%IN&Qs zS>)Sc9mJ+JG%R4_Zm9!?<41EZ`8b-?Z0;JwJ8yk1j@`(fey3tXos(#w17WGBl1i{9 zWR#3;_2Us2<{f@ar3ragLnY;>`pnmwaBV73TQA&#Vr$*>~7z7Fx zD}Z|=u+2JZ8HlHdbr7UOhy_Y9ItjW@s|*M*W40v7&Vz_YJ&#M5nJ(wOiZNiZ)KD=jb}~BZllXyBUS>HT(Xq0fQ-rjn|1GU;sJnkl zNSHTS=yi#)EQO7nv{I*ZGv<>jPoK61c+C^_L;LJ(OIFF4Q}w&C1{HMY#Ac%xbuQiU z%`A8}8rFJ#=YL{@@oxvw-CM*}F=th|FaG%sG0r6x5b0RWiBtfc8f&)E*xqRu30t>n zq};I^FuJwHSkriW;@+Pc%kE8Ft^ST0zUrtL;~XP(=aX2ffBIBDBDll&oikNEYphz* z<#K-WJmCAZ*1E$Z_fQGB61q);4 z6SLbtX%=uJ+@DGWvR3s4W9h6&%Rf~y^98n^MrUS#U*j#?q;O1h{}65v#%}f;M`xPS z80ESxs~3V_pY^Y&-^V0Qc6`Pf@FXjy!&$ct2$B`E;jgz1=#v#e_3|YyK2Ob~0YoiQ zpH*`j_eCXSCedXk5mGIU%u@Xv;0fe50`NNJH>b$KhlGc#fTE=}>nfNgQy(7|K%^*)CUI934j-9S$5RMP_ zSpJ8s!3H{MaAU`Ub$|cUcaou{%bYx3< zq|MpBoI>9wttV#MmE4Btp|(w$YN4-WoLyN9s})l~W4!dGOPEHezs5KAdp6fqalV=K zoLM?nZS|B&J+_T{ zlbf#6KsIRE_l7?!Tx?fa%s+*_c+-Cw$S&EYXg8cX)F(`#vlg#>Rkk@+wmCpFus2wW zCDRHUkCtE(z1sJR`7z1jimwMnY{wVAAWg!&g`d;RDAtWR)Qy1}fh;S^WFyMg#XW$& znWJqn$Ohrxz}5~KXK(8xoJq+>UiWA+a|4m9gmng{yqL#^$*u35Nhd*`BMygAtSte5 zLt>c2%K7NPVu%b%`zejolkE@BS_UGYaLgJ<%~8Ah`YirA@9;hE;J2RIy}0)bf>`9* zCBmPSa#tysj^_EXK32Im=k(ngZ|uUJq3jt`i?RQ6Mpc(FzUq)ST)SZHQT%TdC2jqm z(f|H?CHhli7PJ>l-xUu_iyP=l(TiRmrEV0k>Qx-#Rjjvlz8c4=^^kEv z8uc46nJTo)6=&+GIhKBtoOu?TxIi{*Q}y_`o9b0<+HQ3|IZo4Qq)d3eevKRVj~~X- z;3eNkPGV8ZGFg8Z_VIE2pz-2F{rJ6k4v`V)rU<5UjwJclNN{!Rg`yu}i~~5K#EKlI zdlxn?Pw=a@5W`m^K#AQGs*fzamn@K==X>OIqLSMu@~38_Gl2-Dop(g_4S)d9{ffb#EagDXGX7H?YZMW&j|sZEYBe(AoZ2*MpSF9f}?ig)ax> z1~UT^?sB=x^NG|)Jc)4}L207=cUHLT;?P=G1{-O44H>%QPMWc3yd@m!wyw{9d3V>Z zlU^08_%voL-zT#ASucOI-e@9}WLzH`>8i5mlGnL{O83Bc^(*3o^>#t6^NEutg>MSp zfrHgH9|1cL%D8lgK9-^JEQn>&s$gzqacRyucz5W%WxSyftY!e8obu~jH^X&$B^Qbe z;k*neyT7LMODo)4srevT_qI)u1P5OB6;=msxmlMV~*v7MFHoj(-fGCx&(?QhfNK7=j-EIpTuY>s^N+s%a zy!4I=>jcF*GTdJ4X!bWRsu^79Tj!deth#eIuK0C$G4Es|y| zqPYbT6trgkiX0Gp!nSG|*#Dia*a^tAE42ipDdDvuViZ?|PG=4W?*+O#AOVZqe}I4w z=ksySzmYt64t{+83-zKtX_wSRC+CR{g3pQd<@-`aeT;mt3F3i4ACOQ&24~9Bx);rO znV@%5G-~#a&GeJeIug0uObkU1#&Y;byA>k_535wp#8}Srw{4s?>KPVj54U+p6*SvY z&a#<2LTp-58g3f4`zAe4HnaAus{4Ya8z*qeE2w?bXZmcvTOy$e{~)rDe2Y=l?!cGl zD(R~ixn$)4bz3?=+kUaqtvb&1iPh=u^Z4G;r3yJf4KP-BKxImd+{QnRUYij zEzns0%^2_^W+QUJD0-A8VXK(5rG-w)^3)3q6|ipt6-L-1N9N)>QJo-Wa6$i1fE^O?>RA{j@ zQdf!@!bH6z@^+ff;&`O{YI{Wj|K_S}o`Yj?)q(k@v57~2LdCzjwPAF8sj_NBAOW7( zFv_87wDHQlFsR$cuJ)Ps@_~CHX6zP(t{W67(=09fRRelR7b&)hOHUb548(fl=GF4t zV=S+tegL@+*ebDj4P39{c#h%)qi~G#A)S8eAEN?HWeg_H=^dXVO8Z|Kb<^DW&uqL` zz0qlb)3ymBcyalN&00uRip&oxmw55u9WLN7&4c`AzFuLic*Die!tB3Spyd<8;)7U$ z6==l9-ustpBE;wY)y9{nB(zQ5z^b#RtE01OxB86BIgZ~Ro=g~a?bJ~Zi~Tb+KENJ4 zsD+Dss7lbOm#IF(hu%jmF^3mB({wXFdqD7x#p;^2YuOJTO`N8pg z3ry^y34=VE1k=$Wuds*cGvf0#N`>dY%aInq-f&IE8MDYHxjd^#`8Cd$$%BR`r;$yb z=lcu9;ugd^mRERMF+~lWd#kRWQ*G`dk6_|nM@XN2H1cA4VO;F;fW34|hNH;J=dcY4 zJ*Js;Ai6pjAGn~MGPP~!d9{0CvN83_2y&IT5x;o9ain8a1!fg!GJ|pU^t!^%p>1uO zhl<)Rc8rg8i%f=uPPL7j50BY8+4>%AzNUrASOny~Hp)*hLkXT8ZA?}*qAq_b9dXSf zMNgW;`9&8+&z1t;Ze5Q1Up}^&yHjLhFsIbAfa=)kF>w3 zA86Ej5&hnw<2&w4BH2g|J)?c%(}Thgj<}Au=Vc&=cSNi#2^Pxw*Boe5oxQjhFxW4Z zN1XBif;aZr9l1Jg6Zbja<8D6dzU;m7@H!K}I{G~;hB`TgHF=+JP8K&^F1M&4cemm( zNX%{<80FQ#MrC|njTS$jUI11Rid~+A&%#(cIqv)xK_67kqXn+8bjb5w$51i%r@%$nc@hzoT6Dk=&BYq~o?L10x=ODG%!R{nI4xzndfgt2)6T8c+mCAFL`Z z3wVIKAq)w?vM``2QBklg4~YA^5p@t)_63NW`|lyp5Lm_yA*X>bML>aC*DV9yZDCFt z4yKU57BF00P7=iTPxb$HeQmnF8h!9s>F8wDCwqaTFE{<3+eeoG!m`HJFv&VBcR!jDfk==r5J9i-KwvhVP){CS@t6;(22-lKIlKArpFHY@4eeNULK z^KfpZE%;-Yr3wB`!krs9wm1Gbl$T4AAIsiKxaBn#Zks@MOwm|(A9Ql|d`LX}=Z&k> z*jinB?i;FK!dLc=#|9Coxv5bbhJgebdLK&_}QPfk!I_zQ?Zbg-w7G3+?mx zi&A#O`{toLi&M-CAB9L!;ZY`(6f1X*Yk5#i5I@B0K#6wPVkxDUGXD*h=qb)+xQ4kc z2PB$>=L5%r`;9;HoyI$ZV4a?RvTowGz8*bJQihyhN+tu1z>hIxVRQZcZ&t$EdbsWj ze0(;~J(fVJ`()1PhDHCm?n8Gw$})P9F+m|gE;|l86w5Hu@ce7^k;`Wzf8;i$G~ICv zR@*0m=tfC4v~v73$j<7~4a1F_s`VE^y(Zurp=BuN``(VUbzVm5t@G@bZ241D28uUR zZCJspnA6nzNGW5les$C|X35lTKSnSb!7XJZU~l1(E#2DDH}7ylxSSevOoxBzOiNC3 z&VULA$I3`|XDfk}K3D2@kOku=NCrwArzRc~w_Ik9*M1I}I41e^S?5;PQz{7`+8Zp- zNkDf!&DnloyzjNk;hgk_4J3R?KI{K*>8)L(blE}9fQ*31N%Pc@s`YIqp6lJ>1>KO5 zz*(1|Ud18%al7gVNzD!7KRCBuu>{|CG~xd9;o+y7(jbb5?<>ZUr^{gn5tI|Mxv5Bvi<9z0SHLV%EmrkcSrAlpH;AOF)70LPo<8!xf5vq;`=?$Bi7jrq ziHhKz2!D#7ojW{&betcmf5bW9csbw=gae@@84dC^v?? zBv11{k!Ieql9>2Jn@Lw2Dj${8q5lw1MuuBeDfV6$-J^i{Z=ch(()ly;)bLf4zl#mO z9cHm6I3#%^YxAvlpl|gCf?b$0IgC?QJMHT)n$_}Ek^{lhM|ghekZ|sZ$4I3oOpnTM zl~a~e4@C$CP_~DgW|!&|2#-G52qkKBDlxO=t|IV!;7RIs$@J6oji8uLS#x41 zQC+1ONqeT$r?bpWYH81Pp5JEKd8oxU%z}7spyrkxtj()=plML>rC2B3P1;d@H<#3? zQ$D1yRZTBTGXtTy7C2bJ^LAWTNK;74z1%5m4|hrKA$wc!ywsdpD9ag(B@0B;KTid! zQ9JBBEW56|E=VNxA{+OYx>Z&M?44f)>!Z-nWQ7Wa6orpnj*nPr(y0elvuUBrF6i0&ubNzp<Ven|c2&`i)##xztK#A0&{VB_^uxyZHfkHiFOj!kMw|u+FdUg-5%Gnn!@gmdDY- z-Bb1ph6|e0##0SEVZ5h!xOjzl)kM32>@5#l3`eKRN9)CXu08>K zK9r3lzoUSz#h{5(??Xrz&zl$1b{^w|{N)0Q-1*$pJVCuQJ-EyDy+Itm$d$<@!|=kW zl}LwT5?XAb5qg6hejN8W>e*9uDRtWP?aJ4yPv60l80;C$*5}cgU9WXA*f7kpC#;sP zZnRf-HFS;e^gF{L_9jk|i$VM6-{P-4foZ^E8-8m zA7p;MeCi-?(t-U{zfZJsZ^bp>!>{+hw$hK9!&^QFc+*APCB9dD7x~zfOzpuy)B8G; z&JUk)i|HHbyXi5~3DU2>d1O4wAp7<;!x-&`jz!Bu3eB|JjY5Zl$y%M!kcEteuk$$+ zr|eU;4x&HB(go*E=@(?&!#LSTb&^oW$E0nHNsMx&10mcY93dE?^d!8#gTeP%m5Mnv zw%eTBWGVPCd{{K53%sJjP|Fm@{8GW?%}k1D!hDK))Sl)Ka?N`wIj1?JSt#XuZzfZ* ztS^}wU*g0^eR0&3C&|8h##8xXpC_oir#!SgvpXq%%YdJefRqm^H6B)0-^M%MKm5K` zy3B|tapAK@%s!KV@R59qQwkT%q;`DoO*iwN_kNR+uij6?0sS=nk}4BK)=Jmu+h2KE z`5xLE#hiLCQSGo^-%9^VD;p$B1t&Y$tCrKkP$f!hAn{x2q0feX*rQOHHUa(`+wYUX z6D(tbHCEf%d2i?x-54np3l-TEW?{?rsN=X^?KoraiRcPwNl&_MzgCad+~~&SR5cBY zHfKMWZj!dF5snX$>x_sOiQjBcHPu$D4l7YCQ`Dn07&nBfR#vWiJ1ZQ@f7E{CS!l79 zJ@LEVy}o#JcWg*2=dHHhk$tfVrq`qCv=1*MFx2~tx6m0azpMZj*?U@7`#K}HVy(qz z&S%Xx7{|LeqPLeLkpo)jke}(iXVUz$d)5s(G~I5S56h{Jr@a-#5JZdodc1Ym@+!zP zvLvFy+w$1Z4!<%ZlWg5!Mrb5%kZ~(wgI0{nt)d#8m9ya4jX9zldZ`6BSaKV`+Z^(Z zELC|qHAyVad3|kdaR}0==z&QJc?mBBH^6pme~s_2c=ac*9c_xc&m5kY-s_`?FfupX ztXp)*h5ztLTfje~6UL*#6A5|}R0kF@+@?$s@R|=jiyP8zEKaE>ci0;2IFFj!Q2Py= zk*|5$*jazFs&!hpQVqB7pVEa>cvml`3^sf2pRQ%QWd(+s};5HP47(2MorYyEFif>Ru!vAn=*j)h$Z)7iOF{Kzb@h?8BCyx(y zw{yZ(Qhjia{P)lP7wQ)JHw-2CFVrn#58z5GdrJ`b8n*uTJ8dibSN3qLe+&d*X)6m0 zs1wv40)TXV5HBCt&dS~y4l*S8Zxs9&Q~!f<{{`y*B5tsTvl-$q#=kZKP+r;84gkLZ z3jgc$Uv=c6wk}YF6~q)k;s5mMy1VNC7sCIG)c-#m0Eqhfs{X?Pha}9_{Qu#_%?WBj zzy;#wA>jJ=1H{kA_ks^(0s6O%2Vf1?50L%8ZQT3-tN9-`UT%Kg|E$N$Ex-d%mH((G z$O|x@|Fj7LB;|kDxVU(@dH%Oe=s#_|ynF%xC;1lq)2L|*%Yy$iMHTlPea5A;B zg*yEuWg1oSx{*D$euOPo50VAV~iY&qZ E0fhqC;s5{u diff --git a/vignettes/figure/getNWISUnitPlot.pdf b/vignettes/figure/getNWISUnitPlot.pdf deleted file mode 100644 index 710116d8c74a4b14e88149d07f6deed176e0f02b..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 13636 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 diff --git a/vignettes/figure/getNWIStemperaturePlot-1.pdf b/vignettes/figure/getNWIStemperaturePlot-1.pdf deleted file mode 100644 index ed6227cf2c3baff93b403f041599c56a5da18c9a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6597 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 diff --git a/vignettes/figure/getQWtemperaturePlot.pdf b/vignettes/figure/getQWtemperaturePlot.pdf deleted file mode 100644 index 84f8397d9e32356148774eb556c3bdf3402b32fb..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 8435 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 Date: Fri, 19 May 2017 13:28:55 -0500 Subject: [PATCH 2/6] update build ignore --- .Rbuildignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.Rbuildignore b/.Rbuildignore index 5decb7c8..e7b0d76d 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -1,5 +1,5 @@ .Rhistory -vignettes/figure +vignettes/figures appveyor.yml .travis.yml .gitignore From cc74503ac48370e9cc64b09d010f571afcbb53ea Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Fri, 19 May 2017 14:10:39 -0500 Subject: [PATCH 3/6] Found some edits --- R/whatNWISData.r | 8 ++++++-- inst/doc/dataRetrieval.Rmd | 9 ++++----- inst/doc/dataRetrieval.html | 6 +++--- vignettes/dataRetrieval.Rmd | 9 ++++----- 4 files changed, 17 insertions(+), 15 deletions(-) diff --git a/R/whatNWISData.r b/R/whatNWISData.r index caa3fecb..6782f19a 100644 --- a/R/whatNWISData.r +++ b/R/whatNWISData.r @@ -69,8 +69,12 @@ whatNWISdata <- function(siteNumbers,service="all",parameterCd="all",statCd="all siteNumber <- paste(siteNumbers,collapse=",") if(!("all" %in% service)){ - service <- match.arg(service, c("dv","uv","qw","ad","id","pk","sv","gw","aw","all","ad","iv","rt"), several.ok = TRUE) - } + 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" + } + } if(!("all" %in% parameterCd)){ if(anyNA(parameterCd)){ diff --git a/inst/doc/dataRetrieval.Rmd b/inst/doc/dataRetrieval.Rmd index 9ad527ea..1085d715 100644 --- a/inst/doc/dataRetrieval.Rmd +++ b/inst/doc/dataRetrieval.Rmd @@ -133,7 +133,7 @@ htmlTable(data.df, # USGS Web Retrievals -In this section, examples of National Water Information System (NWIS) retrievals show how to get raw data into R. This data includes [site information](#site-information), measured [parameter information](#parameter-information), historical [daily values](#daily-data), [unit values](#unit-data) (which include real-time data but can also include other sensor data stored at regular time intervals), [water quality data](#water-quality-data), [groundwater level data](#groundwater-level-data), [peak flow data](#peak-flow-data), [rating curve data](#rating-curve-data), and [surface-water measurement data](#surface-water-measurement-data). The section [Embedded Metadata](#embedded-metadata) shows instructions for getting metadata that is attached to each returned data frame. +In this section, examples of National Water Information System (NWIS) retrievals show how to get raw data into R. This data includes [site information](#site-information), measured [parameter information](#parameter-information), historical [daily values](#daily-data), [unit values](#unit-data) (which include real-time data but can also include other sensor data stored at regular time intervals), [water quality data](#water-quality-data), [groundwater level data](#groundwater-level-data), [peak flow data](#peak-flow-data), [rating curve data](#rating-curve-data), [surface-water measurement data](#surface-water-measurement-data), [water use data](#water-use-data), and [statistics data](#statistics-data). The section [Embedded Metadata](#embedded-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 `siteNumber`). Often (but not always), these ID's are 8 digits for surface-water sites and 15 digits for groundwater sites. 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](https://maps.waterdata.usgs.gov/mapper/index.html). @@ -182,6 +182,8 @@ htmlTable(data.df, Examples for using these site numbers, parameter codes, and statistic codes will be presented in subsequent sections. +There are occasions where NWIS values are not reported as numbers, instead there might be text describing a certain event such as "Ice". Any value that cannot be converted to a number will be reported as NA in this package (not including remark code columns), unless the user sets an argument `convertType` to `FALSE`. In that case, the data is returned as a data frame that is entirely character columns. + ## Site Information @@ -207,7 +209,7 @@ comment(siteINFO) ### whatNWISdata -To discover what data is available for a particular USGS site, including measured parameters, period of record, and number of samples (count), use the `whatNWISdata` function. It is possible to limit the retrieval information to a subset of services. The possible choices for services are: "dv" (daily values), "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), and "id" (historical instantaneous values). +To discover what data is available for a particular USGS site, including measured parameters, period of record, and number of samples (count), use the `whatNWISdata` function. It is possible to limit the retrieval information to a subset of services. The possible choices for services are: "dv" (daily values), "uv", 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), and "id" (historical instantaneous values). In the following example, we limit the retrieved data to only daily data. The default for "service" is `all`, which returns all of the available data for that site. Likewise, there are arguments for parameter code (`parameterCd`) and statistic code (`statCd`) to filter the results. The default for both is to return all possible values (`all`). The returned `count_nu` for "uv" data is the count of days with returned data, not the actual count of returned values. @@ -346,9 +348,6 @@ legend("topleft", variableInfo$param_units, ``` -There are occasions where NWIS values are not reported as numbers, instead there might be text describing a certain event such as "Ice". Any value that cannot be converted to a number will be reported as NA in this package (not including remark code columns). - - ## Unit Data Any data collected at regular time intervals (such as 15-minute or hourly) are known as "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 `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. diff --git a/inst/doc/dataRetrieval.html b/inst/doc/dataRetrieval.html index ed74ed15..f8237ee1 100644 --- a/inst/doc/dataRetrieval.html +++ b/inst/doc/dataRetrieval.html @@ -389,7 +389,7 @@

    19 May, 2017

    1 USGS Web Retrievals

    -

    In this section, examples of National Water Information System (NWIS) retrievals show how to get raw data into R. This data includes site information, measured parameter information, historical daily values, unit values (which include real-time data but can also include other sensor data stored at regular time intervals), water quality data, groundwater level data, peak flow data, rating curve data, and surface-water measurement data. The section Embedded Metadata shows instructions for getting metadata that is attached to each returned data frame.

    +

    In this section, examples of National Water Information System (NWIS) retrievals show how to get raw data into R. This data includes site information, measured parameter information, historical daily values, unit values (which include real-time data but can also include other sensor data stored at regular time intervals), water quality data, groundwater level data, peak flow data, rating curve data, surface-water measurement data, water use data, and statistics data. The section Embedded 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 siteNumber). Often (but not always), these ID’s are 8 digits for surface-water sites and 15 digits for groundwater sites. 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.

    Once the siteNumber is known, the next required input for USGS data retrievals is the “parameter code”. This is a 5-digit code that specifies the measured parameter being requested. For example, parameter code 00631 represents “Nitrate plus nitrite, water, filtered, milligrams per liter as nitrogen”, with units of “mg/l as N”.

    Not every station will measure all parameters. A short list of commonly measured parameters is shown in Table 2.

    @@ -458,6 +458,7 @@

    1 USGS Web Retrievals

    Examples for using these site numbers, parameter codes, and statistic codes will be presented in subsequent sections.

    +

    There are occasions where NWIS values are not reported as numbers, instead there might be text describing a certain event such as “Ice”. Any value that cannot be converted to a number will be reported as NA in this package (not including remark code columns), unless the user sets an argument convertType to FALSE. In that case, the data is returned as a data frame that is entirely character columns.

    1.1 Site Information

    @@ -471,7 +472,7 @@

    1.1.1 readNWISsite

    1.1.2 whatNWISdata

    -

    To discover what data is available for a particular USGS site, including measured parameters, period of record, and number of samples (count), use the whatNWISdata function. It is possible to limit the retrieval information to a subset of services. The possible choices for services are: “dv” (daily values), “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), and “id” (historical instantaneous values).

    +

    To discover what data is available for a particular USGS site, including measured parameters, period of record, and number of samples (count), use the whatNWISdata function. It is possible to limit the retrieval information to a subset of services. The possible choices for services are: “dv” (daily values), “uv”, 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), and “id” (historical instantaneous values).

    In the following example, we limit the retrieved data to only daily data. The default for “service” is all, which returns all of the available data for that site. Likewise, there are arguments for parameter code (parameterCd) and statistic code (statCd) to filter the results. The default for both is to return all possible values (all). The returned count_nu for “uv” data is the count of days with returned data, not the actual count of returned values.

    # Continuing from the previous example: This pulls out just
 # the daily, mean data:
@@ -609,7 +610,6 @@ 
    1.3 Daily Data
    
 legend("topleft", variableInfo$param_units, col = c("black", 
     "red"), lty = c(NA, 1), pch = c(1, NA))

    -

    There are occasions where NWIS values are not reported as numbers, instead there might be text describing a certain event such as “Ice”. Any value that cannot be converted to a number will be reported as NA in this package (not including remark code columns).

    1.4 Unit Data

    diff --git a/vignettes/dataRetrieval.Rmd b/vignettes/dataRetrieval.Rmd index 9ad527ea..1085d715 100644 --- a/vignettes/dataRetrieval.Rmd +++ b/vignettes/dataRetrieval.Rmd @@ -133,7 +133,7 @@ htmlTable(data.df, # USGS Web Retrievals -In this section, examples of National Water Information System (NWIS) retrievals show how to get raw data into R. This data includes [site information](#site-information), measured [parameter information](#parameter-information), historical [daily values](#daily-data), [unit values](#unit-data) (which include real-time data but can also include other sensor data stored at regular time intervals), [water quality data](#water-quality-data), [groundwater level data](#groundwater-level-data), [peak flow data](#peak-flow-data), [rating curve data](#rating-curve-data), and [surface-water measurement data](#surface-water-measurement-data). The section [Embedded Metadata](#embedded-metadata) shows instructions for getting metadata that is attached to each returned data frame. +In this section, examples of National Water Information System (NWIS) retrievals show how to get raw data into R. This data includes [site information](#site-information), measured [parameter information](#parameter-information), historical [daily values](#daily-data), [unit values](#unit-data) (which include real-time data but can also include other sensor data stored at regular time intervals), [water quality data](#water-quality-data), [groundwater level data](#groundwater-level-data), [peak flow data](#peak-flow-data), [rating curve data](#rating-curve-data), [surface-water measurement data](#surface-water-measurement-data), [water use data](#water-use-data), and [statistics data](#statistics-data). The section [Embedded Metadata](#embedded-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 `siteNumber`). Often (but not always), these ID's are 8 digits for surface-water sites and 15 digits for groundwater sites. 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](https://maps.waterdata.usgs.gov/mapper/index.html). @@ -182,6 +182,8 @@ htmlTable(data.df, Examples for using these site numbers, parameter codes, and statistic codes will be presented in subsequent sections. +There are occasions where NWIS values are not reported as numbers, instead there might be text describing a certain event such as "Ice". Any value that cannot be converted to a number will be reported as NA in this package (not including remark code columns), unless the user sets an argument `convertType` to `FALSE`. In that case, the data is returned as a data frame that is entirely character columns. + ## Site Information @@ -207,7 +209,7 @@ comment(siteINFO) ### whatNWISdata -To discover what data is available for a particular USGS site, including measured parameters, period of record, and number of samples (count), use the `whatNWISdata` function. It is possible to limit the retrieval information to a subset of services. The possible choices for services are: "dv" (daily values), "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), and "id" (historical instantaneous values). +To discover what data is available for a particular USGS site, including measured parameters, period of record, and number of samples (count), use the `whatNWISdata` function. It is possible to limit the retrieval information to a subset of services. The possible choices for services are: "dv" (daily values), "uv", 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), and "id" (historical instantaneous values). In the following example, we limit the retrieved data to only daily data. The default for "service" is `all`, which returns all of the available data for that site. Likewise, there are arguments for parameter code (`parameterCd`) and statistic code (`statCd`) to filter the results. The default for both is to return all possible values (`all`). The returned `count_nu` for "uv" data is the count of days with returned data, not the actual count of returned values. @@ -346,9 +348,6 @@ legend("topleft", variableInfo$param_units, ``` -There are occasions where NWIS values are not reported as numbers, instead there might be text describing a certain event such as "Ice". Any value that cannot be converted to a number will be reported as NA in this package (not including remark code columns). - - ## Unit Data Any data collected at regular time intervals (such as 15-minute or hourly) are known as "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 `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. From 1ca3f5fcacb71a466cc606e33c53cc2d6fe2d463 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Fri, 19 May 2017 14:32:23 -0500 Subject: [PATCH 4/6] Just in case...skip the "mock"s on cran --- tests/testthat/tests_general.R | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tests/testthat/tests_general.R b/tests/testthat/tests_general.R index c0c2e4ba..964bd283 100644 --- a/tests/testthat/tests_general.R +++ b/tests/testthat/tests_general.R @@ -312,6 +312,7 @@ test_that("NGWMN functions working", { context("getWebServiceData") test_that("long urls use POST", { + testthat::skip_on_cran() url <- paste0(rep("reallylongurl", 200), collapse = '') with_mock( RETRY = function(method, ...) { @@ -324,7 +325,9 @@ test_that("long urls use POST", { .env = "httr" ) }) + test_that("ngwmn urls don't use post", { + testthat::skip_on_cran() url <- paste0(rep("urlwithngwmn", 200), collapse = '') with_mock( RETRY = function(method, ...) { From 87cbf9b3b52fa89dc24933120dcc096f494efd95 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Fri, 19 May 2017 14:38:02 -0500 Subject: [PATCH 5/6] Add some more skip_on_cran just in case --- tests/testthat/tests_userFriendly_fxns.R | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/tests/testthat/tests_userFriendly_fxns.R b/tests/testthat/tests_userFriendly_fxns.R index 0422d1b7..9871165e 100644 --- a/tests/testthat/tests_userFriendly_fxns.R +++ b/tests/testthat/tests_userFriendly_fxns.R @@ -202,6 +202,8 @@ test_that("readNWISuse tests", { context("state tests") test_that("state county tests",{ + testthat::skip_on_cran() + fullName <- stateCdLookup("wi", "fullName") expect_equal(fullName, "Wisconsin") @@ -235,6 +237,7 @@ df_test <- data.frame(site_no = as.character(1:13), result_va = 1:13, stringsAsFactors = FALSE) test_that("addWaterYear works with Date, POSIXct, character, but breaks with numeric", { + testthat::skip_on_cran() library(dplyr) df_date <- df_test @@ -254,7 +257,7 @@ test_that("addWaterYear works with Date, POSIXct, character, but breaks with num }) test_that("addWaterYear works for each column name", { - + testthat::skip_on_cran() nwisqw_style <- df_test nwisqw_style_wy <- addWaterYear(nwisqw_style) expect_equal(ncol(nwisqw_style_wy), ncol(nwisqw_style) + 1) @@ -277,6 +280,7 @@ test_that("addWaterYear works for each column name", { }) test_that("addWaterYear correctly calculates the WY and is numeric", { + testthat::skip_on_cran() df_test_wy <- addWaterYear(df_test) expect_is(df_test_wy[['waterYear']], "numeric") expect_true(all(df_test_wy[['waterYear']][1:9] == 2010)) @@ -284,18 +288,21 @@ test_that("addWaterYear correctly calculates the WY and is numeric", { }) test_that("addWaterYear adds column next to dateTime", { + testthat::skip_on_cran() df_test_wy <- addWaterYear(df_test) dateTime_col <- which(names(df_test_wy) == "dateTime") expect_equal(names(df_test_wy)[dateTime_col + 1], "waterYear") }) test_that("addWaterYear can be used with pipes", { + testthat::skip_on_cran() library(dplyr) df_test_wy <- df_test %>% addWaterYear() expect_equal(ncol(df_test_wy), ncol(df_test) + 1) }) test_that("addWaterYear doesn't add another WY column if it exists", { + testthat::skip_on_cran() df_test_wy <- addWaterYear(df_test) expect_equal(ncol(df_test_wy), ncol(df_test) + 1) df_test_wy2 <- addWaterYear(df_test_wy) @@ -303,6 +310,7 @@ test_that("addWaterYear doesn't add another WY column if it exists", { }) test_that("calcWaterYear can handle missing values", { + testthat::skip_on_cran() dateVec <- seq(as.Date("2010-01-01"),as.Date("2011-01-31"), by="months") dateVec[c(3,7,12)] <- NA wyVec <- dataRetrieval:::calcWaterYear(dateVec) @@ -314,6 +322,7 @@ test_that("calcWaterYear can handle missing values", { context("Construct NWIS urls") test_that("Construct NWIS urls", { + testthat::skip_on_cran() siteNumber <- '01594440' startDate <- '1985-01-01' @@ -368,7 +377,17 @@ test_that("Construct NWIS urls", { context("Construct WQP urls") test_that("Construct WQP urls", { + testthat::skip_on_cran() + site_id <- '01594440' + startDate <- '1985-01-01' + endDate <- '' + pCode <- c("00060","00010") + url_wqp <- constructWQPURL(paste("USGS",site_id,sep="-"), + c('01075','00029','00453'), + startDate,endDate) + + expect_equal(url_wqp, "https://www.waterqualitydata.us/Result/search?siteid=USGS-01594440&pCode=01075;00029;00453&startDateLo=01-01-1985&sorted=no&mimeType=tsv") }) context("checkWQPdates") From e0ec4699135f3c0f9bbb8e1c7e4b5fa0bfdab305 Mon Sep 17 00:00:00 2001 From: Laura DeCicco Date: Fri, 19 May 2017 15:10:32 -0500 Subject: [PATCH 6/6] news --- NEWS | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/NEWS b/NEWS index cd848f4d..d8fbf35b 100644 --- a/NEWS +++ b/NEWS @@ -1,3 +1,7 @@ +dataRetrieval 2.7.1 +========== +* Converted vignette to html + dataRetrieval 2.7.0 ========== * Added National Groundwater Monitoring Network services