2  Tools

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 semester, including:

• Virtual Machine
• Gitlab
• Quarto
• Visual studio code

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

2.2 Step 1 - Log in and off your Virtual Machine

To avoid setup issues, we created a virtual machine ¹ (VM) for you where all the necessary material is already installed. To access the VM, you have to install VMware Horizon and to log on STI-FM-cours-2024 with your EPFL Gaspar account. As you connect to the VM, a terminal window will open and download VScode extensions (Figure 2.1). Let the terminal complete the downloads and don’t close it, it will close automatically once it is done.

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

Figure 2.1

As you log off, please click on the icon LOGOFF SESSION on the desktop. Note that you will as well be disconnected if you close VMware for a few minutes.

Important here!!!!! Everything that is stored on the VM will be erased once you log off. Therefore, store your project files in your personal document folder. Don’t forget to regularly send your work progress on gitlab (commit + push), especially when you log-off.

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. We will grant you access to the repo of your group once you formed your project group. 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.2).
2. Open command prompt and go to the folder where you would like to clone your repository using the cd command. In Figure 2.3, you can see that I chose the Desktop folder.
3. Clone the repo using the command git clone (Figure 2.3). While cloning the repo, it could be that you are asked to enter Gaspar credentials in the Password section (Figure 2.4). If you didn’t reset your password, you can not pass the authentification here.
4. Move your git repository to your personal documents so that it is store after the VMs log off.

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

Figure 2.2: Copy the URL

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

Figure 2.3: Clone the repo

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

Figure 2.4: 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.5).
2. Check the extensions installed. The following extensions are required for the project and should be already installed. If not, you can install those extensions by clicking the extensions icon on the left side, search them by name and the clicking “Install” (Figure 2.6).
   • Python, by Microsoft
   • Quarto, by Quarto
   • R, by REditorSupport
   • AMPL by Michael Sundvick
   • Git Graph, by mhutchie
3. Open the file index.qmd, click on the three dots on the upper right side and click on preview (Figure 2.7). It will generate your report.

If everything went smoothly until now, then please receive my congratulations. You have finished the set-up processes that took the TA team 2 months to prepare.

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

Figure 2.5: Rosmose setup, do not install miniconda

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

Figure 2.6: How to install extentions

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

Figure 2.7: How to preview the report

2.5 Play with Git and VS code

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

In VS code, you will find the source control icon on the side bar and the git graph at the top of the source control window.

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 changes.

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

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

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

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

Where to find git push

The first time you commit cour changes, you might encounter the follwing error:

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

Error message while commiting changes

To solve it, enter the following commands with your identifiers in a new terminal:

• git config --global user.email "your_mail.adress@epfl.ch"
• git config --global user.name "your_name"

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

Enter your git credentials

You can also do all the steps above in command prompt. 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 and 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 you 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}\).

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.8.

Figure 2.8: My introductive funny picture

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

Figure 2.9: 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: 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.10 shows an interactive plot using the library plotly.

Figure 2.10: An interactive figure produced with plotly.

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

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

Further Information

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

• Quarto: The Guide
• Labeling and referencing

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. a * Authoring Books and Technical Documents with R Markdown, * R Markdown Cookbook.

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.