Review of ciCalculations article
Package Review
This review is limited to the ciCalculations article. I did not assess the overall package documentation and functionality.
- Briefly describe any working relationship you have (had) with the package authors. I have discussed the package and its development with the authors several times.
-
As the reviewer I confirm that there are no conflicts of interest for me to review this work.
Estimated hours spent reviewing: 1
-
Should the author(s) deem it appropriate, I agree to be acknowledged as a package reviewer ("rev" role) in the package DESCRIPTION file.
Review Comments
The ciCalculations function works as described. I noticed that there is an asterisk on 'Water Year' in the title of the plot produced by plotConcHistBoot(seriesOut_2, CIAnnualResults)
, but not in the one produced by plotConcHistBoot(eList, CIAnnualResults)
. Is this related to the generalized flow normalization?
Add to example code:
library(EGRETci)
# Run in interactive mode
CIAnnualResults <- ciCalculations(eList,
nBoot = 10)
ciCalculations returns a data frame, but the user assigns it to a variable name. So I would omit the reference to the name 'CIAnnualResults'.
There are several typos, primarily missing punctuation, in the article. Revised text:
Function to calculate confidence bands for flow-normalized concentration or flow-normalized flux. It returns a data frame which is used as input to the functions plotConcHistBoot and plotFluxHistBoot which produce the graphical output.
Arguments
eList named list with at least the Daily, Sample, and INFO dataframes. Created from the EGRET package, after running modelEstimation.
startSeed setSeed value. Defaults to 494817. This is used to make repeatable output.
verbose logical specifying whether or not to display progress messag, default = TRUE
jitterOn logical, if TRUE, adds "jitter" to the data in an attempt to avoid some numerical problems. Default = FALSE. See Details below.
V numeric, a multiplier for addition of jitter to the data, default = 0.2. See Details below.
nBoot integer, number of times the bootstrap resampling and model estimating is done. Default is 100, but that will take a long time. Testing should initially be done using a smaller number like 10.
blockLength integer, number of days in each time block used for resampling data. 200 days has been found to be a good choice.
widthCI numeric, the width of the confidence intervals. 0.9 means a 90% confidence interval.
Value A data frame with the following columns: Year, mean decYear value for the year being reported; FNConcLow, the lower confidence limit for flow normalized concentration, in mg/L; FNConcHigh, the upper confidence limit for flow normalized concentration, in mg/L; FNFluxLow, the lower confidence limit for flow normalized flux, in kg; FNFluxLow, the lower confidence limit for flow normalized flux, in kg.
Details In some situations numerical problems are encountered in the bootstrap process, resulting in highly unreasonable spikes in the confidence intervals. The use of "jitter" can often prevent these problems, but should only be used when it is clearly needed. It adds a small amount of random "jitter" to the explanatory variables of the WRTDS model. The V parameter sets the scale of variation in the log discharge values. The standard deviation of the added jitter is V * standard deviation of Log Q. The default for V is 0.2. Larger values should generally be avoided, and smaller values may be sufficient.
Argument values suggested: To test the code, nBoot = 10 is sufficient, but for meaningful results nBoot = 100 or even nBoot = 500 are more appropriate. blockLength = 200. widthCI = 90 (90% confidence interval).