hydrotoolbox 2.3.1__tar.gz → 2.4.0__tar.gz

hydrotoolbox-2.4.0/.github/workflows/pypi-package.yml

@@ -0,0 +1,49 @@
+---
+# This workflow will install Python dependencies, run tests and lint with
+# a variety of Python versions For more information see:
+# https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: PyPI package tests
+
+on:  # yamllint disable-line rule:truthy
+    push:
+        branches: [main]
+    pull_request:
+        branches: [main]
+    workflow_dispatch:
+
+jobs:
+    tests:
+        uses: ./.github/workflows/tests.yml
+
+    pypi-publish:
+        needs: tests
+        runs-on: ubuntu-latest
+        environment: release
+        name: upload release to PyPI
+
+        permissions:
+            # IMPORTANT: this permission is mandatory for trusted publishing
+            id-token: write
+
+        steps:
+            - name: Checkout source
+              uses: actions/checkout@v7
+              with:
+                  submodules: recursive
+
+            - name: Build sdist and wheel
+              run: |
+                  python -m pip install build
+                  python -m build
+
+            - name: Download artifact
+              uses: actions/download-artifact@v8
+              with:
+                  path: dist
+                  merge-multiple: true
+
+            - name: Publish package distributions to PyPI
+              uses: pypa/gh-action-pypi-publish@release/v1
+              with:
+                  skip-existing: true

{hydrotoolbox-2.3.1 → hydrotoolbox-2.4.0}/.github/workflows/tests.yml

@@ -43,12 +43,12 @@ jobs:
 
         steps:
             - name: Checkout repository
-              uses: actions/checkout@v6
+              uses: actions/checkout@v7
               with:
                   submodules: recursive
 
             - name: Set up Python ${{ matrix.python-versions }}
-              uses: actions/setup-python@v6
+              uses: actions/setup-python@v7
               with:
                   python-version: ${{ matrix.python-versions }}
 
@@ -73,6 +73,7 @@ jobs:
               uses: coverallsapp/github-action@v2
               with:
                   parallel: true
+                  fail-on-error: false
 
     finish:
         needs: test

hydrotoolbox-2.4.0/.pre-commit-config.yaml

@@ -0,0 +1,87 @@
+---
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+
+exclude: |
+    (?x)^(
+        .*\.dods|
+        .*\.dmr|
+        .*\.dmd|
+        .*\.wdm|
+        .*\.hbn
+        )$
+
+repos:
+    - repo: https://github.com/pre-commit/pre-commit-hooks
+      rev: v6.0.0
+      hooks:
+          - id: check-case-conflict
+          - id: check-docstring-first
+          - id: check-executables-have-shebangs
+          - id: check-json
+          - id: check-merge-conflict
+          - id: check-shebang-scripts-are-executable
+          - id: check-toml
+          - id: check-xml
+          - id: end-of-file-fixer
+            exclude: notebooks/tstoolbox_plot_bash.sh
+          - id: mixed-line-ending
+          - id: trailing-whitespace
+            exclude: notebooks/tstoolbox_plot_bash.sh
+
+    - repo: https://github.com/astral-sh/ruff-pre-commit
+      # Ruff version.
+      rev: v0.16.5
+      hooks:
+          # Run the linter.
+          - id: ruff
+            types_or: [python, pyi, jupyter]
+            args: [--fix]
+          # Run the formatter.
+          - id: ruff-format
+            types_or: [python, pyi, jupyter]
+
+    - repo: https://github.com/pappasam/toml-sort
+      rev: v0.24.4
+      hooks:
+          - id: toml-sort-fix
+            args: [--in-place, --spaces-indent-inline-array, '4']
+
+    - repo: https://github.com/adrienverge/yamllint.git
+      rev: v1.38.0
+      hooks:
+          - id: yamllint
+            args: [--format, parsable, --strict]
+
+    - repo: https://github.com/jumanjihouse/pre-commit-hook-yamlfmt
+      rev: 0.2.3
+      hooks:
+          - id: yamlfmt
+
+    - repo: https://github.com/jumanjihouse/pre-commit-hooks
+      rev: 3.0.0
+      hooks:
+          - id: shellcheck
+            args: [-s, bash]
+
+    - repo: https://github.com/lovesegfault/beautysh
+      rev: v6.4.3
+      hooks:
+          - id: beautysh
+            args: [--indent-size, '4']
+
+    - repo: https://github.com/asottile/blacken-docs
+      rev: 1.20.0
+      hooks:
+          - id: blacken-docs
+
+    - repo: https://github.com/asottile/pyupgrade
+      rev: v3.21.2
+      hooks:
+          - id: pyupgrade
+
+    - repo: https://github.com/commitizen-tools/commitizen
+      rev: v4.18.0
+      hooks:
+          - id: commitizen
+            stages: [commit-msg]

