hydrotoolbox 2.2.0__tar.gz → 2.3.0__tar.gz

{hydrotoolbox-2.2.0 → hydrotoolbox-2.3.0}/.pre-commit-config.yaml

@@ -29,7 +29,7 @@ repos:
 
     - repo: https://github.com/astral-sh/ruff-pre-commit
       # Ruff version.
-      rev: v0.15.6
+      rev: v0.15.16
       hooks:
           # Run the linter.
           - id: ruff
@@ -40,7 +40,7 @@ repos:
             types_or: [python, pyi, jupyter]
 
     - repo: https://github.com/pycqa/isort
-      rev: 8.0.1
+      rev: 9.0.0a3
       hooks:
           - id: isort
             name: isort (python)
@@ -52,7 +52,7 @@ repos:
             types: [pyi]
 
     - repo: https://github.com/pappasam/toml-sort
-      rev: v0.24.3
+      rev: v0.24.4
       hooks:
           - id: toml-sort-fix
             args: [--in-place, --spaces-indent-inline-array, '4']
@@ -91,7 +91,7 @@ repos:
           - id: pyupgrade
 
     - repo: https://github.com/commitizen-tools/commitizen
-      rev: v4.13.9
+      rev: v4.16.3
       hooks:
           - id: commitizen
             stages: [commit-msg]

{hydrotoolbox-2.2.0 → hydrotoolbox-2.3.0}/CHANGELOG.md

@@ -1,3 +1,9 @@
+## v2.3.0 (2026-06-09)
+
+### Feat
+
+- add "passes" to Lynne Hollick function
+
 ## v2.2.0 (2026-03-29)
 
 ### Feat

