Required Data Frames

The following table provides definitions of the four data frames that constitute the named list eBoot

There is also a data frame called caseSetUp (created with the trendSetUp function), which contains a number of important parameters that define the way that the test was implemented. They are presented here.

Histograms

The function plotHistogramTrend plots a histogram of all of the trend magnitudes (expressed as percentage change over the period) from the full set of replicates created by running wBT. The function will plot either Flow-Normalized Concentration trends or Flow-Normalized Flux trends. The trend magnitudes for all the replicates are stored in the eBoot list. The first example workflow can be used to plot the two histograms: one for trends in Flow Normalized Concentration and one for Flow Normalized Flux.

A comment about the final argument in these functions: The default is xSeq = seq(-100,100,10). This means that the bins for the histogram will run from -100 to +100 in steps of 10 (the units are percentage change). This will almost certainly be too broad a set of bins, but the first run, with the xSeq left at its devault values (meaning that you can just leave it out of the argument list) will give you an idea of the true range that you need to consider. Then, run it again with a much tighter range that still includes all of the replicate trends. For example, suppose we see that the replicates seen in the first plot run tell us this: the lowest value is between -30 and -20 and the highest value is between 40 and 50, then when we give the command again we should say xSeq = seq(-30,50,10). If it turns out that all the values are much closer to zero we might use something like xSeq = seq(-15,5,5) so the bins are a width of 5 rather than 10. It is also a good idea to have the full width of the histogram include zero. For example, in the case where the values were all in the range of +20 to +70, you might use something like xSeq = seq(0,70,10). Note that if the desired output histogram needs to be smoother, then the original wBT run needs to set bootBreak to a larger value such as 100 or 200. The larger bootBreak is, the smoother the histogram will be.

Here is an example workflow where the analyst has already determined what a good xSeq argument might be.

library(EGRET)
library(EGRETci)

# Example data included in package:
eList <- Choptank_eList # Example data from EGRET package
eBoot <- Choptank_eBoot
caseSetUp <- Choptank_caseSetUp

#Concentration:
plotHistogramTrend(eList, eBoot, caseSetUp,  
                   flux=FALSE, xSeq = seq(-20,60,5))

#Flux
plotHistogramTrend(eList, eBoot, caseSetUp,
                   flux=TRUE, xSeq = seq(-20,60,5))

Alternatively, the two plots can be shown side-by-side using a workflow like this.

Use the par function to set up both functions to plot side-by-side:

par(mfrow=c(1,2))
plotHistogramTrend(eList, eBoot, caseSetUp, flux=FALSE,
                   printTitle=FALSE, ylim=c(0,0.07), xSeq=seq(-10,70,10))
plotHistogramTrend(eList, eBoot, caseSetUp, flux=TRUE,
                   printTitle=FALSE, ylim=c(0,0.07), xSeq=seq(-10,70,10))

# To return to figures printing in 1 row, 1 columns:
par(mfrow=c(1,1))                   

Introduction

The purpose here is to produce a graphic that looks just like those produced by plotConcHist or plotFluxHist but with the addition of confidence bands around the flow-normalized histories. There are two versions of the workflow for confidence bands, the first just uses a single computer core which means it takes a long time to run (jobs can take an hour or more), but it is simple to run. It uses the function ciCalculations and can be run interactively or in batch. Two scripts for that are provided below. It is best done in the Terminal or some other window, rather than in the console. If run in the console it will make it impossible for other work in R to take place while the job is running. The second way it can be done is using parallel computing in R. A script for that purpose is provided. It does require three extra packages be installed (foreach, doParallel, and iterators). It is also best to run this in the Terminal, because if it is run in the console, no other R work can be done while it is running.

Preliminary Steps

Regardless of the approach (single core or parallel) being taken to the computations, the user needs to set up any non-default values of the parameters for model estimation and period of analysis. For example:

If the period of analysis is to be anything other than a Water Year (paStart=10, paLong=12), the user must use the setPA function. For example if we want to do the analysis for the three months starting with April, the command would be eList <- setPA(eList, paStart = 4, paLong = 3).

If the desired value of windowY was 10 rather than the default value of 7, then the command needed would be eList$INFO$windowY <- 10, similar commands can be used for windowQ, windowS, minNumObs, minNumUncen and EdgeAdjust (see help page for modelEstimation).

It is imperative that the standard WRTDS trend analysis be run prior to running the code for the confidence bands. If the user has made changes in smoothing parameters or modified the data in any way since the last time modelEstimation was run, the standard running of modelEstimation must be done and the output saved as eList. The commands would be:

eList <- modelEstimation(eList)

Simple Workflow

This example workflow assumes that we use the default values for all of the model parameters and PA and uses the example eList provided in the package. Remember, this is a very long-running process:

library(EGRET)
library(EGRETci)

eList <- Choptank_eList

CIAnnualResults <- ciCalculations(eList)

save(eList,CIAnnualResults, file="CIAnnualResults.RData")

To run the ciCalculations function in batch mode, the only difference is that additional arguments are specified in the call to the function. For example the call to ciCalculations might read as follows:

CIAnnualResults <- ciCalculations(eList, nBoot = 100, blockLength = 200, widthCI = 90)

As long as all required arguments (nBoot, blockLength, and widthCI) are specified there will be no interaction needed.

Parallel Computing

Taking advantage of the foreach package to do parallel computing:

library(foreach)
library(doParallel)
library(iterators)
library(EGRET)
library(EGRETci)

eList <- Choptank_eList
eList <- modelEstimation(eList) 

nBoot <- 100
blockLength <- 200
coreOut <- 1 #Number of cores to leave out of processing tasks

widthCI <- 90
ciLower <- (50-(widthCI/2))/100
ciUpper <- (50+(widthCI/2))/100
probs <- c(ciLower,ciUpper)

nCores <- detectCores() - coreOut
cl <- makeCluster(nCores)
registerDoParallel(cl)
repAnnual <- foreach(n = 1:nBoot,.packages=c('EGRETci')) %dopar% {
   annualResults <- bootAnnual(eList, blockLength)  
}
stopCluster(cl)               

# save(repAnnual, file="repAnnual.RData")

CIAnnualResults <- ciBands(eList, repAnnual, probs)
save(eList,CIAnnualResults, file="CIAnnualResults.RData")

CI Result Plots

Regardless of the way that the computations are done the outputs that are needed for the graphics are contained in eList and CIAnnualResults (which in either script will end up in a file called CIAnnualResults.RData). Once that file is loaded the graphics can be produced using the functions plotConcHistBoot and plotFluxHistBoot. Each of these functions only require two arguments (eList and CIAnnualResults). However, the user can specify a number of other arguments. These other arguments are the same ones used in the plotConcHist and plotFluxHist functions in the base EGRET package.

The user can also view a table of the confidence interval values shown in these graphics simply by using the command CIAnnualResults (fluxes will be in units if kg/day).

Here is a script for producing these graphics, using the example eList and CIAnnualResults data frames included in the package.

eList <- Choptank_eList

CIAnnualResults <- Choptank_CIAnnualResults

plotConcHistBoot(eList, CIAnnualResults)

plotFluxHistBoot(eList, CIAnnualResults)