Requesting Peak Discharges

It is possible to request a list of each year’s largest flood using the USGS’s Peak Discharge service. This list of annual peak discharges is perfect for doing a flood frequency analysis: you can calculate recurrence intervals and plot a flood frequency graph using these data.

The data provided by the USGS peak service are based on a ‘water year’, which starts on October 1st and ends in the last moments of September. This unusual definition for the start of the year is standard practice in US hydrology: September/October often marks the lowest flows of the year for much of the country, so it is less likely that there will be a large flood that spans the end of one year and continues on into the new year. As an example of the problems that we are trying to avoid by using a ‘water year’, imagine the largest flood in a decade peaking in the last days of December. As the water slowly receeds, it may still be quite high on January 1st. The tail end of last year’s flood may well be the highest discharge of the whole next year! This would interfere with our statistical assumptions about each flood event. By setting the end of the year/start of the year to the low-flow season, we mostly avoid double-counting floods without any extra processing.

[1]:
import hydrofunctions as hf
[2]:
output = hf.peaks('01541200')
Retrieving annual peak discharges for site # 01541200  from  https://nwis.waterdata.usgs.gov/nwis/peak?site_no=01541200&agency_cd=USGS&format=rdb

Our new ‘output’ is a hydroRDB object. It has several useful properties, including:

  • .table, which returns a dataframe of the data

  • .header, which is the original descriptive header provided by the USGS. It lists and describes the variables in the dataset.

  • .columns, which is a list of the column names

  • .dtypes, which is a list of the data types and column widths for each variable in the USGS RDB format.

If you print or evaluate the hydroRDB object, it will return a tuple of the header and dataframe table, like this:

[3]:
output
[3]:

#
# U.S. Geological Survey
# National Water Information System
# Retrieved: 2020-03-04 21:25:01 EST
#
# ---------------------------------- WARNING ----------------------------------------
# Some of the data that you have obtained from this U.S. Geological Survey database
# may not have received Director's approval. Any such data values are qualified
# as provisional and are subject to revision. Provisional data are released on the
# condition that neither the USGS nor the United States Government may be held liable
# for any damages resulting from its use.
#
# More data may be available offline.
# For more information on these data, contact USGS Water Data Inquiries.
# This file contains the annual peak streamflow data.
#
# This information includes the following fields:
#
# agency_cd Agency Code
# site_no USGS station number
# peak_dt Date of peak streamflow (format YYYY-MM-DD)
# peak_tm Time of peak streamflow (24 hour format, 00:00 - 23:59)
# peak_va Annual peak streamflow value in cfs
# peak_cd Peak Discharge-Qualification codes (see explanation below)
# gage_ht Gage height for the associated peak streamflow in feet
# gage_ht_cd Gage height qualification codes
# year_last_pk Peak streamflow reported is the highest since this year
# ag_dt Date of maximum gage-height for water year (if not concurrent with peak)
# ag_tm Time of maximum gage-height for water year (if not concurrent with peak
# ag_gage_ht maximum Gage height for water year in feet (if not concurrent with peak
# ag_gage_ht_cd maximum Gage height code
#
# Sites in this file include:
# USGS 01541200 WB Susquehanna River near Curwensville, PA
#
# Peak Streamflow-Qualification Codes(peak_cd):
# 1 ... Discharge is a Maximum Daily Average
# 2 ... Discharge is an Estimate
# 3 ... Discharge affected by Dam Failure
# 4 ... Discharge less than indicated value,
# which is Minimum Recordable Discharge at this site
# 5 ... Discharge affected to unknown degree by
# Regulation or Diversion
# 6 ... Discharge affected by Regulation or Diversion
# 7 ... Discharge is an Historic Peak
# 8 ... Discharge actually greater than indicated value
# 9 ... Discharge due to Snowmelt, Hurricane,
# Ice-Jam or Debris Dam breakup
# A ... Year of occurrence is unknown or not exact
# Bd ... Day of occurrence is unknown or not exact
# Bm ... Month of occurrence is unknown or not exact
# C ... All or part of the record affected by Urbanization,
# Mining, Agricultural changes, Channelization, or other
# F ... Peak supplied by another agency
# O ... Opportunistic value not from systematic data collection
# R ... Revised
#
# Gage height qualification codes(gage_ht_cd,ag_gage_ht_cd):
# 1 ... Gage height affected by backwater
# 2 ... Gage height not the maximum for the year
# 3 ... Gage height at different site and(or) datum
# 4 ... Gage height below minimum recordable elevation
# 5 ... Gage height is an estimate
# 6 ... Gage datum changed during this year
# 7 ... Debris, mud, or hyper-concentrated flow
# 8 ... Gage height tidally affected
# Bd ... Day of occurrence is unknown or not exact
# Bm ... Month of occurrence is unknown or not exact
# F ... Peak supplied by another agency
# R ... Revised
#
#

