splitPeakCodes {MGBT}

Split the Peak Discharge Qualifications Codes into Separate Columns

Description

Split the U.S. Geological Survey (USGS) peak discharge qualifications codes (Asquith and others, 2017) in the peak_cd column of a peak-streamflow data retrieval from the USGS National Water Information System (NWIS) (U.S. Geological Survey, 2019) in a data.frame into separate columns of the input data.frame. The NWIS system stores all the codes within a single database field. It can be useful for graphical (plotPeaks) or other statistical study to have single logical variable for each of the codes, and such is the purpose of this function. Note because of the appearsSystematic field is based computations involving the water_yr (water year), this function needs the makeWaterYear to have been run first; however, the function will autodetect and call that function internally if needed and those effects are provided on the returned data.frame. (See also the inst/legend/ subdirectory of this package for a script to produce a legend as well as inst/legend/legend_camera.pdf, which has been dressed up in a vector graphics editing program.)

Usage

splitPeakCodes(x, all_peaks_na_okay=FALSE)

Arguments

x

A data.frame having a mandatory column titled peak_cd with discharge qualification codes. Except for a check on only one station being present in site_no column, no other information in x is consulted or otherwise used; and

all_peaks_na_okay

A logical controlling whether a test on all the peak values (peak_va) being NA is made and if all the peak values are missing, then NULL is returned. Because much of this package is built around working with real peak discharges, the default is to be rejectionary to gage-height only streamgages. However, the plotPeaks function does have logic to work out ways to make plots of gage-height only streamgages.

Value

The x as originally inputted is returned with the addition of these columns:

appearsSystematic

The appearsSystematic column produced by the splitPeakCodes function is intended to provide a type of canonical flag on which to subset the record, which can be important for many statistical procedures;

anyCodes

Are any of the codes that follow present for a given record (row, water year) in the input data;

isCode1

Is a discharge qualification code of 1 present for a given record—Streamflow is a maximum daily average;

isCode2

Is a discharge qualification code of 2 present for a given record—Streamflow is an estimate;

isCode3

Is a discharge qualification code of 3 present for a given record—Streamflow affected by dam failure;

isCode4

Is a discharge qualification code of 4 present for a given record—Streamflow is less than indicated value, which is the minimum recordable value at this site;

isCode5

Is a discharge qualification code of 5 present for a given record—Streamflow affected to an unknown degree by regulation or diversion;

isCode6

Is a discharge qualification code of 6 present for a given record—Streamflow is affected by regulation or diversion;

isCode7

Is a discharge qualification code of 7 present for a given record—Streamflow is a historical peak;

isCode8

Is a discharge qualification code of 8 present for a given record—Streamflow is actually greater than the indicated value;

isCode9

Is a discharge qualification code of 9 present—Streamflow is affected by snow melt, hurricane, ice-jam, or debris-dam breakup;

isCodeA

Is a discharge qualification code of A present for a given record—Year of occurrence is unknown or not exact;

isCodeB

Is a discharge qualification code of B present for a given record—Month or day of occurrence is unknown or not exact;

isCodeC

Is a discharge qualification code of C present for a given record—All or part of the record is affected by urbanization, mining, agricultural changes, channelization, or other anthropogenic activity;

isCodeD

Is a discharge qualification code of D present for a given record—Base streamflow changed during this year;

isCodeE

Is a discharge qualification code of E present for a given record—Only annual peak streamflow available for this year; and

isCodeO

Is a discharge qualification code of E present for a given record–Opportunistic value not from systematic data collection. By extension, the presence of this code will trigger the appearsSystematic to false even if the peak itself otherwise appears part of systematic record from the gap analysis.

Note

Concerning appearsSystematic: All records but missing discharges are assumed as systematic records unless the peak streamflows are missing or peaks have a code 7 but there are existing years on either side of individual peaks coded as 7. The logic also handles a so-called “roll-on” and “roll-off” of the data by only testing the leading or trailing year—except this becomes a problem if multiple stations are involved, so the code will return early with a warning. Importantly, it is possible that some code 7s can be flagged as systematic and these are not necessarily in error. Testing indicates that some USGS Water Science Centers (maintainers of databases) have historically slightly different tendencies in application of the code 7. The USGS NWIS database does not actually contain a field indicating that a peak was collected as part of systematic operation and hence that peak is part of an assumed random sample. Peaks with gage height only are flagged as nonsystematic by fiat—this might not be the best solution over all, but because virtually all statistics use the discharge column this seems okay (feature is subject to future changes).

Author(s)

W.H. Asquith

References

Asquith, W.H., Kiang, J.E., and Cohn, T.A., 2017, Application of at-site peak-streamflow frequency analyses for very low annual exceedance probabilities: U.S. Geological Survey Scientific Investigation Report 2017–5038, 93 p., doi: 10.3133/sir20175038.

U.S. Geological Survey, 2019, USGS water data for the Nation: U.S. Geological Survey National Water Information System database, accessed October 11, 2019, at doi: 10.5066/F7P55KJN.

See Also

makeWaterYear, plotPeaks

Examples

  # The dataRetrieval package is not required by MGBT algorithms.
  PK <- dataRetrieval::readNWISpeak("08167000", convertType=FALSE)
  PK <- splitPeakCodes(PK)
  names(PK) # See that the columns are there.