pybaseflow

A comprehensive Python toolkit for baseflow separation from streamflow hydrographs.

pybaseflow implements 17 baseflow separation methods spanning four paradigms: recursive digital filters, graphical/interval methods, recession-based methods, and tracer-based methods. It also provides parameter estimation, USGS data retrieval, and a CMB-to-Eckhardt calibration bridge.

This project builds on the baseflow package by Xie et al. (2020), which implemented methods described in "Evaluation of typical methods for baseflow separation in the contiguous United States" (Journal of Hydrology, 583, 124628). pybaseflow extends that work with new methods (PART, CMB, BFlow, IHACRES), a unified filter architecture, modern packaging, and USGS data integration.

This project is funded by CIROH.

Install

pip install pybaseflow

Quick Start

import pybaseflow

# Load bundled sample data (USGS 01013500, Fish River, Maine)
data = pybaseflow.load_sample_data()
Q = data['Q']

# Run a single method
b = pybaseflow.eckhardt(Q, a=0.98, BFImax=0.8)

# Or fetch your own data from USGS NWIS
from pybaseflow.io import fetch_usgs
data = fetch_usgs('01013500', '2019-01-01', '2020-12-31')

Methods

Recursive Digital Filters

All recursive digital filters share a generalized core: b[t] = alpha * b[t-1] + beta * (Q[t] + gamma * Q[t-1])

gamma=0 family (linear reservoir based):

gamma=1 family (signal processing based):

Variable gamma (hybrid):

Graphical / Recession-Based Methods

Tracer-Based Methods

Recession Analysis

Parameter Estimation

import pybaseflow

data = pybaseflow.load_sample_data()
Q = data['Q']

# Estimate recession coefficient from the hydrograph
strict = pybaseflow.strict_baseflow(Q)
a = pybaseflow.recession_coefficient(Q, strict)

# Use the estimated recession coefficient with any filter
b = pybaseflow.eckhardt(Q, a, BFImax=0.8)
b = pybaseflow.chapman_maxwell(Q, a)
b = pybaseflow.willems(Q, a, w=0.5)

CMB Calibration Bridge

Use specific conductance data to calibrate Eckhardt's BFImax:

from pybaseflow.tracer import calibrate_eckhardt_from_cmb

cal = calibrate_eckhardt_from_cmb(Q, SC)
b = pybaseflow.eckhardt(Q, cal['a'], cal['BFImax'])

BFlow / SWAT Integration

result = pybaseflow.bflow(Q)
print(f"ALPHA_BF = {result['alpha_factor']:.4f}")  # for SWAT calibration
print(f"BFI = {result['BFI']:.3f}")
print(f"Baseflow days = {result['baseflow_days']:.1f}")

USGS Data Retrieval

from pybaseflow.io import fetch_usgs

# Fetch daily discharge
data = fetch_usgs('01013500', '2015-01-01', '2020-12-31')
Q = data['values']

# Fetch specific conductance (for CMB)
sc_data = fetch_usgs('01013500', '2015-01-01', '2020-12-31', parameter='sc')

License

MIT