2  Tools

Disclaimer: This project setup tutorial has been adapted from the project report template of ME-454 Modelling and Optimisation of Energy Systems

This is a sample book written in Quarto. Quarto is an advanced version of Rmarkdown, which can combine LATEX with the simplicity of taking notes and integrating codes and calculations in the same document. Quarto is based on a text language markdown enriched with some functionalities of the Pandoc’s Markdown package that allows for example to integrate a math equation \(a^2 + b^2 = c^2\). A summary of the instructions available in Quarto are in the Cheat sheet.

2.1 Overview

In the very beginning, we introduce you the tools to be used during the course, including:

  • Virtual Machine
  • Gitlab
  • Quarto
  • Visual studio code

From Section 2.2 to 2.5 is a step-by-step tutorial for you to follow to start the project. Section 2.6 is a brief introduction how you can use Gitlab with VS code. Section 2.7 introduces the common Quarto syntax.

2.2 Step 1 - Log into your Virtual Machine

To avoid setup issues, we created a virtual machine 1 (VM) for you where all the necessary material is already installed. To access the VM, follow the instructions related to your operating system:

  • Windows
    • Open Remote Desktop Connection (installed by default on Windows).
    • Fill the computer field with the name you’ve been given (ipesevmXXX).
    • Use your usual EPFL Gaspar account as credentials.
    • Your login should look like intranet.
  • Mac
    • Install Microsoft Remote Desktop 10.
    • Open Microsoft Remote Desktop 10.
      • The first time, you have to do the following extra steps:
      • Click on the + button on the top of the app and then Desktop
      • Fill the PC name field with the name you’ve been given (ipesevmXXX) and validate by clicking on Add.
    • In the main interface, double-click on your VM unsed Saved Desktops.
    • Use your usual EPFL Gaspar account as credentials.
    • Your login should look like intranet.

2.3 Step 2 - Git Clone the project

2.3.1 Set up your Gitlab account

What is git?

Since you are from EPFL, you already have a gitlab account. If you are using gitlab for the first time, you will have to reset your password. You can do it in your perfornal profile. To do so, go to your public avatar - edit profile - Password and enter three times your gaspar password. Click Save password.

knitr::include_graphics('Figures/git_password.png')

Where to change the password in your git account

2.3.2 Clone the project repository to your VM and local machine

For this course, we prepared a git repository with the template for your final report and your starting pack for the project. Make sure that you have access to this repository. If you have any questions, do not hesitate to contact a TA.

Your project is created online. To have it locally on your VM/computer do the followings:

  1. Open your git repository in gitlab and copy the HTTPS url of your repository (Figure 2.1).
  2. Open your terminal or command prompt and go to the folder where you would like to clone your repository using the cd command. In Figure 2.2, you can see that I chose the Desktop folder.
  3. Clone the repo using the command git clone (Figure 2.2). While cloning the repo, it could be that you are asked to enter Gaspar credentials in the Password section (Figure 2.3). If you didn’t reset your password, you can not pass the authentification here.
knitr::include_graphics('Figures/url_clone.png')

Figure 2.1: Copy the URL
knitr::include_graphics('Figures/git_clone.png')

Figure 2.2: Clone the repo
knitr::include_graphics('Figures/git_login.png')

Figure 2.3: Login to git

Your repo is now in local. You can start to work on it! In the following two sections, we will briefly introduce Visual Studio Code.

2.4 Step 3 - Run the project on Visual studio code

An easy way to manage your project and git is through Visual Studio Code. You need to do the following step-by-step:

  1. Open the software, select “File” and open the folder you just cloned from the repository (Figure 2.4).
  2. Check the extensions installed. The following extensions are required for the project. You can install those extensions by clicking the tool box icon on the side bar and search them by name and the clicking “Install” (Figure 2.5).
    • Python, by Microsoft
    • Quarto, by Quarto
    • R, by REditorSupport
    • AMPL by Michael Sundvick You can as well install these extensions to help you with git:
    • Git History, by Don Jayamanne
    • Git Graph, by mhutchie
  3. Open the terminal bar in VS code (Figure 2.6)
  4. Input quarto check in the terminal and then enter to check the environment setting of you quarto (Figure 2.7).
  5. Input quarto preview in the terminal to open a temperary report on your browser(Figure 2.8). It will take several minutes for your first run. No worries and be patient. Continue reading the tutorial while the setup is being done. You can edit the content in the qmd file and the report will adapt the changes automatically when you save the changes. It is like that you are building a website or using overleaf.
  6. Open a new terminal and input quarto render in the terminal to generate a report in html format in the _book folder(Figure 2.9).
knitr::include_graphics('Figures/vs_open_folder.png')

Figure 2.4: Rosmose setup, do not install miniconda
knitr::include_graphics('Figures/vs_extensions.png')

Figure 2.5: How to install extentions
knitr::include_graphics('Figures/vs_check.png')

Figure 2.6: Where to open terminal in VS code
knitr::include_graphics('Figures/quarto_check.png')

Figure 2.7: How to preview the report
knitr::include_graphics('Figures/quarto_preview.png')

Figure 2.8: How to preview the report
knitr::include_graphics('Figures/quarto_render.png')

Figure 2.9: How to render the report

2.5 Play with Git and VS code

During the course, you will have to share your work and code with your colleagues. By VS code and Git, you can easily achive the target.

Important!!!! You can not do the following for this repository, because you are not granted manager authorities

In VS code, if you have installed the extenstion git history and git graph, you can find the Git icon on the side bar.