agency_cd site_no peak_tm peak_va peak_cd gage_ht gage_ht_cd year_last_pk ag_dt ag_tm ag_gage_ht ag_gage_ht_cd
peak_dt
1956-07-03 USGS 01541200 NaN 10200 NaN 10.89 NaN NaN NaN NaN NaN NaN
1957-04-06 USGS 01541200 NaN 9240 NaN 10.44 NaN NaN NaN NaN NaN NaN
1958-05-08 USGS 01541200 NaN 4800 NaN 7.66 NaN NaN NaN NaN NaN NaN
1959-01-22 USGS 01541200 NaN 12500 NaN 12.12 NaN NaN NaN NaN NaN NaN
1960-03-31 USGS 01541200 NaN 10400 NaN 11.03 NaN NaN NaN NaN NaN NaN
1961-02-26 USGS 01541200 NaN 12100 NaN 11.62 NaN NaN NaN NaN NaN NaN
1962-02-24 USGS 01541200 NaN 9000 NaN 10.10 NaN NaN NaN NaN NaN NaN
1963-03-18 USGS 01541200 NaN 9000 NaN 10.00 2,3 NaN 1963-03-06 NaN 11.50 1.0
1964-03-10 USGS 01541200 NaN 15700 NaN 14.19 NaN NaN NaN NaN NaN NaN
1965-01-03 USGS 01541200 NaN 5840 NaN 8.34 2,3 NaN 1965-02-08 NaN 10.79 1.0
1966-02-20 USGS 01541200 NaN 4400 6.0 7.31 NaN NaN NaN NaN NaN NaN
1967-03-07 USGS 01541200 NaN 4010 6.0 7.28 NaN NaN NaN NaN NaN NaN
1968-04-10 USGS 01541200 NaN 7120 6.0 9.28 NaN NaN NaN NaN NaN NaN
1969-04-24 USGS 01541200 NaN 4780 6.0 7.34 NaN NaN NaN NaN NaN NaN
1970-04-08 USGS 01541200 NaN 5640 6.0 7.77 NaN NaN NaN NaN NaN NaN
1971-02-23 USGS 01541200 NaN 5280 6.0 7.59 NaN NaN NaN NaN NaN NaN
1972-06-25 USGS 01541200 NaN 8590 6.0 11.40 NaN NaN NaN NaN NaN NaN
1973-02-03 USGS 01541200 NaN 4080 6.0 7.29 NaN NaN NaN NaN NaN NaN
1974-01-22 USGS 01541200 NaN 3960 6.0 6.84 NaN NaN NaN NaN NaN NaN
1975-03-03 USGS 01541200 NaN 5940 6.0 8.74 NaN NaN NaN NaN NaN NaN
1976-02-23 USGS 01541200 NaN 4720 6.0 7.62 NaN NaN NaN NaN NaN NaN
1977-07-23 USGS 01541200 NaN 5660 6.0 8.47 NaN NaN NaN NaN NaN NaN
1978-05-18 USGS 01541200 NaN 4920 6.0 7.80 NaN NaN NaN NaN NaN NaN
1979-03-07 USGS 01541200 NaN 5610 6.0 8.42 NaN NaN NaN NaN NaN NaN
1980-04-01 USGS 01541200 NaN 3650 6.0 6.78 NaN NaN NaN NaN NaN NaN
1981-02-23 USGS 01541200 NaN 5170 6.0 8.02 NaN NaN NaN NaN NaN NaN
1982-03-15 USGS 01541200 NaN 4330 6.0 7.29 NaN NaN NaN NaN NaN NaN
1983-06-21 USGS 01541200 NaN 4560 6.0 7.47 NaN NaN NaN NaN NaN NaN
1984-06-20 USGS 01541200 NaN 4980 6.0 7.82 NaN NaN NaN NaN NaN NaN
1985-04-02 USGS 01541200 NaN 4320 6.0 7.28 NaN NaN NaN NaN NaN NaN
... ... ... ... ... ... ... ... ... ... ... ... ...
1988-02-03 USGS 01541200 NaN 4210 6.0 7.26 NaN NaN NaN NaN NaN NaN
1989-06-23 USGS 01541200 NaN 4660 6.0 7.61 NaN NaN NaN NaN NaN NaN
1990-07-14 USGS 01541200 NaN 4290 6.0 7.32 NaN NaN NaN NaN NaN NaN
1990-12-19 USGS 01541200 NaN 4300 6.0 7.33 NaN NaN NaN NaN NaN NaN
1992-04-01 USGS 01541200 NaN 3370 6.0 6.61 NaN NaN NaN NaN NaN NaN
1993-04-07 USGS 01541200 NaN 5250 6.0 8.31 NaN NaN NaN NaN NaN NaN
1994-03-30 USGS 01541200 NaN 5390 6.0 8.23 NaN NaN NaN NaN NaN NaN
1994-11-28 USGS 01541200 NaN 3650 6.0 6.82 NaN NaN NaN NaN NaN NaN
1996-01-23 USGS 01541200 NaN 5890 6.0 8.68 NaN NaN NaN NaN NaN NaN
1997-05-26 USGS 01541200 NaN 5390 6.0 8.23 NaN NaN NaN NaN NaN NaN
1997-11-10 USGS 01541200 NaN 5690 6.0 8.49 NaN NaN NaN NaN NaN NaN
1999-01-26 USGS 01541200 NaN 5590 6.0 8.40 NaN NaN NaN NaN NaN NaN
1999-11-26 USGS 01541200 NaN 4220 6.0 7.20 NaN NaN NaN NaN NaN NaN
2000-10-18 USGS 01541200 NaN 3720 6.0 6.80 NaN NaN NaN NaN NaN NaN
2002-03-27 USGS 01541200 NaN 5610 6.0 8.42 NaN NaN NaN NaN NaN NaN
2003-01-01 USGS 01541200 NaN 4800 6.0 7.69 NaN NaN NaN NaN NaN NaN
2004-01-08 USGS 01541200 NaN 5700 6.0 8.50 NaN NaN NaN NaN NaN NaN
2005-01-13 USGS 01541200 NaN 5710 6.0 8.51 NaN NaN NaN NaN NaN NaN
2005-11-30 USGS 01541200 NaN 4310 6.0 7.27 NaN NaN NaN NaN NaN NaN
2006-11-17 USGS 01541200 NaN 5190 6.0 8.04 NaN NaN NaN NaN NaN NaN
2008-03-21 USGS 01541200 NaN 4650 6.0 7.55 NaN NaN NaN NaN NaN NaN
2008-12-20 USGS 01541200 NaN 5170 6.0 8.03 NaN NaN NaN NaN NaN NaN
2010-03-15 USGS 01541200 NaN 4860 6.0 7.74 NaN NaN NaN NaN NaN NaN
2011-09-11 USGS 01541200 NaN 5350 6.0 8.19 NaN NaN NaN NaN NaN NaN
2011-11-23 USGS 01541200 NaN 4460 6.0 7.39 NaN NaN NaN NaN NaN NaN
2013-06-27 USGS 01541200 NaN 4430 6.0 7.35 NaN NaN NaN NaN NaN NaN
2013-12-23 USGS 01541200 08:45 4120 6.0 7.06 NaN NaN NaN NaN NaN NaN
2015-03-16 USGS 01541200 10:15 5240 6.0 8.08 NaN NaN NaN NaN NaN NaN
2016-02-03 USGS 01541200 23:00 2860 6.0 5.94 NaN NaN NaN NaN NaN NaN
2016-12-19 USGS 01541200 NaN 5130 6.0 7.98 NaN NaN NaN NaN NaN NaN

62 rows × 12 columns