Workshops

book/_config.yml

@@ -1,5 +1,5 @@
 title: eWaterCycle projects
-author: Rolf Hut (Delft University of Technology) & the ever growing eWaterCycle team (Netherlands eScience Center, Delft University of Technology), built with <a href="https://teachbooks.tudelft.nl/">TeachBooks</a> and <a href="https://jupyterbook.org/">Jupyter Book</a>, <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer"">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt=""></a> #add your own name here
+author: Rolf Hut & Mark Melotto (Delft University of Technology) & the ever growing eWaterCycle team (Netherlands eScience Center, Delft University of Technology), built with <a href="https://teachbooks.tudelft.nl/">TeachBooks</a> and <a href="https://jupyterbook.org/">Jupyter Book</a>, <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer"">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt=""></a> #add your own name here
 logo: figures/ewatercycle_logo.png #add your own logo here
 
 execute:
@@ -10,7 +10,8 @@ only_build_toc_files: true
 html:
   favicon : "figures/TUD_favicon.ico"
   baseurl :  "https://teachbooks.io/" #Replace this with your own URL
-
+  extra_js:
+    - _static/custom_launch_button.js
 sphinx:
   config:
     html_js_files:
@@ -20,12 +21,12 @@ sphinx:
       exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"]
     html_theme_options:
       repository_url: "https://github.com/eWaterCycle/projects" #add your own repo URL here
-      repository_branch: main
+      repository_branch: workshops
       path_to_docs: book
       use_repository_button: true
       use_issues_button : true
       launch_buttons:
-        jupyterhub_url: https://ewatercyclegu25.ewatercycle-tud.src.surf-hosted.nl/jupyter
+        jupyterhub_url: https://ewatercycleaf.ewatercycle-tud.src.surf-hosted.nl/jupyter
         notebook_interface: "jupyterlab"
         thebe: true
     html_show_copyright: false

book/_static/custom_launch_button.js

@@ -0,0 +1,69 @@
+// This code is used to make the launch button on top of the webpage
+
+window.addEventListener("DOMContentLoaded", () => {
+  // Create the modal HTML
+  const modalHTML = `
+    <div id="customModal" style="display:none; position:fixed; top:0; left:0; width:100%; height:100%; background-color:rgba(0,0,0,0.5); z-index:1000;">
+      <div style="background:white; padding:20px; max-width:400px; margin:100px auto; border-radius:8px; box-shadow:0 2px 10px rgba(0,0,0,0.3);">
+        <h3 style="margin-top:0;">Enter your JupyterHub URL</h3>
+        <input type="text" id="jupyterUrlInput" value="https://ewatercycleaf.ewatercycle-tud.src.surf-hosted.nl/jupyter" style="width:100%; padding:8px; margin-top:10px;"/>
+        <div style="margin-top:15px; text-align:right;">
+          <button id="launchBtn" style="padding:8px 12px; margin-right:10px;">Launch</button>
+          <button id="cancelBtn" style="padding:8px 12px;">Cancel</button>
+        </div>
+      </div>
+    </div>
+  `;
+  document.body.insertAdjacentHTML("beforeend", modalHTML);
+
+  // Create the custom button
+  const header = document.querySelector("header");
+  if (header) {
+    const customButton = document.createElement("a");
+    customButton.textContent = "🚀 Launch eWaterCycle JupyterHub";
+    customButton.className = "custom-launch-button";
+    customButton.style.backgroundColor = "#007ACC";
+    customButton.style.color = "white";
+    customButton.style.padding = "6px 12px";
+    customButton.style.marginLeft = "10px";
+    customButton.style.borderRadius = "4px";
+    customButton.style.textDecoration = "none";
+    customButton.style.fontWeight = "bold";
+    customButton.style.cursor = "pointer";
+
+    customButton.addEventListener("click", () => {
+      document.getElementById("customModal").style.display = "block";
+    });
+
+    header.appendChild(customButton);
+  }
+
+  // Modal button logic
+  const launchBtn = document.getElementById("launchBtn");
+  const cancelBtn = document.getElementById("cancelBtn");
+  const input = document.getElementById("jupyterUrlInput");
+  const modal = document.getElementById("customModal");
+
+  launchBtn.addEventListener("click", () => {
+    const baseUrl = input.value.trim();
+
+    if (baseUrl.startsWith("https://")) {
+      const repo = encodeURIComponent("https://github.com/eWaterCycle/projects");
+      const branch = "workshops";
+      // const notebookPath = "getting-started/book/content/first_model_run/first_run.ipynb"; // Change to your desired notebook
+      const notebookPath = "projects/book/tutorials_examples/7_Caravan/1a_HBV.ipynb"; // Change to your desired notebook
+
+      const nbgitpullerUrl = `${baseUrl}/hub/user-redirect/git-pull?repo=${repo}&branch=${branch}&urlpath=lab/tree/${notebookPath}`;
+      window.open(nbgitpullerUrl, "_blank");
+      modal.style.display = "none";
+      input.value = "";
+    } else {
+      alert("Please enter a valid HTTPS URL.");
+    }
+  });
+
+  cancelBtn.addEventListener("click", () => {
+    modal.style.display = "none";
+    input.value = "";
+  });
+});