{hydrotoolbox-2.3.1 → hydrotoolbox-2.4.0}/BADGES.rst

@@ -1,8 +1,3 @@
-.. image:: https://github.com/timcera/hydrotoolbox/actions/workflows/pypi-package.yml/badge.svg
-    :alt: Tests
-    :target: https://github.com/timcera/hydrotoolbox/actions/workflows/pypi-package.yml
-    :height: 20
-
 .. image:: https://img.shields.io/coveralls/github/timcera/hydrotoolbox
     :alt: Test Coverage
     :target: https://coveralls.io/r/timcera/hydrotoolbox?branch=master

{hydrotoolbox-2.3.1 → hydrotoolbox-2.4.0}/CHANGELOG.md

@@ -1,3 +1,15 @@
+## v2.4.0 (2026-11-09)
+
+### Feat
+
+- **baseflow_sep**: reworked all aspect of the baseflow_sep functionality
+
+## v2.3.2 (2026-06-11)
+
+### Fix
+
+- update toolbox_utils to support numpy 1.*
+
 ## v2.3.1 (2026-06-11)
 
 ## v2.3.0 (2026-06-09)

{hydrotoolbox-2.3.1 → hydrotoolbox-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hydrotoolbox
-Version: 2.3.1
+Version: 2.4.0
 Summary: Command line script and Python library for analysis of flow time-series.
 Author-email: Tim Cera <tim@cerazone.net>
 License: BSD-3-Clause
@@ -34,7 +34,7 @@ Requires-Dist: numpy
 Requires-Dist: pandas[excel]
 Requires-Dist: pint!=0.21.*
 Requires-Dist: pint-pandas
-Requires-Dist: pydantic
+Requires-Dist: pydantic>=2.0
 Requires-Dist: scipy
 Requires-Dist: tabulate
 Dynamic: license-file
@@ -70,6 +70,21 @@ 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

{hydrotoolbox-2.3.1 → hydrotoolbox-2.4.0}/README.rst

@@ -29,6 +29,21 @@ 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

hydrotoolbox-2.4.0/VERSION

@@ -0,0 +1 @@
+2.4.0

{hydrotoolbox-2.3.1 → hydrotoolbox-2.4.0}/docs/conf.py

@@ -10,6 +10,7 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+# Standard library imports
 import os
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -58,7 +59,8 @@ copyright = "2013, Tim Cera, P.E."
 # built documents.
 #
 # The short X.Y version.
-version = open(os.path.join(os.path.pardir, "VERSION")).readline().strip()
+with open(os.path.join(os.path.pardir, "VERSION"), encoding="ascii") as vers:
+    version = vers.readline().strip()
 # The full version, including alpha/beta/rc tags.
 release = version
 

{hydrotoolbox-2.3.1 → hydrotoolbox-2.4.0}/pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
     "pandas[excel]",
     "pint!=0.21.*",
     "pint-pandas",
-    "pydantic",
+    "pydantic >= 2.0",
     "scipy",
     "tabulate"
 ]
@@ -62,18 +62,38 @@ documentation = "https://timcera.bitbucket.io/hydrotoolbox/docs/index.html#hydro
 github = "https://github.com/timcera/hydrotoolbox"
 
 [tool.commitizen]
+multiline = true
 name = "cz_conventional_commits"
 tag_format = "v$version"
 update_changelog_on_bump = true
-version = "2.3.1"
+version = "2.4.0"
 version_files = ["VERSION"]
 
 [tool.isort]
 profile = "black"
 
