2 Practical information

Before diving into the exercises, some practical information is provided on how to effectively set up your working environment and how these exercises will be evaluated.

2.1 The repository

All code used to create this assignment is available at https://github.com/h-cel/hydrological-modelling-public. This collection of files is called a repository. To get started, go to the URL above, click on the green Code button and select Download ZIP (see Figure 2.1). Unzip the downloaded file and place the resulting folder at a location of your choice. This folder contains all the files you need to complete the exercises.

Figure 2.1: Screenshot of GitHub download button

Note that not only the code, but also the processed data is now downloaded. You can find this data in data/processed. More info on the data sources and processing is given in Chapter 3.

This assignment is provided to you in two formats, up to you which one you prefer to work with:

A website at https://h-cel.github.io/hydrological-modelling-public/
A PDF document, which you can download from https://h-cel.github.io/hydrological-modelling-public/Exercises-Hydrological-Modelling.pdf

Throughout the assignment, text formatted as

Tip

A hint

contains tips and recommendations to help you with the exercises. If you need an extra challenge, you can find these in text blocks formatted as

Challenge

A challenge

These challenges are always optional and are meant for those who are interested.

2.2 Working with Quarto and Python

For general introductions, please refer to the following resources:

Python and VS code tutorial: https://olivierbonte.github.io/imecos_software_guide/python_vs_code.html
Quarto tutorial: https://olivierbonte.github.io/imecos_software_guide/quarto.html

Make sure to use the conda environment provided in environment.yml. After following the guides above, you should be able to run the code in the .qmd files and render them into a PDF report.

The idea of this exercise set is that you will use Quarto to combine your code and your scientific report in a single document. The goal is to write a report following the principles of reproducible research ¹, where others have access to all the data and code needed to obtain the same results as the one you present.

In these practicals, you will therefore not write a report from scratch (in Microsoft Word, Google Docs…), but instead you’ll extend the provided .qmd files for each exercise. The files of interest are numbered from 1_...qmd to 6_...qmd. Here you can add Python code ² for your figures and write your discussion in Markdown.

Tip 2.1

Don’t perform all your computations inside of the .qmd files! Instead, make a regular .py file inside of the scripts folder for each exercise. From these .py files, you can save the results (e.g. metrics, output data) in (for example) a data/solutions folder. From this folder, you can then import the necessary results in the .qmd files to write your report and make your figures.

For functions that you reuse across multiple exercises, it is recommended to add these in a .py file inside of the src/hydromod folder. This way, you can easily import these both in your .qmd files and in .py files inside the scripts folder. For example, in src/hydromod/constants.py, a constant STEP_FACTOR is defined. We can import this constant here by using:

Code

from hydromod.constants import STEP_FACTOR

print(STEP_FACTOR)

0.01

2.3 Evaluation

The evaluation of your work will be both orally and in writing. Both forms of evaluation expect individual submissions/participation, but you are of course strongly encouraged to discuss the exercises with your colleagues during the practicals.

For the written examination, hand in the following by Sunday 13/12 23:59 on Ufora:

A PDF version of your report, which is rendered via Quarto.
The full set of files (i.e. repository) including your solution as a .zip file.

By Tuesday 10/11 23:59, you can hand in a draft version of your results and discussion for one exercise for feedback. This will not be graded and only serves as a way to help you with writing your report and using Quarto.

Your report should be written scientifically and should contain at least the following:

Per exercise, a summary of the results with reference to relevant figures and metrics and a proper discussion. Note that all tasks are related and that the results should be discussed in reference to one another in a scientific manner. The emphasis of the report should be on this part. This part should be used to draw the attention on shortcomings of the different algorithms and make a link to potential alternatives. Use the sections Results and discussion in 1...qmd to 5...qmd for writing this part down.
A conclusion about the modelling exercise as a whole, which is written in the 6_conclusion.qmd file.
Figures and tables should be labelled and referenced in the text (see Galileo for more information). Please consult the aforementioned Quarto tutorial to see how this can be achieved in .qmd files.
To support your discussion, it is valuable to include references to relevant scientific papers. To add a reference, please include the relevant source in its bibtex format to references.bib. More information on how to handle citations in Quarto can be found here. The bibtex format is explained in this guide. By means of example, one scientific article, Moore (2007), is already included.
Contrary to a full report/paper (see Galileo for a structure overview), you don’t have to write an abstract, introduction and methods section. The concept is that these are already present in the assignment themselves. This allows you to focus on the results and discussion. Note that if you e.g. tackle one of the challenges and want to add a short extra methodology section, this is of course allowed: you can add an extra section (## ...) before ## Results and discussion. `

The oral examination will be held during the exam of this course (date TBD). It will consist of a discussion on your report and code. The focus will be on methodological choices you made, how you interpreted your results and the scientific discussion.

Lastly, note that following the guidelines on the use of Generative AI tools, you are allowed to use GenAI tools to help you with this report. Remember though that you are still responsible for the content of your report and code, and will be orally evaluated on your capacity to explain your work. Please mention at the end of your report (in the 6_conclusion.qmd file in a new section) which GenAI tools you used (if any) and for what purpose.

This concept is introduced in your course on Data Science in the 2nd Bachelor year of Bioscience Engineering, where you made a Quarto/Rmarkdown presentation/report for a data analysis↩︎
As an example of how this is used in practice, see e.g. the source file 0_study_area_and_data.qmd for Chapter 3 ↩︎