book/_toc.yml

@@ -128,6 +128,64 @@ parts:
       sections:
       - file: tutorials_examples/1_HBV_Caravan_ERA5/example_model_run_HBV.ipynb
       - file: tutorials_examples/2_HBV_PCRGlobWB_ERA5/example_model_run_pcrglobwb.ipynb
+
+  - caption: Workshops Caravan
+    chapters:
+    - file: tutorials_examples/7_Caravan/Workshop_Caravan.md
+      sections:
+      - file: tutorials_examples/7_Caravan/1a_HBV.ipynb
+      - file: tutorials_examples/7_Caravan/1b_ERA5.ipynb
+      - file: tutorials_examples/7_Caravan/2b_calibrate_HBV_SCE.ipynb
+      - file: tutorials_examples/7_Caravan/3a_CMIP.ipynb
+      - file: tutorials_examples/7_Caravan/3b_CMIP.ipynb
+      - file: tutorials_examples/7_Caravan/4_analysis.ipynb
+
+
+  - caption: Workshops SAFE4ALL part 1
+    chapters:
+    - file: tutorials_examples/3_Zimbabwe/1_HBV_Zimbabwe.ipynb
+      sections:
+      - file: tutorials_examples/3_Zimbabwe/2a_CMIP_Zimbabwe.ipynb
+      - file: tutorials_examples/3_Zimbabwe/2b_CMIP_Zimbabwe.ipynb
+      - file: tutorials_examples/3_Zimbabwe/2c_CMIP_Zimbabwe.ipynb
+    - file: tutorials_examples/4_Ghana/1_HBV_Ghana.ipynb
+      sections:
+      - file: tutorials_examples/4_Ghana/2a_CMIP_Ghana.ipynb
+      - file: tutorials_examples/4_Ghana/2b_CMIP_Ghana.ipynb
+      - file: tutorials_examples/4_Ghana/2c_CMIP_Ghana.ipynb
+    - file: tutorials_examples/5_Kenya/1_HBV_Kenya.ipynb
+      sections:
+      - file: tutorials_examples/5_Kenya/2a_CMIP_Kenya.ipynb
+      - file: tutorials_examples/5_Kenya/2b_CMIP_Kenya.ipynb
+      - file: tutorials_examples/5_Kenya/2c_CMIP_Kenya.ipynb
+
+  - caption: Workshops SAFE4ALL part 2
+    chapters:
+    - file: tutorials_examples/6_Africa/Workshop_Africa.md
+      sections:
+      - file: tutorials_examples/6_Africa/1a_HBV_Africa.ipynb
+      - file: tutorials_examples/6_Africa/1b_ERA5_Africa.ipynb
+      - file: tutorials_examples/6_Africa/2a_calibrate_HBV_montecarlo.ipynb
+      - file: tutorials_examples/6_Africa/2b_calibrate_HBV_SCE.ipynb
+      - file: tutorials_examples/6_Africa/3a_CMIP_Africa.ipynb
+      - file: tutorials_examples/6_Africa/3b_CMIP_Africa.ipynb
+      - file: tutorials_examples/6_Africa/3c_CMIP_Africa.ipynb
+      - file: tutorials_examples/6_Africa/4_analysis_Africa.ipynb
+
+  - caption: Climate Impact Analysis (first draft)
+    chapters:
+    - file: colloquium/README.md
+    sections:
+      - file: colloquium/step_0a_select_caravan_region_time_and_scenarios.ipynb
+      - file: colloquium/step_0b_select_CMIP_forcing.ipynb
+      - file: colloquium/step_1a_generate_historical_forcing.ipynb
+      - file: colloquium/step_1b_generate_future_forcing.ipynb
+      - file: colloquium/step_2a_calibrate_HBV_by_hand.ipynb
+      - file: colloquium/step_2b_calibrate_HBV_montecarlo.ipynb
+      - file: colloquium/step_3a_model_run_historical.ipynb
+      - file: colloquium/step_3b_model_run_future.ipynb
+      - file: colloquium/step_4_analyse.ipynb
+
   - caption: Credits
     chapters:
     - file: changelog.md

