bulum 0.3.2__tar.gz → 0.3.3__tar.gz

{bulum-0.3.2/src/bulum.egg-info → bulum-0.3.3}/PKG-INFO

@@ -1,13 +1,14 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: bulum
-Version: 0.3.2
+Version: 0.3.3
 Summary: Open source python library for assessing hydrologic model results in Queensland
 Home-page: https://github.com/odhydrology/bulum
 Author: Chas Egan
-Author-email: chas@odhydrology.com
+Author-email: Chas Egan <chas@odhydrology.com>
+Project-URL: Homepage, https://github.com/odhydrology/bulum
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
 Requires-Dist: altair[all]>=5.5.0
@@ -17,14 +18,9 @@ Requires-Dist: numpy>=1.26.4
 Requires-Dist: pandas>=2.2.0
 Requires-Dist: plotly>=5.18.0
 Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
 Dynamic: home-page
-Dynamic: requires-dist
+Dynamic: license-file
 Dynamic: requires-python
-Dynamic: summary
 
 # bulum
 
@@ -81,8 +77,39 @@ Where can I find the API token password? Chas has it in his emails. It is also h
 
 How do I make a new API token? Go to your PyPi account settings, and click on "API tokens". Then click on "Add API token", and give it a name. The token will be displayed on the next screen.
 
+Alternatively, 
+```bash
+uv build
+uv publish --token XXXXX
+```
+
 ## Unit Tests
 
+For development testing, first sync with extras=dev via
+```bash
+uv sync --extra dev
+```
+
+To run tests with the current or a particular version of python, from the project root run pytest via (for example):
+```bash
+uv run pytest
+uv run 
+uv run tox -e py312 # to run a particular version
+```
+
+Before publishing, check the library is functional across all supported versions of python via (one of):
+```bash
+uv run tox
+uv run tox -p auto # This is run in parallel
+```
+
+Note: if you are missing python versions, install via (e.g.) 
+```bash
+uv python install 3.12
+```
+
+### Legacy
+
 WARNING: Run unit tests from an anaconda environment with compatible dependencies!
 
 Install the nose2 test-runner framework. 

{bulum-0.3.2 → bulum-0.3.3}/README.md

@@ -53,8 +53,39 @@ Where can I find the API token password? Chas has it in his emails. It is also h
 
 How do I make a new API token? Go to your PyPi account settings, and click on "API tokens". Then click on "Add API token", and give it a name. The token will be displayed on the next screen.
 
+Alternatively, 
+```bash
+uv build
+uv publish --token XXXXX
+```
+
 ## Unit Tests
 
+For development testing, first sync with extras=dev via
+```bash
+uv sync --extra dev
+```
+
+To run tests with the current or a particular version of python, from the project root run pytest via (for example):
+```bash
+uv run pytest
+uv run 
+uv run tox -e py312 # to run a particular version
+```
+
+Before publishing, check the library is functional across all supported versions of python via (one of):
+```bash
+uv run tox
+uv run tox -p auto # This is run in parallel
+```
+
+Note: if you are missing python versions, install via (e.g.) 
+```bash
+uv python install 3.12
+```
+
+### Legacy
+
 WARNING: Run unit tests from an anaconda environment with compatible dependencies!
 
 Install the nose2 test-runner framework. 

