Skip to main content
Tests Test Coverage Latest release BSD-3 clause license PyPI - Python Version

hydrotoolbox - Quick Guide

The hydrotoolbox is a Python script for hydrologic calculations and analysis or by function calls within Python. Uses pandas (http://pandas.pydata.org/) or numpy (http://numpy.scipy.org) for any heavy lifting.

The “baseflow_sep” code is based on the work of Xie et al. (2024) and Xie et al. (2020), from the code repository at https://github.com/xiejx5/baseflow. It was refactored to not use numba, and instead use scipy.signal.lfilter where possible, and to be more modular.

Xie, J., Liu, X., Jasechko, S., Berghuijs, W. R., Wang, K., Liu, C., Reichstein, M., Jung, M., & Koirala, S. (2024). Majority of global river flow sustained by groundwater. Nature Geoscience, 17(8), 770–777. https://doi.org/10.1038/s41561-024-01483-5

Xie, J., Liu, X., Wang, K., Yang, T., Liang, K., & Liu, C. (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

Requirements

  • python 3.10 or higher

Installation

pip

pip install hydrotoolbox

conda

conda install -c conda-forge hydrotoolbox

Usage - API

All functions return a PANDAS DataFrame. Input can be a CSV or TAB separated file, or a PANDAS DataFrame and is supplied to the function via the ‘input_ts’ keyword.

Simply import hydrotoolbox:

from hydrotoolbox import hydrotoolbox

# Then you could call the functions
ntsd = hydrotoolbox.baseflow_sep(method='boughton', input_ts='tests/test_fill_01.csv')

Usage - Command Line

All functions are available from the command line. The command line interface is a wrapper around the functions in the hydrotoolbox module. The command line arguments match one-to-one with the function arguments.

To get help for the command line interface, run:

hydrotoolbox --help

Which gives you the following output:

usage: hydrotoolbox [-h] [-v]
                    {baseflow_sep, recession, flow_duration, storm_events,
                    indices, exceedance_time, about} ...

positional arguments:
  {baseflow_sep,recession,flow_duration,storm_events,indices,exceedance_time,about}
    baseflow_sep        baseflow_sep subcommand
    recession           Recession coefficient.
    flow_duration       Flow duration.
    storm_events        Storm events.
    indices             Calculate hydrologic indices.
    exceedance_time     Calculate the time that a time series exceeds (or is
                        below) a threshold.
    about               Display version number and system information.

options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit

To get help for a specific subcommand, run:

hydrotoolbox <subcommand> --help

The default for all of the subcommands is to accept data from stdin (typically a pipe). If a subcommand accepts an input file for an argument, you can use “–input_ts=input_file_name.csv”, or to explicitly specify from stdin (the default) “–input_ts=’-‘”.

For the subcommands that output data it is printed to the screen and you can then redirect to a file.

Metadata

Release files for hydrotoolbox 2.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hydrotoolbox 2.4.0
File Size Uploaded Provenance Actions
hydrotoolbox-2.4.0.tar.gz 19.4 MB With provenance Details for hydrotoolbox-2.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hydrotoolbox 2.4.0
File Interpreter ABI Platform Actions
hydrotoolbox-2.4.0-py3-none-any.whl Python 3 none any Details for hydrotoolbox-2.4.0-py3-none-any.whl

Total release size: 37.9 MB

Release files / hydrotoolbox-2.4.0.tar.gz

Download URL hydrotoolbox-2.4.0.tar.gz
Size 19.4 MB
Tags Source
SHA-256 checksum
How to use checksums
d064985ba26ab6e27a727980c3c64b3d4f1c8ffa8d4e89777e2f0bb30a70a2e1
BLAKE2b-256 checksum
How to use checksums
0e24e72bc5560fc950ea8264e57ea13140f8b8e5d1268f1ce7a9e474f0006f24
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Release files / hydrotoolbox-2.4.0-py3-none-any.whl

Download URL hydrotoolbox-2.4.0-py3-none-any.whl
Size 18.6 MB
Tags Python 3
SHA-256 checksum
How to use checksums
973cbcf67578bc07d722d68a1d7d5796f9bc27965aa1ab38e0a1164ef9e66114
BLAKE2b-256 checksum
How to use checksums
f22844cbb53e08be43dccccd9e3c485bf009c8f380915e762ec569727cdb69e9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

Security for hydrotoolbox 2.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hydrotoolbox-2.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page