Metadata-Version: 2.4
Name: pybfs
Version: 0.2.0
Summary: Python Baseflow Separation - A physically-based baseflow separation algorithm for hydrological analysis
Author: BYU Hydroinformatics
License: MIT
Project-URL: Homepage, https://github.com/BYU-Hydroinformatics/pybfs
Project-URL: Documentation, https://github.com/BYU-Hydroinformatics/pybfs
Project-URL: Repository, https://github.com/BYU-Hydroinformatics/pybfs
Project-URL: Issues, https://github.com/BYU-Hydroinformatics/pybfs/issues
Keywords: hydrology,baseflow,baseflow separation,streamflow,groundwater
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.19.0
Requires-Dist: pandas>=1.1.0
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: numba>=0.56.0
Requires-Dist: scipy>=1.5.0
Requires-Dist: statsmodels>=0.13.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.4.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
Dynamic: license-file

# PyBFS

PyBFS - Python Baseflow Separation

A Python implementation of physically-based Baseflow Separation algorithms for hydrological analysis. PyBFS uses a coupled surface-subsurface reservoir model to separate total streamflow into surface flow, baseflow, and direct runoff components.

## Features

- Physically-based baseflow separation using coupled reservoir models
- Forecast baseflow using initial conditions
- Comprehensive visualization tools
- Well-documented API with NumPy-style docstrings

## Installation

### From PyPI (recommended)

```bash
pip install pybfs
```

### From source

```bash
git clone https://github.com/BYU-Hydroinformatics/pybfs.git
cd pybfs
pip install .
```

### Development installation

```bash
git clone https://github.com/BYU-Hydroinformatics/pybfs.git
cd pybfs
pip install -e .
```

## Quick Start

```python
import pandas as pd
from pybfs import get_values_for_site, base_table, PyBFS, plot_baseflow_simulation

# Load streamflow data
streamflow_data = pd.read_csv('streamflow.csv')

# Load site parameters
params_df = pd.read_csv('site_parameters.csv')

# Get parameters for specific site
site_number = 2312200
basin_char, gw_hyd, flow = get_values_for_site(params_df, site_number)

# Extract parameters
area, lb, x1, wb, por = basin_char[0], basin_char[1], basin_char[2], basin_char[3], basin_char[4]
alpha, beta, ks, kb, kz = gw_hyd[0], gw_hyd[1], gw_hyd[2], gw_hyd[3], gw_hyd[4]

# Generate baseflow table
SBT = base_table(lb, x1, wb, beta, kb, streamflow_data, por)

# Run PyBFS baseflow separation
result = PyBFS(streamflow_data, SBT, basin_char, gw_hyd, flow)

# Visualize results
plot_baseflow_simulation(streamflow_data, result)
```

## Requirements

- Python 3.7 or higher
- numpy >= 1.19.0
- pandas >= 1.1.0
- matplotlib >= 3.3.0

## Documentation

Full documentation is available at: [Documentation](https://github.com/BYU-Hydroinformatics/pybfs)

## Paper data and reproduction scripts

The data and analysis scripts for the streamflow partitioning paper
(Webster-Esho et al., manuscript under review) live in a separate repository:
https://github.com/EniolaWebsterEsho/streamflow_separation_paper_2026

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](docs/contributing.md) for guidelines.

## Citation

If you use PyBFS in your research, please cite:

```
PyBFS - Python Baseflow Separation
BYU Hydroinformatics
https://github.com/BYU-Hydroinformatics/pybfs
```

## Support

For issues, questions, or contributions, please visit: https://github.com/BYU-Hydroinformatics/pybfs/issues
