pybaseflow 0.1.0__tar.gz

pybaseflow-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: pybaseflow
+Version: 0.1.0
+Summary: A comprehensive Python toolkit for baseflow separation
+Author: Nels Jones
+License-Expression: MIT
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: numba
+Requires-Dist: pandas
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: matplotlib; extra == "dev"
+
+# 🌟 baseflow
+baseflow is a Python package that provides a collection of functions for baseflow separation, which is the process of separating the baseflow component from the total streamflow. 
+
+
+This project is a copy of the [baseflow repository](https://github.com/xiejx5/baseflow) , which implements various baseflow separation methods described in the paper by Xie et al. (2020): "Evaluation of typical methods for baseflow separation in the contiguous United States" (Journal of Hydrology, 583, 124628. https://doi.org/10.1016/j.jhydrol.2020.124628).
+
+This project is funded by [CIROH](https://ciroh.ua.edu/) and aims to extend the functionality of the original baseflow package by adding new features and improvements. Our goal is to continuously enhance and maintain this package, keeping it up-to-date with the latest developments in baseflow separation techniques.
+
+For detailed usage instructions and examples, please refer to the [📖 documentation](https://baseflow.readthedocs.io/en/latest/)  🔥.
+
+## ⚡ Usage
+
+### Install
+```bash
+pip install baseflow
+```
+
+
+### Example
+```python
+import baseflow
+import pandas as pd
+
+df = pd.read_csv(baseflow.example, index_col=0)
+df_sta = pd.DataFrame(data=[[30, -28.4, 659], [-109.4, 33, 1611]],
+                      index=df.columns, columns=['lon', 'lat', 'area'])
+dfs, df_kge = baseflow.separation(df, df_sta, return_kge=True)
+print(f'Best Method:\n{df_kge.idxmax(axis=1)}')
+```
+
+
+## 🚀 Project Structure
+The directory structure of baseflow looks like this:
+```
+├── methods <- implements for 12 baseflow separation methods  
+│    
+├── separation <- compute baseflow and compare different separation methods  
+│    
+├── param_estimate <- estimates recession coefficient & backward and calibration approaches to estimate other parameters   
+│  
+├── comparison <- an evaluation criterion to compare different
+methods (KGE) & compute strict baseflow  
+│    
+└── utils <- helper functions
+```

pybaseflow-0.1.0/README.md

@@ -0,0 +1,45 @@
+# 🌟 baseflow
+baseflow is a Python package that provides a collection of functions for baseflow separation, which is the process of separating the baseflow component from the total streamflow. 
+
+
+This project is a copy of the [baseflow repository](https://github.com/xiejx5/baseflow) , which implements various baseflow separation methods described in the paper by Xie et al. (2020): "Evaluation of typical methods for baseflow separation in the contiguous United States" (Journal of Hydrology, 583, 124628. https://doi.org/10.1016/j.jhydrol.2020.124628).
+
+This project is funded by [CIROH](https://ciroh.ua.edu/) and aims to extend the functionality of the original baseflow package by adding new features and improvements. Our goal is to continuously enhance and maintain this package, keeping it up-to-date with the latest developments in baseflow separation techniques.
+
+For detailed usage instructions and examples, please refer to the [📖 documentation](https://baseflow.readthedocs.io/en/latest/)  🔥.
+
+## ⚡ Usage
+
+### Install
+```bash
+pip install baseflow
+```
+
+
+### Example
+```python
+import baseflow
+import pandas as pd
+
+df = pd.read_csv(baseflow.example, index_col=0)
+df_sta = pd.DataFrame(data=[[30, -28.4, 659], [-109.4, 33, 1611]],
+                      index=df.columns, columns=['lon', 'lat', 'area'])
+dfs, df_kge = baseflow.separation(df, df_sta, return_kge=True)
+print(f'Best Method:\n{df_kge.idxmax(axis=1)}')
+```
+
+
+## 🚀 Project Structure
+The directory structure of baseflow looks like this:
+```
+├── methods <- implements for 12 baseflow separation methods  
+│    
+├── separation <- compute baseflow and compare different separation methods  
+│    
+├── param_estimate <- estimates recession coefficient & backward and calibration approaches to estimate other parameters   
+│  
+├── comparison <- an evaluation criterion to compare different
+methods (KGE) & compute strict baseflow  
+│    
+└── utils <- helper functions
+```

pybaseflow-0.1.0/pybaseflow/__init__.py

@@ -0,0 +1,46 @@
+"""pybaseflow — a comprehensive Python toolkit for baseflow separation."""
+
+__version__ = "0.1.0"
+
+import csv
+from datetime import date
+from pathlib import Path
+
+import numpy as np
+
+from pybaseflow.separation import *  # noqa: F401,F403
+from pybaseflow.estimate import *  # noqa: F401,F403
+from pybaseflow.utils import *  # noqa: F401,F403
+from pybaseflow.tracer import cmb, estimate_endmembers, calibrate_eckhardt_from_cmb  # noqa: F401
+
+_DATA_DIR = Path(__file__).parent / 'data'
+
+
+def load_sample_data():
+    """Load the bundled Fish River sample dataset.
+
+    Returns daily discharge for USGS site 01013500 (Fish River near Fort Kent,
+    Maine) for 2019-2020.
+
+    Returns:
+        dict: Dictionary with keys:
+            - 'dates': numpy array of datetime.date objects
+            - 'Q': numpy array of discharge in ft³/s
+            - 'site_id': '01013500'
+            - 'units': 'ft3/s'
+    """
+    path = _DATA_DIR / 'fish_river.csv'
+    dates = []
+    values = []
+    with open(path, newline='') as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            dates.append(date.fromisoformat(row['date']))
+            val = row['discharge_cfs']
+            values.append(float(val) if val else np.nan)
+    return {
+        'dates': np.array(dates),
+        'Q': np.array(values, dtype=np.float64),
+        'site_id': '01013500',
+        'units': 'ft3/s',
+    }

pybaseflow-0.1.0/pybaseflow/data/README.md

@@ -0,0 +1,13 @@
+# Sample Data
+
+## fish_river.csv
+
+- **USGS Site**: 01013500 — Fish River near Fort Kent, Maine
+- **Period**: 2019-01-01 to 2020-12-31 (731 days)
+- **Parameter**: Daily mean discharge (ft³/s), NWIS parameter code 00060
+- **Source**: USGS National Water Information System (NWIS), https://waterdata.usgs.gov/nwis
+- **License**: US Government public domain
+
+This is a clean, unregulated headwater gauge with a strong seasonal signal
+(snowmelt peaks in spring, baseflow-dominated in late summer/fall), making
+it a good test case for baseflow separation methods.