# 🌊 BFI-Toolkit
[](https://test.pypi.org/project/bfi-toolkit/)
[](https://pypi.org/project/bfi-toolkit/)
[](LICENSE)
[](https://doi.org/10.1029/2024WR039479)
A lightweight and flexible Python package for estimating **Baseflow** and **Baseflow Index (BFI)** from streamflow time series.
This toolkit provides a simple, efficient way to:
- Separate baseflow using forward/backward recession analysis
- Compute optimized decay parameters (*k*)
- Calculate **BFI** — a key hydrologic metric for understanding watershed storage and runoff behavior.
---
## 📄 Associated Research
This toolkit was developed as part of the work presented in:
> **Farmani, M. A.**, Tavakoly, A., Behrangi, A., Qiu, Y., Gupta, A., Jawad, M., Yousefi Sohi, H., Zhang, X., Geheran, M., Niu, G.-Y. (2025).
> *Improving Streamflow Predictions in the Arid Southwestern United States Through Understanding of Baseflow Generation Mechanisms.*
> *Water Resources Research.* [https://doi.org/10.1029/2024WR039479](https://doi.org/10.1029/2024WR039479)
© Author(s) 2025. This work is distributed under the Creative Commons Attribution 4.0 License.
---
## 🧠 Scientific Background
This toolkit builds on established methods for baseflow estimation using recession analysis and BFI calculation.
The **underlying baseflow recession concept** is based on:
> van Dijk, A. I. J. M. (2010). *Climate and terrain factors explaining streamflow response and recession in Australian catchments.*
> **Hydrology and Earth System Sciences**, 14(1), 159–169.
> [https://doi.org/10.5194/hess-14-159-2010](https://doi.org/10.5194/hess-14-159-2010)
---
## 📦 Installation
### From PyPI (when released)
```bash
pip install bfi-toolkit
```
### From source (development version)
```bash
git clone https://github.com/mfarmani95/BFI-Toolkit.git
cd BFI-Toolkit
pip install -e .
```
This installs the package in **editable mode**, so any code edits are reflected immediately without reinstalling.
---
## ⚡️ Quick Start
```python
import numpy as np
from bfi_toolkit import compute_bfi
# Example: simple synthetic streamflow data
streamflow = np.array([5, 5, 5, 6, 7, 6, 5.8, 5.6, 5.4, 5.2, 5, 4.9, 4.8])
result = compute_bfi(streamflow, day_after_peak=2,min_events=1,min_pairs=3, start_date="2020-01-01")
# day_after_peak : Number of days to exclude after each detected runoff peak.
# min_events : Minimum number of runoff events required.
# min_pairs : Minimum number of Q–Q* pairs required.
print("Optimized k:", result["k"])
print("BFI:", result["bfi"])
print("Baseflow head:\n", result["baseflow"].head())
```
✅ **Supported input types:**
- Python `list`
- `numpy.ndarray`
- `pandas.DataFrame` (must contain column `QQ`)
- `torch.Tensor` *(optional, if PyTorch installed)*
---
## 🧪 Development Setup
### Option 1: with pip
```bash
git clone https://github.com/mfarmani95/BFI-Toolkit.git
cd BFI-Toolkit
python -m venv .venv
source .venv/bin/activate # (Windows: .venv\Scripts\activate)
pip install -r requirements-dev.txt
```
### Option 2: with Conda (recommended)
```bash
git clone https://github.com/mfarmani95/BFI-Toolkit.git
cd BFI-Toolkit
conda env create -f environment.yml
conda activate bfi-toolkit
```
Then:
```bash
make dev # install dev dependencies
make test # run tests
```
---
## 🧰 Useful Makefile Commands
| Command | Description |
|----------------------|---------------------------------------------|
| `make install` | Install package in editable mode |
| `make dev` | Install dev dependencies |
| `make test` | Run test suite with pytest |
| `make format` | Auto-format code with Black |
| `make lint` | Run static checks with Ruff |
| `make build` | Build distribution package |
| `make upload-test` | Upload to TestPyPI |
| `make upload` | Upload to PyPI |
---
## 🧠 Contributing
We welcome contributions from the community 🙌
1. **Fork** the repository
2. Create a **feature branch**
3. Commit your changes with clear messages
4. Add or update tests if needed
5. Submit a **Pull Request**
Before submitting:
```bash
make format
make lint
make test
```
---
## 🧭 Features
- ✅ Supports multiple input formats (NumPy, Pandas, PyTorch, lists)
- 📉 Flexible dry period filtering with `day_after_peak`
- ⚙️ Optimized decay constant estimation (*k*)
- 💧 Baseflow separation using forward/backward recession
- 📊 Automatic BFI calculation
- 🧰 Clean modular structure (core, utils, optimization, baseflow)
- 🧪 Fully testable with `pytest`
---
## 📝 Citation
If you use this toolkit in your research or operational projects, please cite:
> Farmani, M. A. (2025). *BFI-Toolkit: A lightweight Python package for estimating baseflow and Baseflow Index (BFI)*.
> GitHub: [https://github.com/<your-username>/BFI-Toolkit](https://github.com/<your-username>/BFI-Toolkit)
---
## 📜 License
This project is licensed under the [MIT License](LICENSE).
You’re free to use, modify, and distribute it — just give credit where it’s due.
---
## 🚀 Roadmap
- [ ] Add uncertainty quantification for k estimates
- [ ] Add multi-resolution time series support (weekly, monthly)
- [ ] Add visualization module (hydrograph plotting)
- [ ] Add unit conversion utilities for different discharge formats
- [ ] Publish as official PyPI package
---
## 💧 Acknowledgements
Developed as part of ongoing hydrologic research by
**Mohammad Ali Farmani** — University of Arizona.
Inspired by the need for transparent, flexible, and efficient baseflow separation tools for hydrologic modeling and water resources applications.
Raw data
{
"_id": null,
"home_page": null,
"name": "bfi-toolkit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "hydrology, baseflow, BFI, streamflow, recession",
"author": "Mohammad Ali Farmani",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/bd/99/4153d7ca013db0bffe12e6e948637f0bf3eb447f514512b9769713ce0a78/bfi_toolkit-0.1.3.tar.gz",
"platform": null,
"description": "# \ud83c\udf0a BFI-Toolkit\n\n[](https://test.pypi.org/project/bfi-toolkit/)\n[](https://pypi.org/project/bfi-toolkit/)\n[](LICENSE)\n[](https://doi.org/10.1029/2024WR039479)\n\nA lightweight and flexible Python package for estimating **Baseflow** and **Baseflow Index (BFI)** from streamflow time series.\n\nThis toolkit provides a simple, efficient way to:\n- Separate baseflow using forward/backward recession analysis\n- Compute optimized decay parameters (*k*)\n- Calculate **BFI** \u2014 a key hydrologic metric for understanding watershed storage and runoff behavior.\n\n---\n\n## \ud83d\udcc4 Associated Research\n\nThis toolkit was developed as part of the work presented in:\n\n> **Farmani, M. A.**, Tavakoly, A., Behrangi, A., Qiu, Y., Gupta, A., Jawad, M., Yousefi Sohi, H., Zhang, X., Geheran, M., Niu, G.-Y. (2025). \n> *Improving Streamflow Predictions in the Arid Southwestern United States Through Understanding of Baseflow Generation Mechanisms.* \n> *Water Resources Research.* [https://doi.org/10.1029/2024WR039479](https://doi.org/10.1029/2024WR039479)\n\n\u00a9 Author(s) 2025. This work is distributed under the Creative Commons Attribution 4.0 License.\n\n\n---\n## \ud83e\udde0 Scientific Background\nThis toolkit builds on established methods for baseflow estimation using recession analysis and BFI calculation. \nThe **underlying baseflow recession concept** is based on:\n\n> van Dijk, A. I. J. M. (2010). *Climate and terrain factors explaining streamflow response and recession in Australian catchments.* \n> **Hydrology and Earth System Sciences**, 14(1), 159\u2013169. \n> [https://doi.org/10.5194/hess-14-159-2010](https://doi.org/10.5194/hess-14-159-2010)\n---\n\n\n## \ud83d\udce6 Installation\n\n### From PyPI (when released)\n```bash\npip install bfi-toolkit\n```\n\n### From source (development version)\n```bash\ngit clone https://github.com/mfarmani95/BFI-Toolkit.git\ncd BFI-Toolkit\npip install -e .\n```\n\nThis installs the package in **editable mode**, so any code edits are reflected immediately without reinstalling.\n\n---\n\n## \u26a1\ufe0f Quick Start\n\n```python\nimport numpy as np\nfrom bfi_toolkit import compute_bfi\n\n# Example: simple synthetic streamflow data\nstreamflow = np.array([5, 5, 5, 6, 7, 6, 5.8, 5.6, 5.4, 5.2, 5, 4.9, 4.8])\n\nresult = compute_bfi(streamflow, day_after_peak=2,min_events=1,min_pairs=3, start_date=\"2020-01-01\")\n\n# day_after_peak : Number of days to exclude after each detected runoff peak.\n# min_events : Minimum number of runoff events required.\n# min_pairs : Minimum number of Q\u2013Q* pairs required.\n\nprint(\"Optimized k:\", result[\"k\"])\nprint(\"BFI:\", result[\"bfi\"])\nprint(\"Baseflow head:\\n\", result[\"baseflow\"].head())\n```\n\n\u2705 **Supported input types:**\n- Python `list`\n- `numpy.ndarray`\n- `pandas.DataFrame` (must contain column `QQ`)\n- `torch.Tensor` *(optional, if PyTorch installed)*\n\n---\n\n## \ud83e\uddea Development Setup\n\n### Option 1: with pip\n```bash\ngit clone https://github.com/mfarmani95/BFI-Toolkit.git \ncd BFI-Toolkit\npython -m venv .venv\nsource .venv/bin/activate # (Windows: .venv\\Scripts\\activate)\npip install -r requirements-dev.txt\n```\n\n### Option 2: with Conda (recommended)\n```bash\ngit clone https://github.com/mfarmani95/BFI-Toolkit.git \ncd BFI-Toolkit\nconda env create -f environment.yml\nconda activate bfi-toolkit\n```\n\nThen:\n```bash\nmake dev # install dev dependencies\nmake test # run tests\n```\n\n---\n\n## \ud83e\uddf0 Useful Makefile Commands\n\n| Command | Description |\n|----------------------|---------------------------------------------|\n| `make install` | Install package in editable mode |\n| `make dev` | Install dev dependencies |\n| `make test` | Run test suite with pytest |\n| `make format` | Auto-format code with Black |\n| `make lint` | Run static checks with Ruff |\n| `make build` | Build distribution package |\n| `make upload-test` | Upload to TestPyPI |\n| `make upload` | Upload to PyPI |\n\n---\n\n## \ud83e\udde0 Contributing\n\nWe welcome contributions from the community \ud83d\ude4c \n\n1. **Fork** the repository \n2. Create a **feature branch** \n3. Commit your changes with clear messages \n4. Add or update tests if needed \n5. Submit a **Pull Request**\n\nBefore submitting:\n```bash\nmake format\nmake lint\nmake test\n```\n\n---\n\n## \ud83e\udded Features\n\n- \u2705 Supports multiple input formats (NumPy, Pandas, PyTorch, lists) \n- \ud83d\udcc9 Flexible dry period filtering with `day_after_peak` \n- \u2699\ufe0f Optimized decay constant estimation (*k*) \n- \ud83d\udca7 Baseflow separation using forward/backward recession \n- \ud83d\udcca Automatic BFI calculation \n- \ud83e\uddf0 Clean modular structure (core, utils, optimization, baseflow) \n- \ud83e\uddea Fully testable with `pytest`\n\n---\n\n## \ud83d\udcdd Citation\n\nIf you use this toolkit in your research or operational projects, please cite:\n\n> Farmani, M. A. (2025). *BFI-Toolkit: A lightweight Python package for estimating baseflow and Baseflow Index (BFI)*. \n> GitHub: [https://github.com/<your-username>/BFI-Toolkit](https://github.com/<your-username>/BFI-Toolkit)\n\n---\n\n## \ud83d\udcdc License\n\nThis project is licensed under the [MIT License](LICENSE). \nYou\u2019re free to use, modify, and distribute it \u2014 just give credit where it\u2019s due.\n\n---\n\n## \ud83d\ude80 Roadmap\n\n- [ ] Add uncertainty quantification for k estimates \n- [ ] Add multi-resolution time series support (weekly, monthly) \n- [ ] Add visualization module (hydrograph plotting) \n- [ ] Add unit conversion utilities for different discharge formats \n- [ ] Publish as official PyPI package\n\n---\n\n## \ud83d\udca7 Acknowledgements\n\nDeveloped as part of ongoing hydrologic research by \n**Mohammad Ali Farmani** \u2014 University of Arizona. \n\nInspired by the need for transparent, flexible, and efficient baseflow separation tools for hydrologic modeling and water resources applications.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple toolkit for baseflow separation and Baseflow Index (BFI) estimation from daily streamflow.",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/mfarmani95/BFI-Toolkit",
"Issue Tracker": "https://github.com/mfarmani95/BFI-Toolkit/issues",
"Source": "https://github.com/mfarmani95/BFI-Toolkit"
},
"split_keywords": [
"hydrology",
" baseflow",
" bfi",
" streamflow",
" recession"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1a1b83fec5189db9a059ce999d45fd3f06508231f090627979bc9c6792a3508c",
"md5": "e35afd4b54a37635939ea0be04ff4c40",
"sha256": "9f4226e11a23f2261ffab38a22f738958c4c0203aa0fa176c5c43a05d45f9732"
},
"downloads": -1,
"filename": "bfi_toolkit-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e35afd4b54a37635939ea0be04ff4c40",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 10385,
"upload_time": "2025-10-10T22:57:14",
"upload_time_iso_8601": "2025-10-10T22:57:14.968559Z",
"url": "https://files.pythonhosted.org/packages/1a/1b/83fec5189db9a059ce999d45fd3f06508231f090627979bc9c6792a3508c/bfi_toolkit-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bd994153d7ca013db0bffe12e6e948637f0bf3eb447f514512b9769713ce0a78",
"md5": "cada4106524b84050e365cf318808c10",
"sha256": "3cdafd5a16851071e22919563ec8ab48e27e79e1a3614045d7f38566730324f0"
},
"downloads": -1,
"filename": "bfi_toolkit-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "cada4106524b84050e365cf318808c10",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 12165,
"upload_time": "2025-10-10T22:57:15",
"upload_time_iso_8601": "2025-10-10T22:57:15.734757Z",
"url": "https://files.pythonhosted.org/packages/bd/99/4153d7ca013db0bffe12e6e948637f0bf3eb447f514512b9769713ce0a78/bfi_toolkit-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-10 22:57:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mfarmani95",
"github_project": "BFI-Toolkit",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "bfi-toolkit"
}
JSON
