# hydroutils
[](https://pypi.python.org/pypi/hydroutils)
[](https://anaconda.org/conda-forge/hydroutils)
[](https://pyup.io/repos/github/OuyangWenyu/hydroutils)
[](https://pypi.org/project/hydroutils/)
[](https://opensource.org/licenses/MIT)
**A comprehensive collection of utility functions for hydrological modeling and analysis**
Hydroutils is a Python package designed for hydrological modeling workflows, providing statistical analysis, data visualization, file handling, time period operations and unit conversion, specifically tailored for hydrological research and applications.
**This package is still under development, and the API is subject to change.**
- **Free software**: MIT license
- **Documentation**: https://OuyangWenyu.github.io/hydroutils
- **Source Code**: https://github.com/OuyangWenyu/hydroutils
- **PyPI Package**: https://pypi.org/project/hydroutils/
## ✨ Features
### 📊 Statistical Analysis (`hydro_stat`)
- **Dynamic Metric Functions**: Automatically generated statistical functions (NSE, RMSE, MAE, etc.)
- **Multi-dimensional Analysis**: Support for 2D/3D arrays for basin-scale analysis
- **HydroErr Integration**: Standardized hydrological metrics through HydroErr package
- **NaN Handling**: Flexible strategies ('no', 'sum', 'mean') for missing data
- **Runtime Metric Addition**: Add custom metrics dynamically with `add_metric()`
### 📈 Visualization (`hydro_plot`)
- **Geospatial Plotting**: Cartopy integration for map-based visualizations
- **Chinese Font Support**: Automatic font configuration for Chinese text rendering
- **Statistical Plots**: ECDF, box plots, heatmaps, correlation matrices
- **Hydrological Specializations**: Flow duration curves, unit hydrographs, precipitation plots
- **Customizable Styling**: Extensive configuration options for colors, styles, and formats
### 📁 File Operations (`hydro_file`)
- **JSON Serialization**: NumPy array support with `NumpyArrayEncoder`
- **Cloud Storage**: S3 and MinIO integration for remote data access
- **ZIP Handling**: Nested ZIP file extraction and management
- **Cache Management**: Automatic cache directory creation and management
- **Async Operations**: Asynchronous data retrieval capabilities
### ⏰ Time Period (`hydro_time`)
- **UTC Calculations**: Timezone offset computation from coordinates
- **Date Parsing**: Flexible date string parsing and manipulation
- **Time Range Operations**: Intersection, generation, and validation
- **Interval Detection**: Automatic time interval identification
### 🏷️ Unit Conversion (`hydro_units`)
- **Streamflow Units**: Comprehensive unit conversion for hydrological variables
- **Time Interval Detection**: Automatic detection and validation of time intervals
- **Unit Compatibility**: Validation functions for unit consistency
- **Pint Integration**: Physical units handling with pint and pint-xarray
### 🌊 Event Analysis (`hydro_event`)
- **Hydrological Event Detection**: Flood event identification
- **Event Characterization**: Duration, magnitude, and timing analysis
### ☁️ Cloud Integration (`hydro_s3`)
- **AWS S3 Support**: Direct integration with Amazon S3 services
- **MinIO Compatibility**: Local and private cloud storage solutions
- **Credential Management**: Secure credential handling and configuration
### 📝 Logging (`hydro_log`)
- **Rich Console Output**: Colored and formatted console logging
- **Progress Tracking**: Advanced progress bars and status indicators
- **Debug Support**: Comprehensive debugging and error reporting
## 🚀 Quick Start
### Installation
```bash
# Install from PyPI
pip install hydroutils
# Install with development dependencies using uv (recommended)
pip install uv
uv add hydroutils
# For development setup
git clone https://github.com/OuyangWenyu/hydroutils.git
cd hydroutils
uv sync --all-extras --dev
```
### Basic Usage
```python
import hydroutils
import numpy as np
# Statistical Analysis
obs = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
sim = np.array([1.1, 2.1, 2.9, 3.9, 5.1])
# Calculate Nash-Sutcliffe Efficiency
nse_value = hydroutils.nse(obs, sim)
print(f"NSE: {nse_value:.3f}")
# Multiple metrics at once
metrics = hydroutils.stat_error(obs, sim)
print(f"RMSE: {metrics['rmse']:.3f}")
print(f"MAE: {metrics['mae']:.3f}")
# Visualization
import matplotlib.pyplot as plt
fig, ax = hydroutils.plot_ecdf([obs, sim],
labels=['Observed', 'Simulated'],
colors=['blue', 'red'])
plt.show()
```
## 🛠️ Development
### Setting Up Development Environment
```bash
# Clone the repository
git clone https://github.com/OuyangWenyu/hydroutils.git
cd hydroutils
# Install UV (modern Python package manager)
pip install uv
# Setup development environment
uv sync --all-extras --dev
```
### Development Commands
```bash
# Run tests
uv run pytest # Basic test run
uv run pytest --cov=hydroutils # With coverage
make test-cov # With HTML coverage report
# Code formatting and linting
uv run black . # Format code
uv run ruff check . # Lint code
uv run ruff check --fix . # Fix linting issues
make format # Format and lint together
# Type checking
uv run mypy hydroutils
make type-check
# Documentation
uv run mkdocs serve # Serve docs locally
make docs-serve
# Build and release
uv run python -m build # Build package
make build
```
### Project Structure
```
hydroutils/
├── hydroutils/
│ ├── __init__.py # Package initialization and exports
│ ├── hydro_event.py # Hydrological event analysis
│ ├── hydro_file.py # File I/O and cloud storage
│ ├── hydro_log.py # Logging and console output
│ ├── hydro_plot.py # Visualization functions
│ ├── hydro_s3.py # AWS S3 and MinIO integration
│ ├── hydro_stat.py # Statistical analysis engine
│ ├── hydro_time.py # Time series utilities
│ └── hydro_units.py # Unit conversion and validation
├── tests/ # Comprehensive test suite
├── docs/ # MkDocs documentation
├── pyproject.toml # Modern Python project config
├── Makefile # Development convenience commands
└── uv.lock # UV package manager lock file
```
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](docs/contributing.md) for details.
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests and linting (`make check-all`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
## 📖 Documentation
Comprehensive documentation is available at [https://OuyangWenyu.github.io/hydroutils](https://OuyangWenyu.github.io/hydroutils), including:
- **API Reference**: Complete function and class documentation
- **User Guide**: Step-by-step tutorials and examples
- **Contributing Guide**: Development setup and contribution guidelines
- **FAQ**: Frequently asked questions and troubleshooting
## 🏗️ Requirements
- **Python**: >=3.10
- **Core Dependencies**: numpy, pandas, matplotlib, seaborn
- **Scientific Computing**: scipy, HydroErr, numba
- **Visualization**: cartopy (for geospatial plots)
- **Cloud Storage**: boto3, minio, s3fs
- **Utilities**: tqdm, rich, xarray, pint
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- **HydroErr**: For standardized hydrological error metrics
- **Cookiecutter**: Project template from [giswqs/pypackage](https://github.com/giswqs/pypackage)
- **Scientific Python Ecosystem**: NumPy, SciPy, Matplotlib, Pandas
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/OuyangWenyu/hydroutils/issues)
- **Discussions**: [GitHub Discussions](https://github.com/OuyangWenyu/hydroutils/discussions)
- **Email**: wenyuouyang@outlook.com
---
**Made with ❤️ for the hydrology community**
Raw data
{
"_id": null,
"home_page": null,
"name": "hydroutils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Wenyu Ouyang <wenyuouyang@outlook.com>",
"keywords": "hydrology, hydroutils, modeling, statistics, utilities",
"author": null,
"author_email": "Wenyu Ouyang <wenyuouyang@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/ce/ce/4ef3af2f2bd5afcd4ba35bccd761f7aa8a8f44e7acf6f173849955ac544e/hydroutils-0.1.0.tar.gz",
"platform": null,
"description": "# hydroutils\n\n[](https://pypi.python.org/pypi/hydroutils)\n[](https://anaconda.org/conda-forge/hydroutils)\n[](https://pyup.io/repos/github/OuyangWenyu/hydroutils)\n[](https://pypi.org/project/hydroutils/)\n[](https://opensource.org/licenses/MIT)\n\n**A comprehensive collection of utility functions for hydrological modeling and analysis**\n\nHydroutils is a Python package designed for hydrological modeling workflows, providing statistical analysis, data visualization, file handling, time period operations and unit conversion, specifically tailored for hydrological research and applications.\n\n**This package is still under development, and the API is subject to change.**\n\n- **Free software**: MIT license\n- **Documentation**: https://OuyangWenyu.github.io/hydroutils\n- **Source Code**: https://github.com/OuyangWenyu/hydroutils\n- **PyPI Package**: https://pypi.org/project/hydroutils/\n\n## \u2728 Features\n\n### \ud83d\udcca Statistical Analysis (`hydro_stat`)\n- **Dynamic Metric Functions**: Automatically generated statistical functions (NSE, RMSE, MAE, etc.) \n- **Multi-dimensional Analysis**: Support for 2D/3D arrays for basin-scale analysis\n- **HydroErr Integration**: Standardized hydrological metrics through HydroErr package\n- **NaN Handling**: Flexible strategies ('no', 'sum', 'mean') for missing data\n- **Runtime Metric Addition**: Add custom metrics dynamically with `add_metric()`\n\n### \ud83d\udcc8 Visualization (`hydro_plot`)\n- **Geospatial Plotting**: Cartopy integration for map-based visualizations\n- **Chinese Font Support**: Automatic font configuration for Chinese text rendering\n- **Statistical Plots**: ECDF, box plots, heatmaps, correlation matrices\n- **Hydrological Specializations**: Flow duration curves, unit hydrographs, precipitation plots\n- **Customizable Styling**: Extensive configuration options for colors, styles, and formats\n\n### \ud83d\udcc1 File Operations (`hydro_file`)\n- **JSON Serialization**: NumPy array support with `NumpyArrayEncoder`\n- **Cloud Storage**: S3 and MinIO integration for remote data access\n- **ZIP Handling**: Nested ZIP file extraction and management\n- **Cache Management**: Automatic cache directory creation and management\n- **Async Operations**: Asynchronous data retrieval capabilities\n\n### \u23f0 Time Period (`hydro_time`)\n- **UTC Calculations**: Timezone offset computation from coordinates\n- **Date Parsing**: Flexible date string parsing and manipulation\n- **Time Range Operations**: Intersection, generation, and validation\n- **Interval Detection**: Automatic time interval identification\n\n### \ud83c\udff7\ufe0f Unit Conversion (`hydro_units`)\n- **Streamflow Units**: Comprehensive unit conversion for hydrological variables\n- **Time Interval Detection**: Automatic detection and validation of time intervals\n- **Unit Compatibility**: Validation functions for unit consistency\n- **Pint Integration**: Physical units handling with pint and pint-xarray\n\n### \ud83c\udf0a Event Analysis (`hydro_event`)\n- **Hydrological Event Detection**: Flood event identification\n- **Event Characterization**: Duration, magnitude, and timing analysis\n\n### \u2601\ufe0f Cloud Integration (`hydro_s3`)\n- **AWS S3 Support**: Direct integration with Amazon S3 services\n- **MinIO Compatibility**: Local and private cloud storage solutions\n- **Credential Management**: Secure credential handling and configuration\n\n### \ud83d\udcdd Logging (`hydro_log`)\n- **Rich Console Output**: Colored and formatted console logging\n- **Progress Tracking**: Advanced progress bars and status indicators\n- **Debug Support**: Comprehensive debugging and error reporting\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\n# Install from PyPI\npip install hydroutils\n\n# Install with development dependencies using uv (recommended)\npip install uv\nuv add hydroutils\n\n# For development setup\ngit clone https://github.com/OuyangWenyu/hydroutils.git\ncd hydroutils\nuv sync --all-extras --dev\n```\n\n### Basic Usage\n\n```python\nimport hydroutils\nimport numpy as np\n\n# Statistical Analysis\nobs = np.array([1.0, 2.0, 3.0, 4.0, 5.0])\nsim = np.array([1.1, 2.1, 2.9, 3.9, 5.1])\n\n# Calculate Nash-Sutcliffe Efficiency\nnse_value = hydroutils.nse(obs, sim)\nprint(f\"NSE: {nse_value:.3f}\")\n\n# Multiple metrics at once\nmetrics = hydroutils.stat_error(obs, sim)\nprint(f\"RMSE: {metrics['rmse']:.3f}\")\nprint(f\"MAE: {metrics['mae']:.3f}\")\n\n# Visualization\nimport matplotlib.pyplot as plt\nfig, ax = hydroutils.plot_ecdf([obs, sim], \n labels=['Observed', 'Simulated'],\n colors=['blue', 'red'])\nplt.show()\n```\n\n## \ud83d\udee0\ufe0f Development\n\n### Setting Up Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/OuyangWenyu/hydroutils.git\ncd hydroutils\n\n# Install UV (modern Python package manager)\npip install uv\n\n# Setup development environment\nuv sync --all-extras --dev\n```\n\n### Development Commands\n\n```bash\n# Run tests\nuv run pytest # Basic test run\nuv run pytest --cov=hydroutils # With coverage\nmake test-cov # With HTML coverage report\n\n# Code formatting and linting\nuv run black . # Format code\nuv run ruff check . # Lint code\nuv run ruff check --fix . # Fix linting issues\nmake format # Format and lint together\n\n# Type checking\nuv run mypy hydroutils\nmake type-check\n\n# Documentation\nuv run mkdocs serve # Serve docs locally\nmake docs-serve\n\n# Build and release\nuv run python -m build # Build package\nmake build\n```\n\n### Project Structure\n\n```\nhydroutils/\n\u251c\u2500\u2500 hydroutils/\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization and exports\n\u2502 \u251c\u2500\u2500 hydro_event.py # Hydrological event analysis\n\u2502 \u251c\u2500\u2500 hydro_file.py # File I/O and cloud storage\n\u2502 \u251c\u2500\u2500 hydro_log.py # Logging and console output\n\u2502 \u251c\u2500\u2500 hydro_plot.py # Visualization functions\n\u2502 \u251c\u2500\u2500 hydro_s3.py # AWS S3 and MinIO integration\n\u2502 \u251c\u2500\u2500 hydro_stat.py # Statistical analysis engine\n\u2502 \u251c\u2500\u2500 hydro_time.py # Time series utilities\n\u2502 \u2514\u2500\u2500 hydro_units.py # Unit conversion and validation\n\u251c\u2500\u2500 tests/ # Comprehensive test suite\n\u251c\u2500\u2500 docs/ # MkDocs documentation\n\u251c\u2500\u2500 pyproject.toml # Modern Python project config\n\u251c\u2500\u2500 Makefile # Development convenience commands\n\u2514\u2500\u2500 uv.lock # UV package manager lock file\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](docs/contributing.md) for details.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests and linting (`make check-all`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## \ud83d\udcd6 Documentation\n\nComprehensive documentation is available at [https://OuyangWenyu.github.io/hydroutils](https://OuyangWenyu.github.io/hydroutils), including:\n\n- **API Reference**: Complete function and class documentation\n- **User Guide**: Step-by-step tutorials and examples\n- **Contributing Guide**: Development setup and contribution guidelines\n- **FAQ**: Frequently asked questions and troubleshooting\n\n## \ud83c\udfd7\ufe0f Requirements\n\n- **Python**: >=3.10\n- **Core Dependencies**: numpy, pandas, matplotlib, seaborn\n- **Scientific Computing**: scipy, HydroErr, numba\n- **Visualization**: cartopy (for geospatial plots)\n- **Cloud Storage**: boto3, minio, s3fs\n- **Utilities**: tqdm, rich, xarray, pint\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- **HydroErr**: For standardized hydrological error metrics\n- **Cookiecutter**: Project template from [giswqs/pypackage](https://github.com/giswqs/pypackage)\n- **Scientific Python Ecosystem**: NumPy, SciPy, Matplotlib, Pandas\n\n## \ud83d\udcde Support\n\n- **Issues**: [GitHub Issues](https://github.com/OuyangWenyu/hydroutils/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/OuyangWenyu/hydroutils/discussions)\n- **Email**: wenyuouyang@outlook.com\n\n---\n\n**Made with \u2764\ufe0f for the hydrology community**",
"bugtrack_url": null,
"license": "MIT",
"summary": "A collection of commonly used util functions in hydrological modeling",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/OuyangWenyu/hydroutils/issues",
"Changelog": "https://github.com/OuyangWenyu/hydroutils/blob/main/CHANGELOG.md",
"Documentation": "https://ouyangwenyu.github.io/hydroutils/",
"Homepage": "https://github.com/OuyangWenyu/hydroutils",
"Repository": "https://github.com/OuyangWenyu/hydroutils.git"
},
"split_keywords": [
"hydrology",
" hydroutils",
" modeling",
" statistics",
" utilities"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c6c7b4ac0c61e452c263e10b495c8f7dfa812a878622bc58b15a7dc2606942b1",
"md5": "a231aa3a2c89db4c211ff5bacf76bce0",
"sha256": "be160af5a85d96d9dea85ce0ccf7a019ad269c109228779e9aec0aa4295cf722"
},
"downloads": -1,
"filename": "hydroutils-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a231aa3a2c89db4c211ff5bacf76bce0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 65333,
"upload_time": "2025-10-28T01:24:13",
"upload_time_iso_8601": "2025-10-28T01:24:13.525392Z",
"url": "https://files.pythonhosted.org/packages/c6/c7/b4ac0c61e452c263e10b495c8f7dfa812a878622bc58b15a7dc2606942b1/hydroutils-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cece4ef3af2f2bd5afcd4ba35bccd761f7aa8a8f44e7acf6f173849955ac544e",
"md5": "ae6df7b8cd48e3ab2e291b191512c09f",
"sha256": "17272415c5b6020846f0cf526a56eb26f74a8ac2d501cc97543f3832aeccefa5"
},
"downloads": -1,
"filename": "hydroutils-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ae6df7b8cd48e3ab2e291b191512c09f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 94104,
"upload_time": "2025-10-28T01:24:15",
"upload_time_iso_8601": "2025-10-28T01:24:15.225441Z",
"url": "https://files.pythonhosted.org/packages/ce/ce/4ef3af2f2bd5afcd4ba35bccd761f7aa8a8f44e7acf6f173849955ac544e/hydroutils-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-28 01:24:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OuyangWenyu",
"github_project": "hydroutils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hydroutils"
}
JSON
