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.5.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.5.0
File Size Uploaded Provenance Actions
hydrotoolbox-2.5.0.tar.gz 19.4 MB With provenance Details for hydrotoolbox-2.5.0.tar.gz

Built distribution (wheel)

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

Total release size: 37.9 MB

Release files / hydrotoolbox-2.5.0.tar.gz

Download URL hydrotoolbox-2.5.0.tar.gz
Size 19.4 MB
Tags Source
SHA-256 checksum
How to use checksums
3a0dfd9d62272d22e30ed54dc7c688b35b8235f5e4c8fc6635a66de8e3fcdcc3
BLAKE2b-256 checksum
How to use checksums
1bbd5d5f4f57f59cea8a6cabd9417ac677d3378b2ed63cb7201fae162c1f577f
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 13, 2026.

Transparency log

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

Download URL hydrotoolbox-2.5.0-py3-none-any.whl
Size 18.6 MB
Tags Python 3
SHA-256 checksum
How to use checksums
5629f78e2edaad47cc36871ae4b4780643d2d2c30e66a31eb8fc5433617f5132
BLAKE2b-256 checksum
How to use checksums
348ffd8c089fd631c44fbc6af7b621b7cb0455a5ad388e9ee72f3ac415b6d52f
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 13, 2026.

Transparency log

Security for hydrotoolbox 2.5.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.5.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 13, 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