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