Python Flow Duration Curves

Python programs for streamflow analysis

Purpose of Web Page on Python Programs for Streamflow Analysis

The purpose of this web page is to present some Python programs that can be be used to show stream hydrographs and flow duration curves.  The page is technical and assumes basic knowledge of the Python language and surface water hydrology.  In addition to standard Python libraries, the United States Geological Survey (USGS) hyswap (Hydrologic Surface Water Analysis Package) package of python programs is used (Hamshaw, and others, 2024).  This page provides updated procedure for developing flow duration curves for streams in the United States.

Python Proceedure for Developing Streamflow Duration Curves

Download Streamflow Data From USGS StreamStats 

Stream gauging stations in the United States may be located by using the USGS StreamStats website (https://streamstats.usgs.gov/ss/).  The area of interest can be located on the StreamStats map and enlarged by zooming.  Clicking on a gage symbol provides access to data on the gage including the period of record.  For flow duration analysis, a long period of record is beneficial.  For stations with adequate periods of record, the USGS Station ID Number, and the Period of Record is needed for input to Python code for acquiring the streamflow data and producing a flow duration curve.

Use the USGS dataretreival package to get streamflow data from the gauge selected.  The python program in Attachment 1 is an example of script that will perform this retrieval and produce a text file and a binary file of the data.  The text file allows visual inspection of the data when opened in a text editor.

Inspect the Stream Hydrograph

The hydrograph for a stream may be produced from the data downloaded by using the Python program stream_hydrograph.py shown in Attachment 2.  The example chosen for entry into stream_hydrograph.py is Fountain Creek near Colorado Springs.  The hydrograph is shown in Figure 1.  

Figure1.  Stream hydrograph for Fountain Creek near Colorado Springs (ID: 07103700).

Produce a Flow Duration Curve

A flow duration curve may be produced by using USGS hyswap.   The code in Attachment 3 produces the flow duration curve for Fountain Creek near Colorado Springs (ID: 07103700) that is shown in Figure 2.   The hydrograph peaks above 200 cubic feet per second are not shown well on the flow duration curve.  This is a reason for plotting the stream hydrograph as well as the flow duration curve.

For more information on flow duration curves, see the non-technical page on flow duration curves.

Figure 2.  Flow duration curve for Fountain Creek near Colorado Springs for period 1958-04-07 to  2025-04-07   .

Attachment 1.  Python Program to Retreive NWIS Streamflow Data

'''

Author: Darrel Dunn.

USGS_data_rtv

This Python3 program retrieves streamflow data

from "siteno" starting on "startDT".

'''

from dataretrieval import nwis #dataretrieval is a USGS package.

import numpy as np

siteno = '07103700'# Enter the stream gage site number.

startDT = '1958-04-01'# Enter the start date for the data wanted,

df, md = nwis.get_dv(site=siteno, parameterCd='00060', startDT=startDT) 

#df means DataFrame.

if df is not None:

        print("Data retrieved successfully.")

        # Reset the index to make the date a column

        df = df.reset_index()#Adds a column of row numbers

        # Get the data as a NumPy array

        data_array = df.values

        #Print the NumPy array

        print("Data as NumPy array:")

        print(data_array)

        np.savetxt('hydro_data.txt', data_array, delimiter='\t', fmt='%s')  

        # Use string format. 

        print("Data saved to hydro_data.txt")

        # Save the NumPy array to a binary file (.npy format)

        np.save('hydro_data.npy', data_array)

        print("Data saved to hydro_data.npy")

else:

        print("No data retrieved for the specified parameters.")

print('End usgs_data_rtv')

Attachment 2.  Python Program to Produce a Hydrograph from Stramflow Data

'''

Author: Darrel Dunn

stream_hydrograph.py

This program imports hydro_data.py and produces a streamflow hydrograph.

'''

import numpy as np

import matplotlib.pyplot as plt

import matplotlib.dates as mdates

import pandas as pd  # Import pandas

# Load the NumPy array from the .npy file.

data_array = np.load('hydro_data.npy', allow_pickle=True)

print("Shape of data_array:", data_array.shape)

print("Columns in data_array:", data_array[0]) #print the first row, which contains the column headers

# Extract the streamflow (second column) and dates (fifth column)

streamflow = data_array[:, 2].astype(float)  # Ensure streamflow is numeric

dates = data_array[:, 0]

# Extract the site number from the fourth column to use in the title

site_number = data_array[0, 1]

# Convert dates to datetime objects

dates = pd.to_datetime(dates)

# Create the hydrograph plot

plt.figure(figsize=(12, 7))  # Adjust figure size as needed

plt.plot(dates, streamflow)

# Set labels and title

plt.xlabel('Date')

plt.ylabel('Streamflow, cubic feet per second')

plt.title(f'Streamflow Hydrograph for Site {site_number}')

# Format the x-axis dates

plt.gca().xaxis.set_major_formatter(mdates.DateFormatter('%Y-%m-%d'))

plt.gca().xaxis.set_major_locator(mdates.AutoDateLocator())

plt.xticks(rotation=45)  # Rotate x-axis labels for better readability

# Add gridlines for better visualization

plt.grid(True)

# Save the plot as a PNG file

plt.savefig('streamflow_hydrograph.png')

print('End stream_hydrograph.py')

Attachment 3.  Python Program for Hyswap Flow Duration Curve

'''

Author: Darrel Dunn

This Python3 program imports data from the USGS National Water Informatio System

(NWIS) for a stream station and plots a flow duration curve. 

It uses the USGS packages dataretrievel and hyswap.

'''

import dataretrieval

import numpy as np

import hyswap

from pylab import*

siteno = '07103700'# Get number from USGS SteaamStats.

df, md = dataretrieval.nwis.get_dv(site=siteno, parameterCd='00060',startDT='1958-04-07')

# df holds the daily streamflow record that is retreived and md is metadata.

# Parameter code 00060 represents dischage.

values = np.linspace(df['00060_Mean'].min(), df['00060_Mean'].max(), 10000)

# 10000 equally spaced values

exceedance_probabilities = hyswap.exceedance.calculate_exceedance_probability_from_values_multiple(

    values, df['00060_Mean'])

# plot

fig, ax = plt.subplots(figsize=(8, 8))

# plot the flow duration curve

ax = hyswap.plots.plot_flow_duration_curve(

    values, exceedance_probabilities, ax=ax,

    title=f'Flow Duration Curve for USGS Site {siteno}')

# Save an image of the plot

plt.savefig('FDC.png')

print('End hyswap_fdc') 

References for Python Flow Duration Curves Webpage

Hamshaw, S.D., Hariharan, J., Hinman, E.D., Sleckman, M.J., Stanish, L.F., (2024)  hyswap: A USGS software package for hydrologic data analysis, v1.0.0, doi: 10.5066/P13SKXA2.  🔗