book/colloquium/README.md

@@ -0,0 +1,82 @@
+# Impact and uncertainty of Climate Change on future river discharge using the eWaterCycle platform
+
+This repo contains a workflow that allows users to model the impact of climate change on river discharge for any river where observations of river discharge are available in the Caravan dataset [Katzert](todo:ref). The workflow is designed to be flexible and leverage the advantages of the eWaterCycle platform [ref: Hut 2022](todo:ref). The workflow is build to work with the HBV hydrological model to translate athomspheric forcing, but is easily adjustable to any hydroligcal model supported by eWaterCycle. As an example we run a climate change impact analysis for the Wallkill river in upstate New York, USA. As climate model we use the Max Planck Institute for Meteorology Earth System Model (MPI-ESM1.2, [Gutjahr 2019](https://doi.org/10.5194/gmd-12-3241-2019)). The choice of climate model is also easily changed to any model output available through ESGF [todo:ref](todo:ref).  
+
+## Workflow description
+The workflow consist of four major steps, spread out over seven jupyter notebooks. The workflow is designed such that the selection of region from caravan and climate models from ESGF are made a priori using a seperate notebook and stored in a json file. Each notebook in the workflow reads this json file. In this way no changes need to be made when the workflow is run for another region and/or another climate model. Selection of region and climate model and scenarios is done in the [step_0a_select_caravan_region_time_and_scenarios](step_0a_select_caravan_region_time_and_scenarios.ipynb) notebook. Selecting a climate model and scenarios can be daunting given the wide range of available models and scenarios. The [step_0b_select_CMIP_forcing](step_0b_select_CMIP_forcing.ipynb) provides a list of compatible models to choose from for the given model (HBV in our case).
+
+After the selection of region and climate model in the notebook  is done, the three major steps of the workflow are generating forcing, calibrating HBV model and running HBV model. Finally, in step 4, the model output is analysed and graphs of expected impact of climate change on river discharge are made.
+
+### Overview of the workflow
+The figure below summarizes the workflow graphically.
+
+### step 1: Generate forcing for HBV
+The HBV model needs precipitation, temperature and potential evaporation information as input to calculate river discharge. These inputs are called 'forcing'. Furthermore, it has nine parameters that need to be calibrated for specific regions. Calibration is by comparing model output to observed streamflow measurements and optimizing the parameters. For calibration we use ERA5 as forcing. ERA5 is re-analyses data which has been constrained by observations to give best estimates of actual on earth weather. The climate data for histroical periods on the other hand are not constrained by observations: while climate models are made to be statistical correct, they can never match day to day values because of the chaotic nature of the athmospheric system. To analyse potential biases caused by using ERA5 for calibration and climate data for analyses, we need to analyse the differences in those data sources. Therefore, we generate:
+
+- forcing for HBV model for the chosen region, for the period where we have discharge observations, from both ERA5 and from the historical runs of the climate model in [this](step_1a_generate_historical_forcing.ipynb) notebook.
+- forcing for HBV model for the chosen region, for the future period of interest, for all climate scenarios of interest from chosen climate model in [this](step_1a_generate_future_forcing.ipynb) notebook.
+
+Forcing is saved in a structured directory system on the users home directory for easy reading by the next steps of the workflow.
+
+### step 2: calibrate the HBV model
+Two different methods for calibration are provided. [This](step_2b_calibrate_HBV_montecarlo.ipynb) notebook provides a basic Monte Carlo calibration scheme. While this is not very computationally effective in finding the optimal paramters for a nine dimensional parameter space, it does provide a very clear overview of how the eWaterCycle platform, including the Data Assimilation extension to run ensembles of models, can be used.
+
+A more effective way to calibrate is to use modern methods like Shuffle Complex Evolution (SCE) to systematically and efficiently work towards an optimal set of parameters. [This](step_2c_calibrate_HBV_SCE.ipynb) notebook does that. The code still leverages the eWaterCycle platforms flexibillity, but is a bit harder to read than the Monte Carlo example. The results, however, are much better and the parameters found using this method are used for the model runs. The resulting parameters are saved in a json file together with the forcing used, to make sure those stay together. 
+
+### step 3: run HBV model to generate discharge estimates
+The running of the HBV model, simple though it may be, is also split over two different notebooks. For the historical runs, where the model is forced either with ERA5 forcing data, or with climate model data, is done in [this](step_3a_model_run_historical.ipynb) notebook. This is a typical example of how the eWaterCycle platform can be used for a comparison study. The resulting estimation of river discharge is saved in netcdf files together with the forcing data so it can be easily read in the analyses step later on.
+
+For generating the estimation of future river discharge under different climate scenarios we take a different approach in [this](step_3a_model_run_future.ipynb) notebook. Here I use the data assimilation extension to create an ensemble of model objects. This showcases how different models can be run using a single command with this extension. 
+
+### step 4: analyse results
+Finally, in [this](step_3a_model_run_historical.ipynb) notebook we load the results from the model runs and do statistical analyses to see the projected effect of climate change on the region of interest given the climate model of choice. To assess biases we first look at the statistical differences between the observed discharge, the projected discharge when using ERA5 forcing and when using climate model forcing. We use Metastatistical Extreme Value (MEV) to asses the differences in projected maximum values, which is relevant for flood forecasting. When these differences are small between discharge generated with ERA5 forcing and with climate models and when both are close to the observed values, this gives confidence that HBV model is well capable of generating accurate discharge estimations.
+
+We than finalize by estimating the distrubtion of extreme events of river discharge for the different future climate predictions and compare these to the historical distributions. We can derive from this how much more likely we expect certain values of extreme discharge to become under different climate scenarios.
+
+## running this workflow for a different region
+To run this analysis for a different region:
+
+- open [this step_0a](step_0a_select_caravan_region_time_and_scenarios.ipynb) notebook
+- Read it through and follow the link to the online caravan map.
+- Select a region of interest and copy the caravan ```basin_id```
+- paste the ```basin_id``` into the right cell
+- run all notebooks in order of steps.
+
+## running this workflow for a different climate model
+To run this analysis for a different (selection of) climate model(s)
+
+- open [this step_0b](step_0b_select_CMIP_forcing.ipynb) notebook
+- Change the experiments of interest if needed
+- Run the notebook. Note that this can take quite some time (half an hour easily)
+- choose which combination of climate model and ensemble member you want to run.
+- open [this step_0a](step_0a_select_caravan_region_time_and_scenarios.ipynb) notebook
+- change the cell with ```settings["CMIP_info"]``` to reflect your choices
+- run all notebooks in order of steps. Note that although CMIP datasets might exist, not all servers are always online. It could be you get an error when generating climate data forcing because the server that is supposed to host the data from that particular climate model might be down.
+
+## running this workflow for a different hydrological model
+This is a bit more involved, but still doable because of the flexible nature of eWaterCycle. It is strongly suggested to first look at the 'run model' example for your model of choice, provided with the documentation of that models eWaterCycle plugin repo, before proceeding. After that:
+
+### change settings
+- in [this step_0a](step_0a_select_caravan_region_time_and_scenarios.ipynb) notebook change the base_path to reflect your model choice and to make sure you don't overwrite the output for HBV. 
+
+### generate forcing
+- Find out which parameters your model need for forcing. This should be documented in the model plugin repository. If your model can take ```lumpedmakking``` style ewatercycle forcing, skip to 'calibrate model' below
+- Find out which climate models have the required parameters available using [this step_0b](step_0b_select_CMIP_forcing.ipynb) notebook.
+- change the 1a and 1b notebooks to reflect your model choice. You will need to change the ```ewatercycle.foring.generate``` calls.
+
+### calibrate model
+If your model needs calibration:
+
+- change the step 2b notebook to reflect your own model. It might be wise to first change the "run model" notebooks and subsequently change the calibration
+
+If your model needs external parameter sets (most distributed models)
+
+- rewrite step 2 to generate and point at the correct parameter set.
+
+### run model
+Adjust the 3a and 3b notebooks to run your model. For lumped models like HBV this might be as easy as only changing the call that generates the model object and changing the size of the parameters array. For distrubted models, usually parameter sets have to be externally provided (see above).
+
+## Citing this work
+
+- todo: get DOI, put citation info here
+