Metadata-Version: 2.4
Name: bfi_toolkit
Version: 0.1.0
Summary: A simple toolkit for baseflow separation and Baseflow Index (BFI) estimation from daily streamflow.
Author: Mohammad Ali Farmani
License: MIT
Project-URL: Homepage, https://github.com/mfarmani95/BFI-Toolkit
Project-URL: Source, https://github.com/mfarmani95/BFI-Toolkit
Project-URL: Issue Tracker, https://github.com/mfarmani95/BFI-Toolkit/issues
Keywords: hydrology,baseflow,BFI,streamflow,recession
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Hydrology
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: matplotlib
Dynamic: license-file

# 🌊 BFI-Toolkit

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 recession analysis, compute optimized decay parameters (*k*), and calculate the BFI — a key hydrologic metric for understanding watershed storage and runoff behavior.

---

## 📦 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=5, start_date="2020-01-01")

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.