bulum-0.3.3/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "bulum"
+dynamic = ["version"]
+description = "Open source python library for assessing hydrologic model results in Queensland"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [
+    { name = "Chas Egan", email = "chas@odhydrology.com" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "altair[all]>=5.5.0",
+    "folium>=0.14",
+    "matplotlib>=3.8.3",
+    "numpy>=1.26.4",
+    "pandas>=2.2.0",
+    "plotly>=5.18.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/odhydrology/bulum"
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "bulum.version.__version__" }
+
+[tool.pytest.ini_options]
+filterwarnings = [
+    "ignore::DeprecationWarning:matplotlib",
+    "ignore::DeprecationWarning:PIL",
+    "ignore::PendingDeprecationWarning",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "tox>=4.54.0",
+]

{bulum-0.3.2 → bulum-0.3.3}/setup.py

@@ -8,7 +8,7 @@ exec(open('src/bulum/version.py').read())
 setuptools.setup(
     name="bulum",
     version=__version__,
-    python_requires=">=3.9",
+    python_requires=">=3.11",
     author="Chas Egan",
     author_email="chas@odhydrology.com",
     description="Open source python library for assessing hydrologic model results in Queensland",

bulum-0.3.3/src/bulum/clim/tests/test_clim.py

@@ -0,0 +1,71 @@
+import unittest
+import os
+import bulum.io as bio
+import bulum.clim as ocl
+import bulum.utils as out
+import pandas as pd
+
+
+class Tests(unittest.TestCase):
+
+    @classmethod
+    def setUpClass(cls):
+        os.makedirs("./trash", exist_ok=True)
+        return super().setUpClass()
+
+    def test_load_data_into_df(self):
+        """
+        The purpose of this is just to test that if I load 2 different files as 
+        dataframes, and then simply put them together. I.e. does it join on the
+        dates? YES IT APPEARS TO LEFT-JOIN on the dates from the first file.
+        """
+        df1 = bio.read_ts_csv("./src/bulum/clim/tests/Flow.out.withmissing.csv", date_format=r"%Y-%m-%d")["FRex_FR.qqm"]
+        df2 = bio.read_ts_csv("./src/bulum/clim/tests/Flow.out.RCP85_P2050_GCM8.csv", date_format=r"%Y-%m-%d")["FRex_FR.qqm"]
+        df3 = pd.DataFrame()
+        df3["x"] = df1
+        df3["y"] = df2
+        # print(df3.head())
+        # print(df3.tail())
+        self.assertTrue(len(df3) == len(df1))
+        self.assertAlmostEqual(df3.x.values[-1], 136)  # these values should line up despite different starting dates for each file
+        self.assertAlmostEqual(df3.y.values[-1], 62)  # these values should line up despite different starting dates for each file
+        # And now doe the same again with files loaded in the opposite order
+        df1 = bio.read_ts_csv("./src/bulum/clim/tests/Flow.out.RCP85_P2050_GCM8.csv", date_format=r"%Y-%m-%d")["FRex_FR.qqm"]
+        df2 = bio.read_ts_csv("./src/bulum/clim/tests/Flow.out.withmissing.csv", date_format=r"%Y-%m-%d")["FRex_FR.qqm"]
+        df3 = pd.DataFrame()
+        df3["x"] = df1
+        df3["y"] = df2
+        # print(df3.head())
+        # print(df3.tail())
+        self.assertTrue(len(df3) == len(df1))
+        self.assertAlmostEqual(df3.x.values[-1], 62)  # these values should line up despite different starting dates for each file
+        self.assertAlmostEqual(df3.y.values[-1], 136)  # these values should line up despite different starting dates for each file
+
+    def test_get_exc_transform(self):
+        """
+        This gets transformation curves based on current & future climate datasets, and then checks that the transformation
+        curves have the same total number of points regardless of whether we use default seasons (monthly) or define 3 custom 
+        seasons.
+        """
+        current_climate = bio.read_ts_csv("./src/bulum/clim/tests/Flow.out.withmissing.csv", date_format=r"%Y-%m-%d")
+        future_climate = bio.read_ts_csv("./src/bulum/clim/tests/Flow.out.RCP85_P2050_GCM8.csv", date_format=r"%Y-%m-%d")
+        answer1 = ocl.derive_transformation_curves(current_climate["FRex_FR.qqm"], future_climate["FRex_FR.qqm"])
+        answer2 = ocl.derive_transformation_curves(current_climate["FRex_FR.qqm"], future_climate["FRex_FR.qqm"], season_start_months=[3, 7, 9])
+        total_len_1 = sum([len(a[1]) for a in answer1.values()])
+        total_len_2 = sum([len(a[1]) for a in answer2.values()])
+        self.assertEqual(total_len_1, total_len_2)
+        self.assertTrue(total_len_1 > 0)
+
+    def test_apply_transformation_curves(self):
+        current_climate = bio.read_ts_csv("./src/bulum/clim/tests/Flow.out.withmissing.csv", date_format=r"%Y-%m-%d")
+        future_climate = bio.read_ts_csv("./src/bulum/clim/tests/Flow.out.RCP85_P2050_GCM8.csv", date_format=r"%Y-%m-%d")
+        t = ocl.derive_transformation_curves(current_climate["FRex_FR.qqm"], future_climate["FRex_FR.qqm"])
+        answer = pd.DataFrame()
+        answer["RexCurrent"] = current_climate["FRex_FR.qqm"]
+        answer["RexCurrent"] = future_climate["FRex_FR.qqm"]
+        answer["Transf"] = ocl.apply_transformation_curves(t, current_climate["FRex_FR.qqm"])
+        # print(answer["Current"].sum())
+        # print(answer["Future"].sum())
+        # print(answer["Transf"].sum())
+        self.assertAlmostEqual(answer["Transf"].sum(), 4845710.795475168)  # Actually haven't checked that this is the correct answer but looks plausible.
+        answer.to_csv("./trash/transformed.csv")

{bulum-0.3.2 → bulum-0.3.3}/src/bulum/io/__init__.py

@@ -1,7 +1,6 @@
 from .csv_io import *
 from .res_csv_io import *
 from .idx_io import *
-from .idx_io_native import *
 from .iqqm_out_reader import *
 from .lqn_io import *
 from .general_io import *

{bulum-0.3.2 → bulum-0.3.3}/src/bulum/io/csv_io.py

@@ -1,11 +1,13 @@
-""" 
+"""
 Functions for reading CSVs, particularly time-series CSVs.
 """
 
+import os
+from typing import Union
+
 import numpy as np
 import pandas as pd
 from bulum import utils
-import os
 
 na_values = ['', ' ', 'null', 'NULL', 'NAN', 'NaN', 'nan', 'NA', 'na', 'N/A' 'n/a', '#N/A', '#NA', '-NaN', '-nan']
 
@@ -20,33 +22,43 @@ def read_ts_csv(filename: str | os.PathLike, date_format=None,
 
     Parameters
     ----------
-    filename : str | PathLike
+    filename : str or PathLike
+        Path to the CSV file to read.
     date_format : str, optional
         defaults to "%d/%m/%Y" as per Fors. Other common formats include "%Y-%m-%d", "%Y/%m/%d".
     df : pd.DataFrame, optional
         If provided, the reader will append columns to this dataframe. Defaults to None.
     colprefix : str, optional
-        If provided, the reader will append this prefix to the start of each column name. Defaults to None.
+        If provided, the reader will prepend this to column name. Defaults to None.
     allow_nonnumeric : bool, optional
-        If false, the method will assert that all columns are numerical. Defaults to False.
+        If False, raises if any column is not numeric. Default is False.
     assert_date : bool, optional
-        If true, the method will assert that date index meets "%Y-%m-%d" format. Defaults to True.         
+        If True, asserts the date index conforms to ``"%Y-%m-%d"``. Default is True.
+
+    Returns
+    -------
+    utils.TimeseriesDataframe
 
-    Returns:
-        pd.DataFrame: Dataframe containing the data from the csv file.
+    Raises
+    ------
+    TypeError
+        If a column is not numeric and ``allow_nonnumeric`` is False.
+    ValueError
+        If the new date range does not overlap with ``df``.
     """
+    new_df: pd.DataFrame
     new_df = pd.read_csv(filename, na_values=na_values, **kwargs)
     # Date index
     new_df.set_index(new_df.columns[0], inplace=True)
     if assert_date:
-        new_df.index = utils.standardize_datestring_format(new_df.index)
-    new_df.index.name = "Date"
+        new_df.index = utils.standardize_datestring_format(new_df.index, as_index=True)
+    new_df.index.name = "Date" # type: ignore
     # df = df.replace(r'^\s*$', np.nan, regex=True)
     # Check values
     if not allow_nonnumeric:
         for col in new_df.columns:
-            if not np.issubdtype(new_df[col].dtype, np.number):
-                raise Exception(f"ERROR: Column '{col}' is not numeric!")
+            if not np.issubdtype(new_df[col].dtype, np.number):  # type: ignore
+                raise TypeError(f"ERROR: Column '{col}' is not numeric!")
     # Rename columns if required
     if colprefix is not None:
         for c in new_df.columns:
@@ -55,17 +67,28 @@ def read_ts_csv(filename: str | os.PathLike, date_format=None,
     if df is None:
         df = new_df
     else:
+        assert isinstance(df, pd.DataFrame), f"Dataframe {df=} is not a dataframe!"
         if len(df) > 0:
             # Check that the dates overlap
             newdf_ends_before_df_starts = new_df.index[0] < df.index[-1]
             df_ends_before_newdf_starts = df.index[-1] < new_df.index[0]
             if newdf_ends_before_df_starts or df_ends_before_newdf_starts:
-                raise Exception("ERROR: The dates in the new dataframe do not overlap with the existing dataframe!")
+                raise ValueError("ERROR: The dates in the new dataframe do not"
+                                 " overlap with the existing dataframe!")
         df = df.join(new_df, how="outer")
     return utils.TimeseriesDataframe.from_dataframe(df)
 
 
-def write_ts_csv(df: pd.DataFrame, filename: str,
-                 *args, **kwargs):
-    """Wrapper around ``pandas.DataFrame.to_csv()``."""
+def write_ts_csv(df: pd.DataFrame, filename: str, *args, **kwargs) -> None:
+    """Write a dataframe to CSV via :meth:`pandas.DataFrame.to_csv`.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        DataFrame to write.
+    filename : str or PathLike
+        Path to the output CSV file.
+    *args, **kwargs
+        Passed through to :meth:`pandas.DataFrame.to_csv`.
+    """
     df.to_csv(filename, *args, **kwargs)

bulum-0.3.3/src/bulum/io/general_io.py

@@ -0,0 +1,55 @@
+""" 
+General use IO functions.
+"""
+import os
+import re
+from pathlib import Path
+
+import bulum.io as bio
+from bulum import utils
+
+
+def read(filename: str | os.PathLike, **kwargs) -> utils.TimeseriesDataframe:
+    """Read a timeseries file, dispatching to the appropriate reader based on file extension.
+
+    Supported formats: ``.res.csv``, ``.csv``, ``.idx``, and IQQM listquan
+    outputs (e.g. ``.01d``).
+
+    Parameters
+    ----------
+    filename : str or PathLike
+        Path to the file to read.
+    **kwargs
+        Passed through to the underlying reader function.
+
+    Returns
+    -------
+    utils.TimeseriesDataframe
+
+    Raises
+    ------
+    ValueError
+        If the file extension is not recognised, or if a ``.res.csv`` file
+        cannot be parsed.
+    """
+    if not isinstance(filename, Path):
+        filename = Path(filename)
+    filename_suffix = filename.suffix.lower()
+
+    df = None
+    if filename.name.lower().endswith(".res.csv"):
+        df = bio.read_res_csv(filename, **kwargs)
+        if df is None:
+            raise ValueError("Res csv could not be read.")
+    elif filename_suffix == ".csv":
+        df = bio.read_ts_csv(filename, **kwargs)
+    elif filename_suffix == ".idx":
+        df = bio.read_idx(filename, **kwargs)
+    elif re.search(".[0-9a-f]{2}d$", filename_suffix):
+        df = bio.read_iqqm_lqn_output(filename, **kwargs)
+    else:
+        raise ValueError(f"Unknown file extension: {filename}")
+
+    assert isinstance(df, utils.TimeseriesDataframe), \
+        "Output of `read` is not a TimeseriesDataframe."
+    return df