peakcheck

Name:
peakcheck - Graphically review peak-flow-file data

Information:

Peakcheck facilitates a review of the peaks in the peak flow file by creating a series of plots for each station and summary plots of the entire Water Science Center. Beginning in 2007 the Office of Surface Water started using it as part of all WSC Surface Water Reviews.

Five plots are generated by the script:

Plot 1: Stage-Discharge plot of Annual Peaks
All peaks with both stage and discharge in peak flow file are plotted
Peaks with the following Q codes are plotted in red with the code shown

: 2 - estimated
3 - dam failure
4 - discharge less than indicated value
7 - historic peak
8 - discharge greater than indicated value
9 - snowmelt, hurricane, ice-jam, dam break

Peaks with the following GH codes are plotted with outer black circle

: 1 - affected by backwater
3 - at different site or datum

Peaks with a GH code of 6 (datum changed) are plotted with outer orange circle
Other Q or GH codes are ignored.

This plot is intended to catch the following types of errors:

: (1) peaks that do not line up in the pattern of a reasonable rating (presuming a somewhat stable high end), thus pointing to the potential for input errors in GH or Q. Peaks that are way off the pattern should be have an outer black circle indicating they are from a different site or are affected by backwater. Otherwise they are suspect.
(2) potential incorrect usage of Q codes (dam failure, etc.)
(3) potential incorrect usage of GH code 6. My understanding is that usage of code 6 is variable. Some folks use the code 6 on all peaks prior to the datum change, some folks use it on all the peaks after the datum change, and some folks use it on only the first peak after the datum change. As has been noted by others, this is a bit of a mess. I just plot the peaks with a code 6 to help identify potential issues. If I saw a bunch of peaks that clearly defined two different "ratings" offset by one or more feet, I would expect to see at least one peak with a datum change flag (although it has been noted that there is a potential problem if one only flags the first peaks after the change and it is a secondary peak).

Plot 2: Time-series plot of annual peaks
All peaks with a discharge are plotted
Peaks with a code 5 (regulation to unknown degree) are plotted in blue
Peaks with a code 6 (known regulatory effect) are plotted in red
Peaks with a code 7 (historical peaks) are plotted with an outer black circle
The period of complete daily record is shown at the bottom

This plot is intended to catch the following types of errors:

: (1) Inconsistent usage of 5 and 6 codes over time (see station 01111500 in the below example)
(2) potential historical peak that is not "historical" or potential peak that should be historical (see station 01114500 in the below example)
(3) potential missing peaks - by comparison with the complete daily flows. It will be expected that sites might have a peak without a complete year of daily flows, but a complete year of daily flows should in most cases result in a peak.

Plots 3-4: Plot of Peak Flow vs. Daily Value
Peaks are plotted against the corresponding daily mean.
Both plots are the same, except that one include a date dag on the data to identify outliers. The other leaves the dates off for a clean look at the data.

This plot is intended to catch the following types of errors:

: (1) Input errors in the peak flow
(2) Input errors in the peak date

Plot 5: Scatterplot of ALL peaks for the state vs. drainage area
All peaks for all sites with a drainage area are plotted (contributing DA from the site file is used if it exists, otherwise DA)
To help identify the sites with outliers, the same plot is reproduced many times, with 10 sites identified and highlighted on each plot. The identified sites more one site to the right with each plot.

This plot is intended as an overall "envelope curve" for the entire WSC to help find outliers that are hydrologically unreasonable.

All reports generated are generated in pdf format and stored under the following names:

00_Peaks_stations_plots_XX (contains plots 1-4)
00_Peaks_DA_plots_XX (contains plot 5)

: where "XX" is the FIPS state code of the area selected

Usage:

Simply type "peakcheck" and answer the prompts. The script can either be run on a provided site list or will use an NWISWeb generated site list for a given State or State FIPS code. The script runs entirely off NWISWeb and is independent of the NWIS database. Thus it can be run for any location and not just the users home WSC.

Installation:

The script can be installed by unzipping the files in any Sun directory and making sure the script is executable (chmod +x peakcheck). It must be run out of the same directory it is installed to.

The following files are included and should be kept in the same directory as the script:

: peakcheck - main program script
peaks.header.pdf - header page of station output (plots 1-4) file
scatter.template.tkg2 - tkg2 template for plot 1
timeseries.template.tkg2 - tkg2 template for plot 2
dv.scatter.template.tkg2 - tkg2 template for plot 3
dv2.scatter.template.tkg2 - tkg2 template for plot 4
no.dv.scatter.template.tkg2 - tkg2 template for plots 3/4 when no DVs exist for site
da.scatter.template.tkg2 - tkg2 template for plot 5

The following files are included and can be removed once the ascii2pdf script has been installed (see the "Requirements" section below.

: PDF-Create-0.01.tar.gz - Perl module required for ascii2pdf script
ascii2pdf - script needed by peakcheck to convert ascii files to pdf
ascii2pdf.readme - instructions for loading ascii2pdf and required Perl module

Script Language:
ksh

Requirements:

Since it runs entirely off NWISWeb there are no specific user rights needed.
The following software packages which are not part of the core Sun packages are required:
wget: http://unix.usgs.gov/solaris/wget.html
ImageMagick: http://unix.usgs.gov/solaris/ImageMagick.html
ascii2pdf: To install 'ascii2pdf see "ascii2pdf.readme" in the script download package

Original Author(s): Joseph Nielsen, Office of Surface Water

: Note the original author is noted on this page for the purposes of giving credit only. Please address questions/comments to OSW (GS-W OSW Scripts@usgs.gov).

Known Problems/Limitations/Need Improvements:

Uses annual peaks only, as those are the only peaks available on NWISWeb
When running, the software produces a bus error and core dump or each plot generated. This is not due to a problem with the script, but rather a problem with tkg2 that has been tracked to issues with the underlying tkg2 programming language (Perl). Although disconcerting to see, the errors have been shown over several years to cause no problems with either the script output or the computer system it is run on. Peakcheck automatically removes the core files as they are created.
The check against complete years of daily record at the bottom of plot2 uses the annual stats retrieved from NWISWeb to find complete years because only complete years produce annual stats normally. However, if the annual stats period is cut off on NWISWeb (which would be because it is also cut off for the stats at the bottom of ADAPS DV tables) then those historic periods will be shown as not having DVs in the peakcheck output.

Scripts:

: Version 0.97: posted (5/6/10) - fixed bug related to multiple DV stat codes; peakcheck download (Zip file = 73K)

Back to Scripts

[an error occurred while processing this directive]