Documentation adjustments

.readthedocs.yml

@@ -13,9 +13,9 @@ sphinx:
   fail_on_warning: true
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   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

README.rst

@@ -1,6 +1,6 @@
-=======
-RavenPy
-=======
+==============
+RavenPy |logo|
+==============
 
 +----------------------------+-----------------------------------------------------+
 | Versions                   | |pypi| |versions|                                   |
@@ -71,14 +71,18 @@ This package was created with Cookiecutter_ and the `Ouranosinc/cookiecutter-pyp
         :target: https://coveralls.io/github/CSHS-CWRA/RavenPy
         :alt: Coveralls
 
-.. |docs| image:: https://readthedocs.org/projects/RavenPy/badge/?version=latest
-        :target: https://ravenpy.readthedocs.io/en/latest/?version=latest
+.. |docs| image:: https://readthedocs.org/projects/ravenpy/badge/?version=latest
+        :target: https://ravenpy.readthedocs.io/en/latest
         :alt: Documentation Status
 
 .. |license| image:: https://img.shields.io/github/license/CSHS-CWRA/RavenPy.svg
         :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
+        :target: https://github.com/CSHS-CWRA/RavenPy
+        :alt: RavenPy Logo
+
 .. |ossf| image:: https://api.securityscorecards.dev/projects/github.com/CSHS-CWRA/RavenPy/badge
         :target: https://securityscorecards.dev/viewer/?uri=github.com/CSHS-CWRA/RavenPy
         :alt: OpenSSF Scorecard

docs/conf.py

@@ -213,7 +213,10 @@ def rebuild_readme():
 # theme further.  For a list of options available for each theme, see the
 # documentation.
 #
-html_theme_options = {"style_external_links": True}
+html_theme_options = {
+    "style_external_links": True,
+    "logo_only": True
+}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -222,6 +225,8 @@ def rebuild_readme():
     os.makedirs("_static")
 html_static_path = ["_static"]
 
+html_logo = "_static/_images/logos/ravenpy-logo.png"
+
 # -- Options for HTMLHelp output ---------------------------------------
 
 # Output file base name for HTML help builder.

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"
    ]
   },
   {
@@ -113,9 +104,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Import required packages. We already imported the GR4JCN emulator in the first cell, but let's keep it here for\n",
-    "# completeness.\n",
-    "from ravenpy.config.emulators import GR4JCN\n",
+    "# Import required packages. We already imported the GR4JCN emulator in the first cell.\n",
+    "# from ravenpy.config.emulators import GR4JCN\n",
     "\n",
     "# Since our meteorological gauge data is all included in a single file, we need to tell the model which variables\n",
     "# we are providing. We will generate the list now and pass it later to Ravenpy as an argument to the model.\n",
@@ -197,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",
@@ -235,9 +225,8 @@
    "outputs": [],
    "source": [
     "# If we want to import our own raven configuration files and forcing data, we can do so by importing them\n",
-    "# using the ravenpy.run  method. This will run the model exactly as the users will have designed it.\n",
-    "from ravenpy import OutputReader\n",
-    "from ravenpy.ravenpy import run\n",
+    "# using the ravenpy.run method. This will run the model exactly as the users will have designed it.\n",
+    "from ravenpy import OutputReader, ravenpy\n",
     "\n",
     "# This is used to specify the raven configuration files prefixes. In this case, we will retake the previously created files\n",
     "run_name = run_name\n",
@@ -247,7 +236,7 @@
     "configdir = workdir\n",
     "\n",
     "# Run the model and get the path to the outputs folder that can be used in the output reader.\n",
-    "outputs_path = run(modelname=run_name, configdir=configdir)\n",
+    "outputs_path = ravenpy.run(modelname=run_name, configdir=configdir)\n",
     "\n",
     "# Get the outputs using the Output Reader object.\n",
     "outputs = OutputReader(run_name=run_name, path=outputs_path)"
@@ -298,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",
@@ -401,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",
@@ -422,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."
    ]
   },
   {
@@ -443,7 +432,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m = HMETS(\n",
+    "m = emulators.HMETS(\n",
     "    params=(\n",
     "        9.5019,\n",
     "        0.2774,\n",
@@ -484,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",
     ")"
@@ -503,7 +492,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m = HBVEC(\n",
+    "m = emulators.HBVEC(\n",
     "    params=(\n",
     "        0.059845,\n",
     "        4.07223,\n",
@@ -544,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",
@@ -601,7 +590,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m = HYPR(\n",
+    "m = emulators.HYPR(\n",
     "    params=(\n",
     "        -1.856410e-01,\n",
     "        2.92301100e00,\n",
@@ -642,7 +631,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m = SACSMA(\n",
+    "m = emulators.SACSMA(\n",
     "    params=(\n",
     "        0.0100000,\n",
     "        0.0500000,\n",
@@ -683,7 +672,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "m = Blended(\n",
+    "m = emulators.Blended(\n",
     "    params=(\n",
     "        2.930702e-02,\n",
     "        2.211166e00,\n",

docs/notebooks/05_Advanced_RavenPy_configuration.ipynb

@@ -77,16 +77,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from ravenpy import OutputReader\n",
-    "from ravenpy.ravenpy import run\n",
+    "from ravenpy import OutputReader, ravenpy\n",
     "\n",
     "run_name = \"raven-gr4j-salmon\"  # As can be seen in the config above, this is the name of the .rvX files.\n",
     "configdir = config[\n",
     "    0\n",
     "].parent  # We can get the path to the folder containing the .rvX files this way\n",
     "\n",
     "# Run the model and get the path to outputs\n",
-    "outputs_path = run(modelname=run_name, configdir=configdir, overwrite=True)\n",
+    "outputs_path = ravenpy.run(modelname=run_name, configdir=configdir, overwrite=True)\n",
     "\n",
     "# Note. The modelname parameter can be confusing. You need to give the FILES extension name (run_name in our case),\n",
     "# not the name of the model.\n",
@@ -107,7 +106,7 @@
     "# compared to the one above, you should change the run_name value to this new name. It's important though that you keep the end\n",
     "# of the filename the same\n",
     "\n",
-    "# Show the list of files that were retrived by the OutputReader\n",
+    "# Show the list of files that were retrieved by the OutputReader\n",
     "outputs.files"
    ]
   },
@@ -213,7 +212,7 @@
     "\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",
     "\n",
     "# Observed weather data for the Salmon river. We extracted this using Tutorial Notebook 03 and the\n",
     "# salmon_river.geojson file as the contour.\n",
@@ -269,7 +268,7 @@
    "outputs": [],
    "source": [
     "# Run the model (See Notebook 04 for more details on implementation)\n",
-    "m = GR4JCN(\n",
+    "m = emulators.GR4JCN(\n",
     "    params=parameters,\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",
@@ -324,7 +323,7 @@
    "outputs": [],
    "source": [
     "# Run the model (See Notebook 04 for more details on implementation)\n",
-    "m = GR4JCN(\n",
+    "m = emulators.GR4JCN(\n",
     "    params=parameters,\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",
@@ -434,7 +433,7 @@
    "outputs": [],
    "source": [
     "# Run the model (See Notebook 04 for more details on implementation)\n",
-    "m = GR4JCN(\n",
+    "m = emulators.GR4JCN(\n",
     "    params=parameters,\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",
@@ -503,7 +502,7 @@
    "outputs": [],
    "source": [
     "# Run the model (See Notebook 04 for more details on implementation)\n",
-    "m = GR4JCN(\n",
+    "m = emulators.GR4JCN(\n",
     "    params=parameters,\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",

docs/notebooks/06_Raven_calibration.ipynb

@@ -32,7 +32,7 @@
     "import spotpy\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.calibration import SpotSetup"
    ]
   },
@@ -109,7 +109,7 @@
     "\n",
     "\n",
     "# We need to create the desired model with its parameters the same way as in the Notebook 04_Emulating_hydrological_models.\n",
-    "model_config = GR4JCN(\n",
+    "model_config = emulators.GR4JCN(\n",
     "    ObservationData=[rc.ObservationData.from_nc(nc_file, alt_names=\"qobs\")],\n",
     "    Gauge=[\n",
     "        rc.Gauge.from_nc(\n",

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",

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",