{hydrotoolbox-2.2.0/src/hydrotoolbox.egg-info → hydrotoolbox-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hydrotoolbox
-Version: 2.2.0
+Version: 2.3.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

hydrotoolbox-2.3.0/VERSION

@@ -0,0 +1 @@
+2.3.0

{hydrotoolbox-2.2.0 → hydrotoolbox-2.3.0}/pyproject.toml

@@ -65,7 +65,7 @@ github = "https://github.com/timcera/hydrotoolbox"
 name = "cz_conventional_commits"
 tag_format = "v$version"
 update_changelog_on_bump = true
-version = "2.2.0"
+version = "2.3.0"
 version_files = ["VERSION"]
 
 [tool.isort]

{hydrotoolbox-2.2.0 → hydrotoolbox-2.3.0}/src/hydrotoolbox/baseflow/methods/lyne_hollick.py

@@ -5,10 +5,15 @@ __all__ = [
 from hydrotoolbox.baseflow.methods.general_form import general_form_digital_filter
 
 
-def lyne_hollick(flow, k):
+def lyne_hollick(flow, k, passes=1):
     """LH digital filter (Lyne & Hollick, 1979)"""
     alpha = k
     beta = (1 - k) / 2
     gamma = 1.0
 
-    return general_form_digital_filter(flow, alpha, beta, gamma)
+    for pss in range(passes):
+        if pss > 0:
+            flow = flow[::-1]
+        flow, count = general_form_digital_filter(flow, alpha, beta, gamma)
+
+    return flow, count

{hydrotoolbox-2.2.0 → hydrotoolbox-2.3.0}/src/hydrotoolbox/baseflow/separation.py

@@ -37,6 +37,7 @@ def separation(
     C=None,
     a=None,
     bfi_max=None,
+    passes=1,
 ):
     if method == "all":
         method = [
@@ -76,7 +77,7 @@ def separation(
             "furey",
             "willems",
         ]:
-            b_lh = lyne_hollick(Q, k=k)[0]
+            b_lh = lyne_hollick(Q, k=k, passes=passes)[0]
 
         if m == "ukih":
             b[m] = ukih(Q, b_lh)
@@ -91,7 +92,7 @@ def separation(
             b[m] = slide(Q, area=area, num_days=num_days)
 
         if m == "lyne_hollick":
-            b[m] = lyne_hollick(Q, k=k)[0]
+            b[m] = lyne_hollick(Q, k=k, passes=passes)[0]
 
         if m == "chapman":
             b[m] = chapman(Q, k)[0]

{hydrotoolbox-2.2.0 → hydrotoolbox-2.3.0}/src/hydrotoolbox/baseflow_sep.py

@@ -104,6 +104,7 @@ def bfsep(
     C=None,
     a=None,
     bfi_max=None,
+    passes=1,
 ):
     complete_index = pd.date_range(start=flow.index[0], end=flow.index[-1], freq="D")
     flow = flow.reindex(complete_index, fill_value=np.nan)
@@ -154,6 +155,7 @@ def bfsep(
                 C=C,
                 a=a,
                 bfi_max=bfi_max,
+                passes=passes,
             )[bfi],
             index=ncol.index,
         )
@@ -664,6 +666,7 @@ def furey(
 def lyne_hollick(
     input_ts="-",
     alpha=0.925,
+    passes=1,
     columns=None,
     source_units=None,
     start_date=None,
@@ -696,6 +699,8 @@ def lyne_hollick(
     ${columns}
     alpha
         Catchment constant (value between 0 and 1).  Default is 0.925.
+    passes : int
+        The number of passes to use for the filter.
     ${source_units}
     ${start_date}
     ${end_date}
@@ -731,7 +736,7 @@ def lyne_hollick(
         source_units=source_units,
         target_units=target_units,
     )
-    return bfsep(flow, "lyne_hollick", print_input, k=alpha)
+    return bfsep(flow, "lyne_hollick", print_input, k=alpha, passes=passes)
 
 
 @tsutils.doc(tsutils.docstrings)

{hydrotoolbox-2.2.0 → hydrotoolbox-2.3.0}/src/hydrotoolbox/toolbox_utils/src/toolbox_utils/readers/hbn.py

@@ -1,23 +1,26 @@
-"""hspfbintoolbox to read HSPF binary files."""
+"""function to read HSPF binary files."""
 
 import datetime
 import struct
 import sys
-
-try:
-    from typing import Literal
-except ImportError:
-    from typing import Literal
+from typing import Literal
 
 import pandas as pd
 
 from .. import tsutils
+from ..utils import pandas_period_by_version
+from . import utils
 
 code2intervalmap = {5: "yearly", 4: "monthly", 3: "daily", 2: "bivl"}
 
 interval2codemap = {"yearly": 5, "monthly": 4, "daily": 3, "bivl": 2}
 
-code2freqmap = {5: "A", 4: "M", 3: "D", 2: None}
+code2freqmap = {
+    5: pandas_period_by_version("Y"),
+    4: "M",
+    3: "D",
+    2: None,
+}
 
 
 _LOCAL_DOCSTRINGS = {
@@ -27,168 +30,20 @@ _LOCAL_DOCSTRINGS = {
 }
 
 
-def tuple_match(findme, hay):
-    """Part of partial ordered matching.
-    See http://stackoverflow.com/a/4559604
-    """
-    return len(findme) == len(hay) and all(
-        i is None or j is None or i == j for i, j in zip(findme, hay)
-    )
-
-
-def tuple_combine(findme, hay):
-    """Part of partial ordered matching.
-    See http://stackoverflow.com/a/4559604
-    """
-    return tuple(i is None and j or i for i, j in zip(findme, hay))
-
-
-def tuple_search(findme, haystack):
-    """Partial ordered matching with 'None' as wildcard
-    See http://stackoverflow.com/a/4559604
-    """
-    return [
-        (index, tuple_combine(findme, hay))
-        for index, hay in enumerate(haystack)
-        if tuple_match(findme, hay)
-    ]
-
-
 def _get_data(binfilename, interval="daily", labels=None, catalog_only=True):
     """Underlying function to read from the binary file.  Used by
     'extract', 'catalog'.
     """
-    if labels is None:
-        labels = [",,,"]
-    testem = {
-        "PERLND": [
-            "ATEMP",
-            "SNOW",
-            "PWATER",
-            "SEDMNT",
-            "PSTEMP",
-            "PWTGAS",
-            "PQUAL",
-            "MSTLAY",
-            "PEST",
-            "NITR",
-            "PHOS",
-            "TRACER",
-            "",
-        ],
-        "IMPLND": ["ATEMP", "SNOW", "IWATER", "SOLIDS", "IWTGAS", "IQUAL", ""],
-        "RCHRES": [
-            "HYDR",
-            "CONS",
-            "HTRCH",
-            "SEDTRN",
-            "GQUAL",
-            "OXRX",
-            "NUTRX",
-            "PLANK",
-            "PHCARB",
-            "INFLOW",
-            "OFLOW",
-            "ROFLOW",
-            "",
-        ],
-        "BMPRAC": [""],
-        "": [""],
-    }
-
-    collect_dict = {}
-    lablist = []
-
     # Normalize interval code
     try:
         intervalcode = interval2codemap[interval.lower()]
     except AttributeError:
         intervalcode = None
 
-    # convert label tuples to lists
-    labels = list(labels)
-
-    # turn into a list of lists
-    nlabels = []
-    for label in labels:
-        if isinstance(label, str):
-            nlabels.append(label.split(","))
-        else:
-            nlabels.append(label)
-    labels = nlabels
-
-    # Check the list members for valid values
-    for label in labels:
-        if len(label) != 4:
-            raise ValueError(
-                tsutils.error_wrapper(
-                    f"""The label '{label}' has the wrong number of entries.
-                    """
-                )
-            )
-
-        # replace empty fields with None
-        # operation,lue_number,group,variable
-        words = [None if (i in ("", "None")) else i for i in label]
-
-        # first word must be a valid operation type or None
-        if words[0] is not None:
-            # force uppercase before comparison
-            words[0] = words[0].upper()
-            if words[0] not in testem:
-                raise ValueError(
-                    tsutils.error_wrapper(
-                        f"""Operation type must be one of 'PERLND', 'IMPLND',
-                        'RCHRES', or 'BMPRAC', or missing (to get all) instead
-                        of {words[0]}.
-                        """
-                    )
-                )
-
-        # second word must be integer 1-999 or None or range to parse
-        if words[1] is not None:
-            try:
-                words[1] = int(words[1])
-                luelist = [words[1]]
-            except ValueError:
-                luelist = tsutils.range_to_numlist(words[1])
-            for luenum in luelist:
-                if luenum < 1 or luenum > 999:
-                    raise ValueError(
-                        tsutils.error_wrapper(
-                            f"""The land use element must be an integer from
-                            1 to 999 inclusive, instead of {luenum}.
-                            """
-                        )
-                    )
-        else:
-            luelist = [None]
-
-        # third word must be a valid group name or None
-        if words[2] is not None:
-            words[2] = words[2].upper()
-            if words[2] not in testem[words[0]]:
-                raise ValueError(
-                    tsutils.error_wrapper(
-                        f"""The {words[0]} operation type only allows the
-                        variable groups: {testem[words[0]][:-1]}, instead you
-                        gave {words[2]}.
-                        """
-                    )
-                )
-
-        # fourth word is currently not checked - assumed to be a variable name
-        # if not, it will simply never be found in the file, so ok
-        # but no warning for the user - add check?
-
-        # add interval code as fifth word in list
-        words.append(intervalcode)
-
-        # add to new list of checked and expanded lists
-        for luenum in luelist:
-            words[1] = luenum
-            lablist.append(list(words))
+    lablist = utils.normalize_labels(labels)
+    lablist = [i + [intervalcode] for i in lablist]
 
+    collect_dict = {}
     # Now read through the binary file and collect the data matching the labels
     with open(binfilename, "rb") as binfp:
         labeltest = set()
@@ -200,7 +55,8 @@ def _get_data(binfilename, interval="daily", labels=None, catalog_only=True):
             # not a valid HSPF binary file
             raise ValueError(
                 tsutils.error_wrapper(
-                    f"""{binfilename} is not a valid HSPF binary output file
+                    f"""
+                    {binfilename} is not a valid HSPF binary output file
                     (.hbn),  The first byte must be FD hexadecimal, but it was
                     {magicbyte}.
                     """
@@ -251,9 +107,7 @@ def _get_data(binfilename, interval="daily", labels=None, catalog_only=True):
                     # read the variable name
                     variable_name = struct.unpack(f"{length}s", binfp.read(length))[0]
 
-                    # add variable name to the set for this operation
-                    # why a set instead of a list? There should never be
-                    # a duplicate anyway
+                    # add variable name to the vnames list
                     vnames.setdefault((lue, group), []).append(variable_name)
 
                     # update how far along the record we are
@@ -275,11 +129,15 @@ def _get_data(binfilename, interval="daily", labels=None, catalog_only=True):
                 vals = struct.unpack(f"{numvals}f", binfp.read(4 * numvals))
                 recpos += 4 * numvals
 
+                # delta accounts for HSPF's use of hour 24 to represent
+                # the end of the last interval of the day.
                 delta = datetime.timedelta(hours=0)
-                if hour == 24:
-                    hour = 0
+                if level == interval2codemap["bivl"]:
+                    delta = datetime.timedelta(hours=hour) + datetime.timedelta(
+                        minutes=minute
+                    )
 
-                ndate = datetime.datetime(year, month, day, hour, minute) + delta
+                ndate = datetime.datetime(year, month, day) + delta
 
                 #  Go through labels to see if these values need to be
                 #  collected
@@ -291,9 +149,8 @@ def _get_data(binfilename, interval="daily", labels=None, catalog_only=True):
                         vname.decode("ascii"),
                         level,
                     )
-
                     for lbl in lablist:
-                        res = tuple_search(tmpkey, [lbl])
+                        res = utils.tuple_search(tmpkey, [lbl])
                         if not res:
                             continue
                         labeltest.add(tuple(lbl))
@@ -322,8 +179,9 @@ def _get_data(binfilename, interval="daily", labels=None, catalog_only=True):
     if not collect_dict:
         raise ValueError(
             tsutils.error_wrapper(
-                f"""The label specifications below matched no records in the
-                binary file.
+                f"""
+                The label specifications below matched no records in the binary
+                file.
 
                 {lablist}
                 """
@@ -337,8 +195,9 @@ def _get_data(binfilename, interval="daily", labels=None, catalog_only=True):
             if tuple(lbl) not in labeltest:
                 sys.stderr.write(
                     tsutils.error_wrapper(
-                        f"""Warning: The label '{lbl}' matched no records in
-                        the binary file.
+                        f"""
+                        Warning: The label '{lbl}' matched no records in the
+                        binary file.
                         """
                     )
                 )
@@ -365,7 +224,8 @@ def hbn_extract(
     if interval not in ("bivl", "daily", "monthly", "yearly"):
         raise ValueError(
             tsutils.error_wrapper(
-                f"""The "interval" argument must be one of "bivl", "daily",
+                f"""
+                The "interval" argument must be one of "bivl", "daily",
                 "monthly", or "yearly".  You supplied "{interval}".
                 """
             )

hydrotoolbox-2.3.0/src/hydrotoolbox/toolbox_utils/src/toolbox_utils/readers/utils.py

@@ -0,0 +1,179 @@
+"""A collection of functions used by toolbox_utils, wdmtoolbox, ...etc."""
+
+from typing import List, Optional, Union
+
+import pint_pandas  # not used directly, but required to use pint in pandas
+
+from .. import tsutils
+
+# This is here so that linters don't remove the pint_pandas import which is
+# needed to use pint in pandas
+_ = pint_pandas.version("pint")
+
+
+def normalize_labels(labels: Optional[Union[str, List[str]]]) -> List[str]:
+    """
+    Process labels for the hbn function.
+
+    Parameters
+    ----------
+    labels
+        The labels to be processed.
+
+    Returns
+    -------
+    process_labels
+        A list of processed labels.
+    """
+    if labels is None:
+        labels = [",,,"]
+
+    testem = {
+        "PERLND": [
+            "ATEMP",
+            "SNOW",
+            "PWATER",
+            "SEDMNT",
+            "PSTEMP",
+            "PWTGAS",
+            "PQUAL",
+            "MSTLAY",
+            "PEST",
+            "NITR",
+            "PHOS",
+            "TRACER",
+            "",
+        ],
+        "IMPLND": ["ATEMP", "SNOW", "IWATER", "SOLIDS", "IWTGAS", "IQUAL", ""],
+        "RCHRES": [
+            "HYDR",
+            "CONS",
+            "HTRCH",
+            "SEDTRN",
+            "GQUAL",
+            "OXRX",
+            "NUTRX",
+            "PLANK",
+            "PHCARB",
+            "INFLOW",
+            "OFLOW",
+            "ROFLOW",
+            "",
+        ],
+        "BMPRAC": [""],
+        "": [""],
+    }
+
+    lablist = []
+
+    # convert label tuples to lists
+    labels = list(labels)
+
+    # turn into a list of lists
+    nlabels = []
+    for label in labels:
+        if isinstance(label, str):
+            nlabels.append(label.split(","))
+        else:
+            nlabels.append(label)
+    labels = nlabels
+
+    # Check the list members for valid values
+    for label in labels:
+        if len(label) != 4:
+            raise ValueError(
+                tsutils.error_wrapper(
+                    f"""
+                    The label '{label}' has the wrong number of entries.
+                    """
+                )
+            )
+
+        # replace empty fields with None
+        words = [None if i == "" else i for i in label]
+
+        # first word must be a valid operation type or None
+        if words[0] is not None:
+            # force uppercase before comparison
+            words[0] = words[0].upper()
+            if words[0] not in testem:
+                raise ValueError(
+                    tsutils.error_wrapper(
+                        f"""
+                        Operation type must be one of 'PERLND', 'IMPLND',
+                        'RCHRES', or 'BMPRAC', or missing (to get all) instead
+                        of {words[0]}.
+                        """
+                    )
+                )
+
+        # second word must be integer 1-999 or None or range to parse
+        if words[1] is not None:
+            try:
+                words[1] = int(words[1])
+                luelist = [words[1]]
+            except ValueError:
+                luelist = tsutils.range_to_numlist(words[1])
+            for luenum in luelist:
+                if luenum < 1 or luenum > 999:
+                    raise ValueError(
+                        tsutils.error_wrapper(
+                            f"""
+                            The land use element must be an integer from 1 to
+                            999 inclusive, instead of {luenum}.
+                            """
+                        )
+                    )
+        else:
+            luelist = [None]
+
+        # third word must be a valid group name or None
+        if words[2] is not None:
+            words[2] = words[2].upper()
+            if (words[0] is not None) and (words[2] not in testem[words[0]]):
+                raise ValueError(
+                    tsutils.error_wrapper(
+                        f"""
+                        The {words[0]} operation type only allows the variable
+                        groups: {testem[words[0]][:-1]},
+                        instead you gave {words[2]}.
+                        """
+                    )
+                )
+
+        # fourth word is currently not checked - assumed to be a variable name
+        # if not, it will simply never be found in the file, so ok
+        # but no warning for the user - add check?
+
+        # add to new list of checked and expanded lists
+        for luenum in luelist:
+            words[1] = luenum
+            lablist.append(list(words))
+    return lablist
+
+
+def tuple_match(findme, hay):
+    """Part of partial ordered matching.
+    See http://stackoverflow.com/a/4559604
+    """
+    return len(findme) == len(hay) and all(
+        i is None or j is None or i == j for i, j in zip(findme, hay)
+    )
+
+
+def tuple_combine(findme, hay):
+    """Part of partial ordered matching.
+    See http://stackoverflow.com/a/4559604
+    """
+    return tuple(i is None and j or i for i, j in zip(findme, hay))
+
+
+def tuple_search(findme, haystack):
+    """Partial ordered matching with 'None' as wildcard
+    See http://stackoverflow.com/a/4559604
+    """
+    return [
+        (index, tuple_combine(findme, hay))
+        for index, hay in enumerate(haystack)
+        if tuple_match(findme, hay)
+    ]