CSHS-CWRA · Zeitsperre · Jan 15, 2025 · Dec 13, 2024 · Dec 18, 2024 · Jan 7, 2025
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -13,9 +13,9 @@ sphinx:
   fail_on_warning: true
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-lts-latest
   tools:
-    python: "mambaforge-22.9"
+    python: "mambaforge-23.11"
   jobs:
     pre_build:
       - env SPHINX_APIDOC_OPTIONS="members,undoc-members,show-inheritance,noindex" sphinx-apidoc -o docs/apidoc --private --module-first src/ravenpy

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -9,6 +9,11 @@ v0.17.0 (unreleased)
 * Updated `ts_fit_graph` logic for `matplotlib` >= 3.10.0 compatibility. (PR #434)
 * Temporarily pinned `pygments` below v2.19 due to a breaking change affecting `sphinx-codeautolink`. (PR #434)
 * Adopted a new RavenPy logo for the documentation. (PR #428)
+* Documentation Updates: (PR #436)
+    * Cleaner imports, removed some unneeded library imports.
+    * Typo and grammar fixes.
+    * Updated the Python, Anaconda, and Ubuntu versions used to generate the documentation.
+* Small import fixes and minor code cleanup (`ravenpy.extractors`). (PR #436)
 
 v0.16.1 (2024-12-05)
 --------------------

diff --git a/README.rst b/README.rst
@@ -79,7 +79,7 @@ This package was created with Cookiecutter_ and the `Ouranosinc/cookiecutter-pyp
         :target: https://github.com/CSHS-CWRA/RavenPy/blob/master/LICENSE
         :alt: License
 
-.. |logo| image:: https://raw.githubusercontent.com/CSHS-CWRA/RavenPy/main/docs/_static/_images/ravenpy-logo-small.png
+.. |logo| image:: https://raw.githubusercontent.com/CSHS-CWRA/RavenPy/master/docs/_static/_images/logos/ravenpy-logo-small.png
         :target: https://github.com/CSHS-CWRA/RavenPy
         :alt: RavenPy Logo
 

diff --git a/docs/notebooks/04_Emulating_hydrological_models.ipynb b/docs/notebooks/04_Emulating_hydrological_models.ipynb
@@ -26,17 +26,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Import the list of possible model templates.\n",
-    "from ravenpy.config.emulators import (\n",
-    "    GR4JCN,\n",
-    "    HBVEC,\n",
-    "    HMETS,\n",
-    "    HYPR,\n",
-    "    SACSMA,\n",
-    "    Blended,\n",
-    "    CanadianShield,\n",
-    "    Mohyse,\n",
-    ")"
+    "# Import the emulators from the ravenpy package\n",
+    "from ravenpy.config import emulators"
    ]
   },
   {
@@ -196,7 +187,7 @@
     "# preferences, and then we will write the Raven configuration files to disk such that Raven can read them and\n",
     "# execute a simulation. In this case, we are building a GR4JCN model, but you could change this to any of the\n",
     "# eight models that are preconfigured for direct emulation in Ravenpy.\n",
-    "m = GR4JCN(\n",
+    "m = emulators.GR4JCN(\n",
     "    # Raven requires parameters for the GR4JCN model. For now, we provide default values, but in a later notebook\n",
     "    # we will show how to calibrate and find new parameters for our model.\n",
     "    params=[0.529, -3.396, 407.29, 1.072, 16.9, 0.947],\n",
@@ -296,7 +287,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The outputs are as follow:\n",
+    "The outputs are as follows:\n",
     "\n",
     "- hydrograph: The actual simulated hydrograph (q_sim), in netcdf format. It also contains the observed discharge (q_obs) if observed streamflow was provided as a forcing file.\n",
     "- storage: The state variables of the simulation duration, in netcdf format\n",
@@ -399,7 +390,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "As you can see, PAVICS-Hydro makes it easy to build a hydrological model, run it with forcing data, and then interact with the results! In the next notebooks, we will see how to adjust configuration files (the .rvX files) to setup and run a model, and also how to calibrate its parameters.\n",
+    "As you can see, PAVICS-Hydro makes it easy to build a hydrological model, run it with forcing data, and then interact with the results! In the next notebooks, we will see how to adjust configuration files (the .rvX files) to set up and run a model, and also how to calibrate its parameters.\n",
     "\n",
     "\n",
     "\n",
@@ -420,7 +411,7 @@
     "* MOHYSE = 10 parameters\n",
     "* HBVEC = 21 parameters\n",
     "\n",
-    "These parameters are found through calibration by tuning their values until the simulated streamflow matches the observations as much as possible. PAVICS-Hydro provides an integrated calibration toolbox that will be explored in the the 6th step of this tutorial. For now, we simply provided a set of parameters but it is not yet fully calibrated. This explains the poor quality of the simulated hydrograph."
+    "These parameters are found through calibration by tuning their values until the simulated streamflow matches the observations as much as possible. PAVICS-Hydro provides an integrated calibration toolbox that will be explored in the 6th step of this tutorial. For now, we simply provided a set of parameters, but it is not yet fully calibrated. This explains the poor quality of the simulated hydrograph."
    ]
   },
   {
@@ -441,7 +432,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m = HMETS(\n",
+    "m = emulators.HMETS(\n",
     "    params=(\n",
     "        9.5019,\n",
     "        0.2774,\n",
@@ -482,7 +473,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m = Mohyse(\n",
+    "m = emulators.Mohyse(\n",
     "    params=(1.0, 0.0468, 4.2952, 2.658, 0.4038, 0.0621, 0.0273, 0.0453, 0.9039, 5.6167),\n",
     "    **default_emulator_config,\n",
     ")"
@@ -501,7 +492,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m = HBVEC(\n",
+    "m = emulators.HBVEC(\n",
     "    params=(\n",
     "        0.059845,\n",
     "        4.07223,\n",
@@ -542,10 +533,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# The CanadianShield model needs atleast 2 HRUs. We have to modify the default config before executing it.\n",
+    "# The CanadianShield model needs at least two (2) HRUs. We have to modify the default config before executing it.\n",
     "default_emulator_config[\"HRUs\"] = [hru, hru]\n",
     "\n",
-    "m = CanadianShield(\n",
+    "m = emulators.CanadianShield(\n",
     "    params=(\n",
     "        4.72304300e-01,\n",
     "        8.16392200e-01,\n",
@@ -599,7 +590,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m = HYPR(\n",
+    "m = emulators.HYPR(\n",
     "    params=(\n",
     "        -1.856410e-01,\n",
     "        2.92301100e00,\n",
@@ -640,7 +631,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m = SACSMA(\n",
+    "m = emulators.SACSMA(\n",
     "    params=(\n",
     "        0.0100000,\n",
     "        0.0500000,\n",
@@ -681,7 +672,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m = Blended(\n",
+    "m = emulators.Blended(\n",
     "    params=(\n",
     "        2.930702e-02,\n",
     "        2.211166e00,\n",

diff --git a/docs/notebooks/07_Making_and_using_hotstart_files.ipynb b/docs/notebooks/07_Making_and_using_hotstart_files.ipynb
@@ -37,10 +37,10 @@
     "from matplotlib import pyplot as plt\n",
     "\n",
     "from ravenpy import Emulator, RavenWarning\n",
-    "from ravenpy.config import commands as rc\n",
     "\n",
     "# Import the GR4JCN model\n",
-    "from ravenpy.config.emulators import GR4JCN\n",
+    "from ravenpy.config import commands as rc\n",
+    "from ravenpy.config import emulators\n",
     "from ravenpy.utilities.testdata import get_file"
    ]
   },
@@ -85,7 +85,7 @@
     "}\n",
     "\n",
     "# Model configuration\n",
-    "config = GR4JCN(\n",
+    "config = emulators.GR4JCN(\n",
     "    params=[0.529, -3.396, 407.29, 1.072, 16.9, 0.947],\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",

diff --git a/docs/notebooks/09_Hydrological_impacts_of_climate_change.ipynb b/docs/notebooks/09_Hydrological_impacts_of_climate_change.ipynb
@@ -24,17 +24,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "\"\"\"\n",
-    "Import the required packages\n",
-    "\"\"\"\n",
+    "# Import the required packages\n",
     "import datetime as dt\n",
     "import warnings\n",
     "\n",
     "from matplotlib import pyplot as plt\n",
     "\n",
     "from ravenpy import Emulator\n",
     "from ravenpy.config import commands as rc\n",
-    "from ravenpy.config.emulators import GR4JCN\n",
+    "from ravenpy.config import emulators\n",
     "from ravenpy.utilities.testdata import get_file\n",
     "\n",
     "warnings.filterwarnings(\"ignore\")"
@@ -91,7 +89,7 @@
     "    }\n",
     "}\n",
     "# Start a model instance, in this case a GR4JCN model emulator.\n",
-    "m = GR4JCN(\n",
+    "m = emulators.GR4JCN(\n",
     "    params=[0.529, -3.396, 407.29, 1.072, 16.9, 0.947],\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",
@@ -139,7 +137,7 @@
     "future_ds = get_file(\"notebook_inputs/future_dataset.nc\")\n",
     "\n",
     "# Start a new model instance, again in this case a GR4JCN model emulator.\n",
-    "m = GR4JCN(\n",
+    "m = emulators.GR4JCN(\n",
     "    params=[0.529, -3.396, 407.29, 1.072, 16.9, 0.947],\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",

diff --git a/docs/notebooks/10_Data_assimilation.ipynb b/docs/notebooks/10_Data_assimilation.ipynb
@@ -47,8 +47,8 @@
     "\n",
     "from ravenpy import Emulator, EnsembleReader\n",
     "from ravenpy.config import commands as rc\n",
+    "from ravenpy.config import emulators\n",
     "from ravenpy.config import options as o\n",
-    "from ravenpy.config.emulators import GR4JCN\n",
     "from ravenpy.utilities.testdata import get_file\n",
     "\n",
     "# Import hydrometeorological data\n",
@@ -122,7 +122,7 @@
     "\n",
     "# Prepare the configuration for the spinup. Since we have added information about Ensemble Kalman Filter data\n",
     "# assimilation, a \".rve\" file will also be written to disk and Raven will use this to perform the assimilation.\n",
-    "conf_spinup = GR4JCN(\n",
+    "conf_spinup = emulators.GR4JCN(\n",
     "    # Model parameters\n",
     "    params=[0.14, -0.005, 576, 7.0, 1.1, 0.92],\n",
     "    # Meteorological gauge data from the Salmon river\n",
@@ -301,7 +301,7 @@
     "total_hydrograph = ens_loop.hydrograph\n",
     "\n",
     "# Here is where the assimilation loop is performed. We will apply the assimilation 30 successive times, advancing\n",
-    "# in time by 3 days each iteration.\n",
+    "# in time by three (3) days each iteration.\n",
     "for i in range(0, 30):\n",
     "    # Set the new start_date and end_dates\n",
     "    start_date = end_date\n",
@@ -356,12 +356,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Reset the start and end-dates to cover the entire period (spinup + 30 3-day steps)\n",
+    "# Reset the start and end-dates to cover the entire period (spinup + 30 * 3-day steps)\n",
     "start_date = dt.datetime(1996, 9, 1)\n",
     "end_date = dt.datetime(1997, 8, 31) + dt.timedelta(days=30 * 3)\n",
     "\n",
     "# Setup a standard GR4JCN model\n",
-    "conf_openloop = GR4JCN(\n",
+    "conf_openloop = emulators.GR4JCN(\n",
     "    params=[0.14, -0.005, 576, 7.0, 1.1, 0.92],\n",
     "    Gauge=gauge,\n",
     "    ObservationData=[rc.ObservationData.from_nc(salmon_meteo, alt_names=\"qobs\")],\n",
@@ -396,7 +396,7 @@
    "source": [
     "We can see that the data assimilation as vastly improved most of the hydrograph. Making the assimilation more frequent, changing other state variables, or adjusting the error model hyperparameters could also lead to better simulations.\n",
     "\n",
-    "Once we are satisfied with the initial states, our model would now be ready for forecasting, using the ensemble initial states as initial conditions for generating the forecasts. This can be done using the EnKF forecating method:"
+    "Once we are satisfied with the initial states, our model would now be ready for forecasting, using the ensemble initial states as initial conditions for generating the forecasts. This can be done using the EnKF forecasting method:"
    ]
   },
   {
@@ -415,7 +415,7 @@
     "    UniformInitialConditions=None,\n",
     "    # Set the start date equal to the end date of the last assimilation run.\n",
     "    StartDate=end_date,\n",
-    "    # Here we will do a 30-day forecast using the observed meteorological data as forecast data. However it is\n",
+    "    # Here we will do a 30-day forecast using the observed meteorological data as forecast data. However, it is\n",
     "    # possible to replace the Gauge forcing data with that of a forecast, as we have done before.\n",
     "    EndDate=end_date + dt.timedelta(days=30),\n",
     ")\n",

diff --git a/docs/notebooks/11_Climatological_ESP_forecasting.ipynb b/docs/notebooks/11_Climatological_ESP_forecasting.ipynb
@@ -29,7 +29,7 @@
     "from matplotlib import pyplot as plt\n",
     "\n",
     "from ravenpy.config import commands as rc\n",
-    "from ravenpy.config.emulators import GR4JCN\n",
+    "from ravenpy.config import emulators\n",
     "from ravenpy.utilities import forecasting\n",
     "from ravenpy.utilities.testdata import get_file"
    ]
@@ -62,7 +62,6 @@
     "forecast_duration = 100\n",
     "\n",
     "# Define HRU to build the hydrological model\n",
-    "hru = {}\n",
     "hru = dict(\n",
     "    area=4250.6,\n",
     "    elevation=843.0,\n",
@@ -89,7 +88,7 @@
     "    }\n",
     "}\n",
     "# Model configuration\n",
-    "model_config = GR4JCN(\n",
+    "model_config = emulators.GR4JCN(\n",
     "    params=[0.529, -3.396, 407.29, 1.072, 16.9, 0.947],\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",
@@ -189,7 +188,7 @@
    "metadata": {},
    "source": [
     "## Performing a climatology ESP hindcast\n",
-    "In this section, we make the hindcasts for each initialization date that we desire. Here we will extract ESP forecasts for a given calendar date for the years in \"hindcast_years\" as hindcast dates. Each ESP hindcast uses all available data in the `ts` dataset, so in this case we will have 56/57 members for each hindcast initialization depending on the date that we start on, UNLESS we specify a list of years manually. The \"hindcasts\" dataset generated contains all of the flow data from the ESP hindcasts for the initialization dates. The `q_obs` dataset contains all q_obs in the timeseries: Climpred will sort it all out during its processing. Note that the format of these datasets is tailor-made to be used in climpred, and thus has specific dimension names.\n",
+    "In this section, we make the hindcasts for each initialization date that we desire. Here we will extract ESP forecasts for a given calendar date for the years in \"hindcast_years\" as hindcast dates. Each ESP hindcast uses all available data in the `ts` dataset, so in this case we will have 56/57 members for each hindcast initialization depending on the date that we start on, UNLESS we specify a list of years manually. The \"hindcasts\" dataset generated contains all the flow data from the ESP hindcasts for the initialization dates. The `q_obs` dataset contains all q_obs in the timeseries: Climpred will sort it all out during its processing. Note that the format of these datasets is tailor-made to be used in climpred, and thus has specific dimension names.\n",
     "\n",
     "This is a slimmed down example of how we would run an ESP forecast over multiple years to assess the skill of such a forecast."
    ]

diff --git a/docs/notebooks/12_Performing_hindcasting_experiments.ipynb b/docs/notebooks/12_Performing_hindcasting_experiments.ipynb
@@ -69,7 +69,7 @@
     "    )\n",
     "ts_subset = ts_subset.resample(time=\"6H\").nearest(\n",
     "    tolerance=\"1H\"\n",
-    ")  # To make the timesteps identical accross the entire duration"
+    ")  # To make the timesteps identical across the entire duration"
    ]
   },
   {
@@ -86,7 +86,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now that we have the correct weather forecasts, we can setup the hydrological model for a warm-up run:"
+    "Now that we have the correct weather forecasts, we can set up the hydrological model for a warm-up run:"
    ]
   },
   {

diff --git a/docs/notebooks/Assess_probabilistic_flood_risk.ipynb b/docs/notebooks/Assess_probabilistic_flood_risk.ipynb
@@ -116,7 +116,7 @@
    "outputs": [],
    "source": [
     "from ravenpy.config import commands as rc\n",
-    "from ravenpy.config.emulators import GR4JCN\n",
+    "from ravenpy.config import emulators\n",
     "from ravenpy.utilities.forecasting import climatology_esp, compute_forecast_flood_risk\n",
     "\n",
     "# Choose the forecast date. Each forecast will start with the same day and month.\n",
@@ -153,7 +153,7 @@
     "    }\n",
     "}\n",
     "# Model configuration\n",
-    "model_config = GR4JCN(\n",
+    "model_config = emulators.GR4JCN(\n",
     "    params=[0.529, -3.396, 407.29, 1.072, 16.9, 0.947],\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",

diff --git a/docs/notebooks/Comparing_hindcasts_and_ESP_forecasts.ipynb b/docs/notebooks/Comparing_hindcasts_and_ESP_forecasts.ipynb
@@ -61,7 +61,6 @@
     "\n",
     "# Define some of the catchment properties. Could also be replaced by a call to the properties WPS as in\n",
     "# the Tutorial Notebook 02.\n",
-    "hru = {}\n",
     "hru = dict(\n",
     "    area=4250.6,\n",
     "    elevation=843.0,\n",
@@ -144,7 +143,7 @@
     "\n",
     "# Build a new model config:\n",
     "# Model configuration\n",
-    "model_config_ESP = GR4JCN(\n",
+    "model_config_ESP = emulators.GR4JCN(\n",
     "    params=[0.529, -3.396, 407.29, 1.072, 16.9, 0.947],\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",
@@ -258,7 +257,7 @@
     "}\n",
     "\n",
     "# Model configuration for forecasting, including correct start date and forecast duration\n",
-    "model_config_fcst = GR4JCN(\n",
+    "model_config_fcst = emulators.GR4JCN(\n",
     "    params=[0.529, -3.396, 407.29, 1.072, 16.9, 0.947],\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",