Home
Exploration and Graphics for RivEr Trends (EGRET):
An R-package for the analysis of long-term changes in water quality and streamflow, including the water-quality method Weighted Regressions on Time, Discharge, and Season (WRTDS)
The link for the official USGS publication user guide is here: http://pubs.usgs.gov/tm/04/a10/
An introduction to the EGRET package can be found here:
http://usgs-r.github.io/EGRET/
Evaluating long-term changes in river conditions (water quality and discharge) is an important use of hydrologic data. To carry out such evaluations, the hydrologist needs tools to facilitate several key steps in the process: acquiring the data records from a variety of sources, structuring it in ways that facilitate the analysis, routines that will process the data to extract information about changes that may be happening, and graphical techniques that can display findings about change. The R package EGRET (Exploration and Graphics for RivEr Trends) was developed for carrying out each of these steps in an integrated manner. It is designed to accept easily data from three sources: U.S. Geological Survey hydrologic data, Water Quality Portal Data (currently including U.S. Environmental Protection Agency (EPA) STORET data, and USDA STEWARDS data), and user-supplied flat files. The EGRET package has components oriented towards the description of long-term changes in streamflow statistics (high flow, average flow, and low flow) as well as changes in water quality. For the water-quality analysis, it uses Weighted Regressions on Time, Discharge and Season (WRTDS) to describe long-term trends in both concentration and flux. EGRET also creates a wide range of graphical presentations of the water-quality data and of the WRTDS results. The following report serves as a user guide, providing detailed guidance on installation and use of the software, documentation of the analysis methods used, as well as guidance on some of the kinds of questions and approaches that the software can facilitate.
Note: As of February 5, 2015 a new version of the user guide has been posted at the URL given above. If you were using previous versions of EGRET you should take a look here to see a list of the major changes in the workflow and some function names..
The EGRET and dataRetrieval packages are only available from CRAN (http://cran.us.r-project.org/) and not from this wiki page. Thus, to download these packages and to use them you must have R installed on your computer. To download the packages, once you have started an R session the command is simply:
install.packages(c("dataRetrieval","EGRET"))Once you have it installed them you will need to load them. Loading is done with the commands
library(dataRetrieval)
library(EGRET)Then you will have access to the package vignettes, to help pages, and to the code itself.
Please see the following link for information on converting deprecated workflow:
Please report any bugs on the Issues page:
https://github.com/USGS-R/EGRET/issues
WRTDS is a method of analysis for long-term surface water quality data to evaluate trends and average concentrations and fluxes. It is intended for use with data sets of more than about 200 observations of water quality over a time span of about 20 years or more, but can be used with somewhat shorter data sets. There also needs to be a daily time series of streamflow data covering the entire period of the water quality data collection. The method can be used with smaller data sets, but some adjustments by the user are needed to make it work with less than 100 water quality observations. The best way to learn about the WRTDS approach is to read the User Guide and two journal articles which are available, for free, from the journals in which they were published.
The first relates to nitrate and total phosphorus data for 9 rivers draining to Chesapeake Bay:
The second is an application to nitrate data for 8 monitoring sites on the Mississippi River or its major tributaries:
The manual assumes that the user understands the concepts underlying WRTDS. Thus, reading at least the first of these papers is necessary to understanding the manual.
Load data from web services:
library(EGRET)
Daily <- readNWISDaily("06934500","00060","1979-10-01","2010-09-30")
Sample <-readNWISSample("06934500","00631","1970-10-01","2011-09-30")
INFO <-readNWISInfo("06934500","00631")
eList <-mergeReport(INFO, Daily, Sample)This is a sample workflow for a WRTDS trend analysis using EGRET on the Choptank River at Greensboro MD, for Nitrate:
library(EGRET)
############################
# Gather discharge data:
siteID <- "01491000" #Choptank River at Greensboro, MD
startDate <- "" #Gets earliest date
endDate <- "2011-09-30"
# Gather sample data:
parameter_cd<-"00631" #5 digit USGS code
Sample <- readNWISSample(siteID,parameter_cd,startDate,endDate)
#Gets earliest date from Sample record:
#This is just one of many ways to assure the Daily record
#spans the Sample record
startDate <- min(as.character(Sample$Date))
# Gather discharge data:
Daily <- readNWISDaily(siteID,"00060",startDate,endDate)
# Gather site and parameter information:
# Here user must input some values for
# the default (interactive=TRUE)
INFO<- readNWISInfo(siteID,parameter_cd)
INFO$shortName <- "Choptank River near Greensboro, MD"
# Merge discharge with sample data:
eList <- mergeReport(INFO, Daily, Sample)
############################
############################
# Check sample data:
boxConcMonth(eList)
boxQTwice(eList)
plotConcTime(eList)
plotConcQ(eList)
multiPlotDataOverview(eList)
############################
############################
# Run WRTDS model:
eList <- modelEstimation(eList)
############################
############################
#Check model results:
#Require Sample + INFO:
plotConcTimeDaily(eList)
plotFluxTimeDaily(eList)
plotConcPred(eList)
plotFluxPred(eList)
plotResidPred(eList)
plotResidQ(eList)
plotResidTime(eList)
boxResidMonth(eList)
boxConcThree(eList)
#Require Daily + INFO:
plotConcHist(eList)
plotFluxHist(eList)
# Multi-line plots:
date1 <- "2000-09-01"
date2 <- "2005-09-01"
date3 <- "2009-09-01"
qBottom<-100
qTop<-5000
plotConcQSmooth(eList, date1, date2, date3, qBottom, qTop,
concMax=2,qUnit=1)
q1 <- 10
q2 <- 25
q3 <- 75
centerDate <- "07-01"
yearEnd <- 2009
yearStart <- 2000
plotConcTimeSmooth(eList, q1, q2, q3, centerDate, yearStart, yearEnd)
# Multi-plots:
fluxBiasMulti(eList)
#Contour plots:
clevel<-seq(0,2,0.5)
maxDiff<-0.8
yearStart <- 2000
yearEnd <- 2010
plotContours(eList, yearStart,yearEnd,qBottom,qTop,
contourLevels = clevel,qUnit=1)
plotDiffContours(eList, yearStart,yearEnd,
qBottom,qTop,maxDiff,qUnit=1)
# modify this for your own computer file structure
savePath<-"/Users/rhirsch/Desktop/"
saveResults(savePath, eList)This is a sample workflow for a flowHistory application for the entire record.
library(EGRET)
# Flow history analysis
############################
# Gather discharge data:
siteID <- "01491000" #Choptank River at Greensboro, MD
startDate <- "" # Get earliest date
endDate <- "" # Get latest date
Daily <- readNWISDaily(siteID,"00060",startDate,endDate)
# Gather site and parameter information:
# Here user must input some values for
# the default (interactive=TRUE)
INFO<- readNWISInfo(siteID,"00060")
INFO$shortName <- "Choptank River at Greensboro, MD"
eList <- as.egret(INFO, Daily, NA, NA)
############################
############################
# Check flow history data:
plotFlowSingle(eList, istat=7,qUnit="thousandCfs")
plotSDLogQ(eList)
plotQTimeDaily(eList, qLower=1,qUnit=3)
plotFour(eList qUnit=3)
plotFourStats(eList, qUnit=3)
############################
# modify this for your own computer file structure:
savePath<-"/Users/rhirsch/Desktop/"
saveResults(savePath, eList)Please email questions, comments, and feedback to: egret_comments@usgs.gov
Additionally, to subscribe to an email list concerning updates to these R packages, please send a request to egret_comments@usgs.gov.
- start/end year argument names unified to yearStart and yearEnd (previously included startYear and endYear)
- Argument for randomized censored values names randomCensored
- Added an argument to the concentration and residual plotting functions to randomize the censored values for the plots.
- Minor bug fixes
- Removed unnecessary disclaimer.
- Minor bug fixes
- Added kg/year option for flux
- Updated CITATION file
- Exposed sysdata.rda constants
- Fixed some inconsistancies in readUserInfo function
- Added prettyDate argument to plotFluxTimeDaily, plotConcTimeDaily, and plotQTimeDaily. This overrides the 'pretty' axis so that the plot starts and ends exactly at the startYear/endYear arguments
- Added testthat unit tests
- Added kg/year flux constant
- Updated processQWData to be more inclusive of Water Quality Portal data
- Moved some lookup files (month labels, flux labels) to sysdata.rda
###EGRET 2.0.0
- November 13, 2014
- New workflow
###EGRET 1.3.0
- July 31, 2014
- Modified the smoothing algorithm in flowHistory and WRTDS to reduce "edge effects". New smoother is the default, but original method is still available (see User Guide for details). The modified method tends to reduce curvature near the start and end of record. It has no effect during the middle years of the data set.
###EGRET 1.2.5
- March 14, 2014
- Added period of analysis control to all graphs and tables (with exception of plotContours, plotDiffContours, plotConcQSmooth, and plotConcTimeSmooth). This allows these outputs to be limited to specific months of the year as determined by the user.
- Changed default color palette for contour plots
- Updated vignette.
- Added setupYears call within functions to generally eliminate the need for AnnualResults.
- Updated calculateMonthlyResults to give month, year, and decimal year.
- Continued to improve documentation.
###EGRET 1.2.4
-
July 10, 2013
-
Version 1.2.3 February 21, 2013
-
Version 1.2.1 June 8, 2012
-
Version 1.1.3 April 26, 2012
-
Version 1.0.0 March 16, 2012
This software has been approved for release by the U.S. Geological Survey (USGS). Although the software has been subjected to rigorous review, the USGS reserves the right to update the software as needed pursuant to further analysis and review. No warranty, expressed or implied, is made by the USGS or the U.S. Government as to the functionality of the software and related material nor shall the fact of release constitute any such warranty. Furthermore, the software is released on condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from its authorized or unauthorized use.