plotPeaks: Plot Peak Streamflows with Emphasis on Peak Discharge...
In wasquith-usgs/MGBT: Multiple Grubbs-Beck Low-Outlier Test

Description Usage Arguments Value Author(s) See Also Examples

Plot U.S. Geological Survey peak streamflows in peak_va and discharge qualifications codes in the peak_cd columns of a peak-streamflow data retrieval from the National Water Information System (NWIS). This code makes use of the add.log.axis function from the lmomco package, and because this is the only instance of this dependency, the lmomco package is treated as a suggested package and not as a dependency for the MGBT package. This function is used for the basis of the logarithmic plot within the plotFFQevol function.

This function accommodates the plotting of various nuances of the peak including less than (code 4), greater than (code 8), zero peaks (plotted by a green tick on the horizontal axis), and peaks that are missing but the gage height was available (plotted by a light-blue tick on the horizontal axis if the showGHyrs argument is set). So-called code 5, 6, and 7 peaks are plotted by the numeric code as the plotting symbol, and so-called code C peaks are plotted by the letter “C.” These codes are are summarized within splitPeakCodes. The greater symbology set is described in the directory MGBT/inst/legend of the package sources.

plotPeaks(x, codes=TRUE, lot=NULL, site="",
             xlab="", ylab="", xlim=NULL, ylim=NULL,
             xlim.inflate=TRUE, ylim.inflate=TRUE, aux.y=NULL,
             log.ticks=c(1, 2, 3, 5, 8),
             show48=FALSE, showDubNA=FALSE, showGHyrs=TRUE, ...)

`x`	A `data.frame` having a mandatory column titled `peak_va` and `peak_cd`. It is advised to have run `makeWaterYear` and `splitPeakCodes` first, but if columns resulting from those two functions are are not detected, then the water year column and code split are made internally but not returned;
`codes`	A logical to trigger use of character plotting characters and not symbols;
`lot`	The low-outlier threshold, but if omitted, then `MGBT` is triggered internally;
`site`	An optional character string for a plot title, and in practice, this is expected to be a streamgage location;
`xlab`	An optional x-label of the plot;
`ylab`	An optional y-label of the plot;
`xlim`	An optional x-limit of the plot;
`ylim`	An optional y-limit of the plot;
`xlim.inflate`	A logical to trigger nudging the horizontal axis left/right to the previous/future decade;
`ylim.inflate`	A logical to trigger nudging the vertical axis down/up to the nearest sane increment of log10-cycles. This inflation also includes a \pm0.01 log10-cycle adjustment to the lower and upper values of the limit. This ensures (say) that a 50,000 cubic feet per second maximum, which is on a sane increment, is nudged up enough to make the upper limit 60,000 instead. The point itself plots at 50,000 cfs;
`aux.y`	An optional set of values to pack into the data just ahead of the the vertical axis limits computation;
`log.ticks`	The argument `logs` of the `add.log.axis` function;
`show48`	A logical, if `codes` is set, will draw a “4” and “8” for those respective codes instead of a reddish dot;
`showDubNA`	A logical, if set, will draw a \pmhalf-year polygon for the water years having both `NA` discharge (`peak_va`) and `NA` gage height (`gage_ht`). To some analysts, it might be useful to study the degree of these double empty entries in contrast to just the records of such years not even being present in NWIS. Double empty entries could represent incomplete data handling on part of the USGS or inadvertently missing zero discharges for `peak_va`;
`showGHyrs`	A logical to trigger the light-blue special ticks for the water years having only gage height. The horizontal limits will be inflated accordingly if gage heights are outside the general discharge record; and
`...`	Additional arguments to pass to `plot`.

No values are returned; this function is used for its graphical side effects.

W.H. Asquith

makeWaterYear, splitPeakCodes, plotFFQevol

## Not run: 
  # Note that makeWaterYear() is not needed because splitPeakCodes() requires
  # the water_yr for gap analyses, and will call makeWaterYear() if it needs to.
  PK <- dataRetrieval::readNWISpeak("08167000", convertType=FALSE)
  PK <- splitPeakCodes(makeWaterYear(PK))
  plotPeaks(PK, codes=TRUE, showGHyrs=FALSE) # 
## End(Not run)

## Not run: 
  # An example with zero flows
  PK <- dataRetrieval::readNWISpeak("07148400", convertType=FALSE)
  PK <- MGBT::splitPeakCodes(PK)
  plotPeaks(PK, codes=TRUE,  showDubNA=TRUE) # 
## End(Not run)
  
## Not run: 
  PK <- dataRetrieval::readNWISpeak("08329935", convertType=FALSE)
  PK <- MGBT::splitPeakCodes(PK)
  plotPeaks(PK, codes=TRUE, showDubNA=TRUE) # 
## End(Not run)