Introduction

Streamflow data represent the hydrologic response of a watershed as influenced by the changes in watershed conditions. Within the United States, streamflow measurements are mainly provided by the United States Geological Survey (USGS), or Water Management districts. Information on streamflow has a wide range of applications such as estimation of water yield, design of flood control structures, or understanding of the impact of past and future watershed characteristics on watershed response. In addition, streamflow data is one of the primary data required to calibrate and validate hydrologic watershed models , and thus rapid acquisition of streamflow data saves some of the time spent on collection of data needed by the watershed modelers. Below is a description of steps that can be adapted to download streamflow data from the USGS website using available packages within python.

Step 1: Import the required packages - Install the packages if needed.

There are three python libraries that need to be imported as described in the code below. The python Pandas and numpy are used in the manipulation of streamflow data. The "hydrofunctions package" uses requests to extract streamflow data from USGS website, and imports it into python. Check out the documentation and capabilities of the hydrofunction package here.

# Import required packages

import hydrofunctions as hf

import pandas as pd

import numpy as np

Step2: Write a function to request streamflow data and manipulate the data for further processing.

Once the streamflow data has been downloaded from the USGS database, it needs some manipulation to make sure that it is consistent and can be used for further analysis if needed. The code below will extract the streamflow data for a single station and return data as data frame.

'''

A function streamflow_raw that extracts USGS streamflow data

Inputs:

station_id - USGS station Id

start_date - Start date

end_date - End date

Outputs:

Daily streamflow records

'''

def streamflow_raw (station_id,start_date, end_date):

# Extract streamflow from a gauge

flow_extract = hf.NWIS(str(station_id), 'dv', start_date, end_date, parameterCd='00060')

# Convert the data object to a data frame

raw_flow = flow_extract.get_data().df().reset_index()

# Add names to the data frame

raw_flow.columns = ['Date', 'Flow (cfs)', 'Code']

# set date as index

raw_flow.index = pd.to_datetime(raw_flow.Date)

# Exclude negative flow values if they exist and replace any negative values with nan if any

raw_flow.loc[raw_flow['Flow (cfs)']<0,'Flow (cfs)'] = np.nan

# Make sure that the dates are consistent

raw_flow_daily = raw_flow [['Flow (cfs)', 'Code']].resample('D').asfreq()

return (raw_flow_daily.round(2))

Step3: Test the function with the USGS streamflow gauge id USGS 03341500

Below is how the streamflow data looks within the USGS database. The commands used to extract streamflow data are shown in the code below.

"""

"""

# Test the Streamflow function

station_id = '03341500'

start_date = '2018-10-01'

end_date = '2020-10-19'

flow = streamflow_raw (station_id,start_date, end_date)

A data frame is generated after running the above code. At this point, the data frame can be exported as a csv file. or to a database. A visualization of the acquired streamflow data can performed to examine any inconsistences as shown below.