knitr::include_graphics('Figures/vs_git.png')

Git tools in VS code

You can see all the changes that you have made. There are three steps to save all the changes.

git add –> By clicking the “+”, you add the changes.

knitr::include_graphics('Figures/git_add.png')

Where to find git add

git commit –> Input the words you want your collaborator to see and click “Commit”, you commit your changes to your local branch

knitr::include_graphics('Figures/git_commit.png')

Where to find git commit

git push –> Push your local changes to the git server

knitr::include_graphics('Figures/git_push.png')

Where to find git push

You will find you changed the files on the git website.

knitr::include_graphics('Figures/git_server.png')

Changes on git website

You can also do all the steps above in command or terminal. You can find a lot of tutorials on google, like this one. Git is a very powerful tool and it will be very useful in your future courses or career.

2.6 Quarto syntax

2.6.1 Chunks and codes

Quarto uses chunks (also called cells) to include your codes into the report (see below). First, you define the language (r, python, …) and a label to your chunk (my-first-chunk). You decide whether you want to show the code (echo=TRUE or echo=T) or not (echo=FALSE or echo=F). The keyboard shortcut to initialize a chunk is Ctrl + Shift + i. It is worth mentioning that you can specify general settings for your code display:

knitr::opts_chunk$set(echo = F, warning = F, message = F)

I want to show the code:

consumption=10 #[kg/h]
t_op=8760 #[h/year]
cost= 2 #[CHF/kg]
total=consumption*t_op*cost
total
[1] 175200

I don’t want to show the code:

[1] 2e+05

Finally, you can use in-line calculation. For example, you want to show that the total costs are 175.2 kCHF/year. Or using latex syntax that it is 175.2 \(\frac{kCHF}{year}\). Note that the first element inside the in-line code refers to the programming language you are using, in this case, r.

2.6.2 Labels, figures, tables, equations, references

You can label chapter and section titles using {#sec-xxx} after them and refer to the with @sec-xxx, for example this is Section 2.6.2.

To write equations you can use the latex syntax in between two set of $$ symbols. To label your equation use {#eq-xxx} and refer with @eq-xxx. This is Equation 2.1. Use the character - instead of white spaces.

\[ k_{\mathrm{th}} = U_{\mathrm{env}} + \dot{m}_{\mathrm{air}} \cdot c_{p,air} \tag{2.1}\]

Figures are displayed using the following structure ![caption](path to figure){@fig-xxx}. You can add options like fig-align="left" or width=70% next to your label and you refer to the figure with @fig-xxx like in Figure 2.10.

Figure 2.10: My introductive funny picture

Of course, you can also plot your own figures directly with a quarto chunk as in Figure 2.11. To add a label to a plot from a chunk, write #| label: fig-xxx in the chunk.

Figure 2.11: Here is a nice figure!

Just like figures, tables in latex format are printed only in a pdf document. You can create tables using this link. An example is given below on Table 2.1. The caption of the table is set at the end with Table: caption. You can add a label with the format {#tbl-xxx} after the caption.

Table 2.1: My first table
category E\(^{demand}\) Heat gains Surface Q\(_{tot}\)
classroom 1 5 1 5
restaurant 2 5 2 3
offices 3 9 3 5

An option to plot tables with your own data is to use a chunk and to use the function knitr::kable() to generate the table (Ex:Table 2.2). To label your table, add #| label: tbl-xxx in the chunk.

Table 2.2: ?(caption)

(a) Here is a nice table
Sepal.Length Sepal.Width Petal.Length Petal.Width Species
5.1 3.5 1.4 0.2 setosa
4.9 3.0 1.4 0.2 setosa
4.7 3.2 1.3 0.2 setosa
4.6 3.1 1.5 0.2 setosa
5.0 3.6 1.4 0.2 setosa

You can write citations, too. For example, we are using the bookdown package (Xie. 2022) in this sample book, which was built on top of R Markdown and knitr (Xie 2015). The list of references available are in project.bib.

The bibliography is stored in the project.bib file in the book folder. You can generate this file from your bibliography management system. We recommend the use of open source system Zotero to manage biography. In zotero any subgroup of your library can be exported as a library in the report folder. If you want to change the name of the bibliography file, it is in the header of the file index.Rmd, citations can be directly obtained by a right click in the Zotero application.

When the book is built, all paths are set from the first level of the folder (where the .yml files are). Keep this in mind when you call figures and data files for your report.

2.6.3 Interactive figures

The strength of building html files instead of pdf is the interactivity they allow between the user and the report. The results are dynamic, we can zoom, select data and explore the dataset. Figure 2.12 shows an interactive plot using the library plotly.

Figure 2.12: An interactive figure produced with plotly.

Similarly, an interactive table can be embedded in the report, as shown in Figure 2.13. Pay attention that dynamic tables are treated like figures. Therefore, to refer to them, use @fig-xxx and not @tab-xxx.

Figure 2.13: A table widget rendered via the DT package.

Further Information

Further guidelines, additional features and possible customization are provided here:

In addition, you will find some documentation on Rmarkdown below. It is the former version of Quarto and shares more or less the same syntax than Quarto.

Xie, Yihui. 2015. Dynamic Documents with R and Knitr. 2nd ed. Boca Raton, Florida: Chapman; Hall/CRC. http://yihui.org/knitr/.
Xie., Yihui. 2022. Bookdown: Authoring Books and Technical Documents with r Markdown.

  1. A Virtual Machine (VM) is a compute resource that uses software instead of a physical computer to run programs and deploy apps.↩︎