+[tool.jupytext]
+formats = "auto:percent"
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 
+[tool.ruff]
+exclude = [
+    "src/hydrotoolbox/toolbox_utils"
+]
+fix = true
+
+[tool.ruff.lint]
+extend-select = ["I"]
+
+[tool.ruff.lint.isort.import-heading]
+first-party = "First party imports"
+future = "Future imports"
+local-folder = "Local folder imports"
+standard-library = "Standard library imports"
+third-party = "Third party imports"
+
 [tool.setuptools]
 include-package-data = true
 license-files = ["LICENSE.txt"]

{hydrotoolbox-2.3.1 → hydrotoolbox-2.4.0}/src/hydrotoolbox/__init__.py

@@ -1,6 +1,7 @@
 """Define hydrotoolbox package."""
 
 # Import main functions from hydrotoolbox module
+# First party imports
 from hydrotoolbox.hydrotoolbox import (
     about,
     exceedance_time,

{hydrotoolbox-2.3.1 → hydrotoolbox-2.4.0}/src/hydrotoolbox/baseflow/__init__.py

@@ -1,30 +1,31 @@
+# Standard library imports
 import os
 
 __all__ = [
+    "KGE",
     "boughton",
     "chapman",
     "chapman_maxwell",
     "eckhardt",
     "ewma",
     "five_day",
-    "fixed",
     "furey",
     "ihacres",
     "lyne_hollick",
-    "local",
-    "slide",
-    "strict",
-    "ukih",
-    "willems",
-    "recession_coefficient",
+    "maximum_BFI",
     "param_calibrate",
+    "recession_coefficient",
     "recession_period",
-    "maximum_BFI",
     "separation",
     "strict_baseflow",
-    "KGE",
+    "ukih",
+    "usgs_hysep_fixed",
+    "usgs_hysep_local",
+    "usgs_hysep_slide",
+    "willems",
 ]
 
+# Local folder imports
 from .comparison import KGE, strict_baseflow
 from .methods import (
     boughton,
@@ -33,14 +34,13 @@ from .methods import (
     eckhardt,
     ewma,
     five_day,
-    fixed,
     furey,
     ihacres,
-    local,
     lyne_hollick,
-    slide,
-    strict,
     ukih,
+    usgs_hysep_fixed,
+    usgs_hysep_local,
+    usgs_hysep_slide,
     willems,
 )
 from .param_estimate import (

{hydrotoolbox-2.3.1 → hydrotoolbox-2.4.0}/src/hydrotoolbox/baseflow/comparison.py

@@ -3,6 +3,7 @@ __all__ = [
     "strict_baseflow",
 ]
 
+# Third party imports
 import numpy as np
 
 
@@ -37,23 +38,41 @@ def strict_baseflow(Q):
 
 
 def KGE(simulations, evaluation):
-    """Original Kling-Gupta Efficiency (KGE) and its three components
-    (r, α, β) as per `Gupta et al., 2009
+    """Calculate original Kling-Gupta Efficiency (KGE).
+
+    The KGE and its components (r, α, β) follow `Gupta et al., 2009
     <https://doi.org/10.1016/j.jhydrol.2009.08.003>`_.
-    Note, all four values KGE, r, α, β are returned, in this order.
-    :Calculation Details:
-        .. math::
-           E_{\\text{KGE}} = 1 - \\sqrt{[r - 1]^2 + [\\alpha - 1]^2
-           + [\\beta - 1]^2}
-        .. math::
-           r = \\frac{\\text{cov}(e, s)}{\\sigma({e}) \\cdot \\sigma(s)}
-        .. math::
-           \\alpha = \\frac{\\sigma(s)}{\\sigma(e)}
-        .. math::
-           \\beta = \\frac{\\mu(s)}{\\mu(e)}
-        where *e* is the *evaluation* series, *s* is (one of) the
-        *simulations* series, *cov* is the covariance, *σ* is the
-        standard deviation, and *μ* is the arithmetic mean.
+
+    Parameters
+    ----------
+    simulations : array_like
+        Simulated values, with time along the first axis.
+    evaluation : array_like
+        Observed values, with time along the first axis.
+
+    Returns
+    -------
+    float or ndarray
+        KGE for each series.
+
+    Notes
+    -----
+    .. math::
+       E_{\\text{KGE}} = 1 - \\sqrt{[r - 1]^2 + [\\alpha - 1]^2
+       + [\\beta - 1]^2}
+
+    .. math::
+       r = \\frac{\\text{cov}(e, s)}{\\sigma({e}) \\cdot \\sigma(s)}
+
+    .. math::
+       \\alpha = \\frac{\\sigma(s)}{\\sigma(e)}
+
+    .. math::
+       \\beta = \\frac{\\mu(s)}{\\mu(e)}
+
+    Here *e* is the *evaluation* series, *s* is (one of) the
+    *simulations* series, *cov* is the covariance, *σ* is the
+    standard deviation, and *μ* is the arithmetic mean.
     """
     # calculate error in timing and dynamics r
     # (Pearson's correlation coefficient)

hydrotoolbox-2.4.0/src/hydrotoolbox/baseflow/general_form.py

@@ -0,0 +1,77 @@
+# Third party imports
+import numpy as np
+from scipy.signal import lfilter
+
+# First party imports
+from hydrotoolbox.baseflow.utils import BaseflowInitialMethod, _init_baseflow
+
+
+def general_form_digital_filter(
+    flow, alpha, beta, gamma, delta=1, b0_method: BaseflowInitialMethod = "zi", k=None
+):
+    """
+    Use a general form digital filter given coefficients alpha, beta, gamma, and delta.
+
+    The filter is defined by the difference equation::
+
+        bf[t] = alpha * bf[t-1] + beta * (delta * flow[t] + gamma * flow[t-1])
+
+        group baseflow terms on left side...
+
+        bf[t] - alpha * bf[t-1] = beta * delta * flow[t] + beta * gamma * flow[t-1]
+
+    The scipy lfilter takes "b" and "a" using the equation::
+
+        sum for k=0 to N (a[k]*bf[t-k]) = sum for k=0 to M (b[k]*flow[t-k])
+
+        Since N and M are both 1, expands to...
+
+        a[0]*bf[t] + a[1]*bf[t-1] = b[0]*flow[t] + b[1]*flow[t-1]
+
+    Comparing reshaped equations give::
+
+        b = [beta*delta, beta*gamma]
+        a = [1, -alpha]
+
+    Parameters
+    ----------
+    flow : array_like
+        Input signal (e.g., streamflow time series).
+    alpha
+        Parameter for the previous baseflow value.
+    beta
+        Parameter for the current and previous total flow values.
+    gamma
+        Parameter for the previous total flow value.
+    delta : float, optional
+        Multiplier for the current total flow value (default is 1).
+    b0_method : {"Q0", "min", "LH", "zi"} or float, optional
+        Initial baseflow. "zi" uses the SciPy steady-state filter
+        initialization. Numeric strings are also accepted.
+    k : float, optional
+        Recession coefficient used when b0_method is "LH".
+
+    Returns
+    -------
+    baseflow
+        The filtered baseflow signal.
+    num_exceeds
+        The count of baseflow values that exceed the input flow.
+
+    Notes
+    -----
+    The selected initial value is used as the first unbounded filter output.
+    Clipping to the flow is applied after filtering, as for all other outputs.
+    """
+    b = [beta * delta, gamma * beta]
+    a = [1.0, -alpha]
+
+    b0 = _init_baseflow(
+        flow, b0_method, k=k, alpha=alpha, beta=beta, gamma=gamma, delta=delta
+    )
+    zi = np.array([b0 - b[0] * flow[0]])
+    bf = lfilter(b, a, flow, axis=0, zi=zi)[0]
+
+    num_exceeds = np.count_nonzero(bf > flow)
+    bf = np.clip(bf, a_min=0, a_max=flow)
+    return bf, num_exceeds

{hydrotoolbox-2.3.1 → hydrotoolbox-2.4.0}/src/hydrotoolbox/baseflow/methods/__init__.py

@@ -5,33 +5,29 @@ __all__ = [
     "eckhardt",
     "ewma",
     "five_day",
-    "fixed",
     "furey",
     "ihacres",
     "lyne_hollick",
-    "local",
-    "slide",
     "strict",
     "ukih",
+    "usgs_hysep_fixed",
+    "usgs_hysep_local",
+    "usgs_hysep_slide",
     "willems",
-    "f_Boughton",
-    "f_Eckhardt",
-    "f_Furey",
-    "f_Willems",
 ]
 
-from .boughton import boughton, f_Boughton
+# Local folder imports
+from .boughton import boughton
 from .chapman import chapman
 from .chapman_maxwell import chapman_maxwell
-from .eckhardt import eckhardt, f_Eckhardt
+from .eckhardt import eckhardt
 from .ewma import ewma
 from .five_day import five_day
-from .fixed import fixed
-from .furey import f_Furey, furey
+from .furey import furey
 from .ihacres import ihacres
-from .local import local
 from .lyne_hollick import lyne_hollick
-from .slide import slide
-from .strict import strict
 from .ukih import ukih
-from .willems import f_Willems, willems
+from .usgs_hysep_fixed import usgs_hysep_fixed
+from .usgs_hysep_local import usgs_hysep_local
+from .usgs_hysep_slide import usgs_hysep_slide
+from .willems import willems

hydrotoolbox-2.4.0/src/hydrotoolbox/baseflow/methods/boughton.py

@@ -0,0 +1,48 @@
+__all__ = [
+    "boughton",
+]
+
+# Third party imports
+import numpy as np
+
+# First party imports
+from hydrotoolbox.baseflow.general_form import general_form_digital_filter
+from hydrotoolbox.baseflow.param_estimate import param_calibrate, resolve_k
+from hydrotoolbox.baseflow.utils import BaseflowInitialMethod
+
+
+def _boughton(flow, k, C, b0_method: BaseflowInitialMethod = "zi"):
+    alpha = k / (1 + C)
+    beta = C / (1 + C)
+    gamma = 0.0
+    return general_form_digital_filter(
+        flow, alpha, beta, gamma, b0_method=b0_method, k=k
+    )
+
+
+def boughton(flow, k=None, C=None, b0_method: BaseflowInitialMethod = "zi"):
+    """Boughton double-parameter filter (Boughton, 2004).
+
+    Parameters
+    ----------
+    flow : ndarray
+        Streamflow.
+    k : float, optional
+        Recession coefficient, estimated if None.
+    C : float, optional
+        Filter parameter, calibrated if None.
+    b0_method : {"Q0", "min", "LH", "zi"} or float, optional
+        Initial baseflow method or value. "zi" uses SciPy filter
+        initialization. Numeric strings are also accepted.
+
+    Returns
+    -------
+    ndarray
+        Separated baseflow.
+    """
+    k = resolve_k(flow, k)
+    if C is None:
+        C = param_calibrate(
+            np.arange(0.001, 1, 0.001), _boughton, flow, k, b0_method=b0_method
+        )
+    return _boughton(flow, k, float(C), b0_method=b0_method)[0]

hydrotoolbox-2.4.0/src/hydrotoolbox/baseflow/methods/chapman.py

@@ -0,0 +1,35 @@
+__all__ = [
+    "chapman",
+]
+
+# First party imports
+from hydrotoolbox.baseflow.general_form import general_form_digital_filter
+from hydrotoolbox.baseflow.param_estimate import resolve_k
+from hydrotoolbox.baseflow.utils import BaseflowInitialMethod
+
+
+def chapman(flow, k=None, b0_method: BaseflowInitialMethod = "zi"):
+    """Chapman filter (Chapman, 1991).
+
+    Parameters
+    ----------
+    flow : ndarray
+        Streamflow.
+    k : float, optional
+        Recession coefficient, estimated if None.
+    b0_method : {"Q0", "min", "LH", "zi"} or float, optional
+        Initial baseflow method or value. "zi" uses SciPy filter
+        initialization. Numeric strings are also accepted.
+
+    Returns
+    -------
+    ndarray
+        Separated baseflow.
+    """
+    k = resolve_k(flow, k)
+    alpha = (3 * k - 1) / (3 - k)
+    beta = (1 - k) / (3 - k)
+    gamma = 1.0
+    return general_form_digital_filter(
+        flow, alpha, beta, gamma, b0_method=b0_method, k=k
+    )[0]