baseflowx

A comprehensive Python toolkit for baseflow separation from streamflow hydrographs.

baseflowx 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.

Try it in the browser: Baseflow Explorer — pick any USGS gage on a map and compare every separation method side by side.

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). baseflowx 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 baseflowx

Quick Start

import baseflowx

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

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

# Or fetch your own data from USGS NWIS
from baseflowx.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 baseflowx

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

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

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

CMB Calibration Bridge

Use specific conductance data to calibrate Eckhardt's BFImax:

from baseflowx.tracer import calibrate_eckhardt_from_cmb

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

BFlow / SWAT Integration

result = baseflowx.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 baseflowx.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