Change hydrological modelling to classes, add Hydrotel

Makefile

@@ -27,7 +27,7 @@ LOCALES := docs/locales
 help:
 	@python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)
 
-clean: clean-build clean-pyc clean-test ## remove all build, test, coverage and Python artifacts
+clean: clean-build clean-docs clean-pyc clean-test ## remove all build, test, coverage and Python artifacts
 
 clean-build: ## remove build artifacts
 	rm -fr build/
@@ -37,6 +37,8 @@ clean-build: ## remove build artifacts
 	find . -name '*.egg' -exec rm -f {} +
 
 clean-docs: ## remove docs artifacts
+	rm -fr docs/notebooks/_data/
+	rm -fr docs/notebooks/.ipynb_checkpoints/
 	rm -f docs/apidoc/xhydro*.rst
 	rm -f docs/apidoc/modules.rst
 	rm -f docs/locales/fr/LC_MESSAGES/*.mo

docs/notebooks/_finder.py

@@ -0,0 +1,13 @@
+"""Utility to find the folder containing the notebooks."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _find_current_folder():
+    """Find the folder containing the notebooks.
+
+    Needed in order to run the notebooks from the docs/notebooks folder.
+    """
+    return Path(__file__).absolute().parent

docs/notebooks/index.rst

@@ -5,7 +5,8 @@ Usage
     :maxdepth: 1
     :numbered:
 
-    climate_change
     gis
-    local_frequency_analysis
+    hydrological_modelling
     optimal_interpolation
+    local_frequency_analysis
+    climate_change

environment-dev.yml

@@ -11,11 +11,13 @@ dependencies:
   - intake <2.0.0 # This should be set by xdatasets once on conda-forge
   - leafmap
   - numpy
+  - pandas
   - planetary-computer
   - pystac
   - pystac-client
   - pooch >=1.8.0
   - pydantic >=2.0,<2.5.3  # FIXME: Remove pin once our dependencies (xclim, xscen) support pydantic 2.5.3
+  - pyyaml
   - rasterio
   - spotpy
   - stackstac

environment.yml

@@ -11,11 +11,13 @@ dependencies:
   - intake <2.0.0 # This should be set by xdatasets once on conda-forge
   - leafmap
   - numpy
+  - pandas
   - planetary-computer
   - pooch >=1.8.0
   - pydantic >=2.0,<2.5.3  # FIXME: Remove pin once our dependencies (xclim, xscen) support pydantic 2.5.3
   - pystac
   - pystac-client
+  - pyyaml
   - rasterio
   - spotpy
   - stackstac

pyproject.toml

@@ -44,11 +44,13 @@ dependencies = [
   "intake-esm !=2024.2.6", # pin needed for intake-esm (dependency of xscen) to work with Python3.9
   "leafmap",
   "numpy",
+  "pandas",
   "planetary-computer",
   "pooch >=1.8.0",
   "pydantic >=2.0,<2.5.3",
   "pystac",
   "pystac-client",
+  "pyyaml",
   "rasterio",
   "spotpy",
   "stackstac",

tests/test_calibration.py

@@ -4,8 +4,8 @@
 import numpy as np
 import pytest
 
+from xhydro.modelling import hydrological_model
 from xhydro.modelling.calibration import perform_calibration
-from xhydro.modelling.hydrological_modelling import _dummy_model
 from xhydro.modelling.obj_funcs import get_objective_function, transform_flows
 
 
@@ -50,8 +50,8 @@ def test_spotpy_calibration():
 
     # Test dummy model response
     model_config["parameters"] = [5, 5, 5]
-    qsim = _dummy_model(model_config)
-    assert qsim["qsim"].values[3] == 3500.00
+    qsim = hydrological_model(model_config).run()
+    assert qsim["streamflow"].values[3] == 3500.00
 
     # Also test to ensure SCEUA and take_minimize is required.
     best_parameters_sceua, best_simulation, best_objfun = perform_calibration(

tests/test_hydrological_modelling.py

@@ -3,51 +3,84 @@
 import numpy as np
 import pytest
 
-from xhydro.modelling.hydrological_modelling import (
-    get_hydrological_model_inputs,
-    run_hydrological_model,
-)
-
-
-def test_hydrological_modelling():
-    """Test the hydrological models as they become online"""
-    # Test the dummy model
-    model_config = {
-        "precip": np.array([10, 11, 12, 13, 14, 15]),
-        "temperature": np.array([10, 3, -5, 1, 15, 0]),
-        "qobs": np.array([120, 130, 140, 150, 160, 170]),
-        "drainage_area": np.array([10]),
-        "model_name": "Dummy",
-        "parameters": np.array([5, 5, 5]),
-    }
-    qsim = run_hydrological_model(model_config)
-    assert qsim["qsim"].values[3] == 3500.00
-
-    # Test the exceptions for new models
-    model_config.update(model_name="ADD_OTHER_HERE")
-    qsim = run_hydrological_model(model_config)
-    assert qsim == 0
-
-
-def test_import_unknown_model():
-    """Test for unknown model"""
-    with pytest.raises(NotImplementedError) as pytest_wrapped_e:
-        model_config = {"model_name": "fake_model"}
-        _ = run_hydrological_model(model_config)
-        assert pytest_wrapped_e.type == NotImplementedError
-
-
-def test_get_unknown_model_requirements():
-    """Test for required inputs for models with unknown name"""
-    with pytest.raises(NotImplementedError) as pytest_wrapped_e:
-        model_name = "fake_model"
-        _ = get_hydrological_model_inputs(model_name)
-        assert pytest_wrapped_e.type == NotImplementedError
-
-
-def test_get_model_requirements():
-    """Test for required inputs for models"""
-    model_name = "Dummy"
-    required_config = get_hydrological_model_inputs(model_name)
-    print(required_config.keys())
-    assert len(required_config.keys()) == 4
+from xhydro.modelling import get_hydrological_model_inputs, hydrological_model
+
+
+class TestHydrologicalModelling:
+    def test_hydrological_modelling(self):
+        """Test the hydrological models as they become online"""
+        # Test the dummy model
+        model_config = {
+            "precip": np.array([10, 11, 12, 13, 14, 15]),
+            "temperature": np.array([10, 3, -5, 1, 15, 0]),
+            "qobs": np.array([120, 130, 140, 150, 160, 170]),
+            "drainage_area": np.array([10]),
+            "model_name": "Dummy",
+            "parameters": np.array([5, 5, 5]),
+        }
+        qsim = hydrological_model(model_config).run()
+        np.testing.assert_array_equal(qsim["streamflow"].values[3], 3500.00)
+
+    def test_import_unknown_model(self):
+        """Test for unknown model"""
+        with pytest.raises(NotImplementedError) as pytest_wrapped_e:
+            model_config = {"model_name": "fake_model"}
+            _ = hydrological_model(model_config).run()
+            assert pytest_wrapped_e.type == NotImplementedError
+
+    def test_missing_name(self):
+        with pytest.raises(ValueError, match="The model name must be provided"):
+            model_config = {"parameters": [1, 2, 3]}
+            hydrological_model(model_config).run()
+
+
+class TestHydrologicalModelRequirements:
+    def test_get_unknown_model_requirements(self):
+        """Test for required inputs for models with unknown name"""
+        with pytest.raises(NotImplementedError) as pytest_wrapped_e:
+            model_name = "fake_model"
+            _ = get_hydrological_model_inputs(model_name)
+            assert pytest_wrapped_e.type == NotImplementedError
+
+    @pytest.mark.parametrize("model_name", ["Dummy", "Hydrotel"])
+    def test_get_model_requirements(self, model_name):
+        """Test for required inputs for models"""
+        expected_keys = {"Dummy": (6, 6), "Hydrotel": (8, 3)}
+
+        all_config, _ = get_hydrological_model_inputs(model_name)
+        assert len(all_config.keys()) == expected_keys[model_name][0]
+
+        all_config, _ = get_hydrological_model_inputs(model_name, required_only=True)
+        assert len(all_config.keys()) == expected_keys[model_name][1]
+
+
+class TestDummyModel:
+    def test_inputs(self):
+        model_config = {
+            "model_name": "Dummy",
+            "precip": np.array([10, 11, 12, 13, 14, 15]),
+            "temperature": np.array([10, 3, -5, 1, 15, 0]),
+            "qobs": np.array([120, 130, 140, 150, 160, 170]),
+            "drainage_area": np.array([10]),
+            "parameters": np.array([5, 5, 5]),
+        }
+        dummy = hydrological_model(model_config)
+        ds_in = dummy.get_inputs()
+        np.testing.assert_array_equal(ds_in.precip, model_config["precip"])
+        np.testing.assert_array_equal(ds_in.temperature, model_config["temperature"])
+        assert len(ds_in.time) == len(model_config["precip"])
+
+    def test_streamflow(self):
+        model_config = {
+            "model_name": "Dummy",
+            "precip": np.array([10, 11, 12, 13, 14, 15]),
+            "temperature": np.array([10, 3, -5, 1, 15, 0]),
+            "qobs": np.array([120, 130, 140, 150, 160, 170]),
+            "drainage_area": np.array([10]),
+            "parameters": np.array([5, 5, 5]),
+        }
+        dummy = hydrological_model(model_config)
+        ds_out = dummy.get_streamflow()
+        np.testing.assert_array_equal(ds_out["streamflow"].values[3], 3500.00)
+        assert dummy.qsim.equals(ds_out)
+        assert dummy.get_streamflow().equals(ds_out)