
# Tools {#sec-tool}

## Overview

In this section, we will introduce the tools you will use during the semester, including:

- Virtual Machine
- Quarto

From **Section 1.2 to 1.5** is a step-by-step tutorial for you to follow to start the project. **Section 1.6** is a brief introduction on how you can use Gitlab with VS code.
**Section 1.7** introduces the common Quarto syntax.

## Step one: 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, you have to install [VMware Horizon](https://vdi.epfl.ch/) and to log on **STI-FM-cours** with your EPFL Gaspar account. 

**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. However, python is not able to access your document folder due to path issues on Windows. While you are working on the project, move your project folder from your documents to the desktop to by-pass this issue. Then before log-off, move it back to your document folder or send your changes online (`commit` + `push`). We will try to find another way to avoid this copy-pasting step.

## Step two: Quarto syntax {#rmd-syntax}

Open Visual Studio Code.

### Quarto on VSCode

In VSCode, open a new terminal @fig-terminal.

![Opening a terminal on VSCode](Figures/vs_check.PNG){#fig-terminal fig-align="left" width=70%}

Check if you have the quarto extensions in VSCode @fig-extension.

![Quarto extensions](Figures/vs_extensions.PNG){#fig-extension fig-align="left" width=70%}

See if you have the good version of quarto installed by typing **quarto check** in the terminal @fig-check.

![Quarto check](Figures/quarto_check.PNG){#fig-check fig-align="left" width=70%}

### Chunks and codes
Rmarkdown uses chunks 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` + `Alt` + `I`. It is worth mentioning that you can specify general settings for your code display:
```{r setup}
knitr::opts_chunk$set(echo = F, warning = F, message = F)
```

I want to show the code:

```{r my first chunk, echo=TRUE}
consumption=10 #[kg/h]
t_op=8760 #[h/year]
cost= 2 #[CHF/kg]
total=consumption*t_op*cost
total
```

I don't want to show the code:

```{r my second chunk, echo=F}
total=200000
total
```

Finally, you can use in-line calculations. For example, you want to show that the total costs are `r consumption*t_op*cost/1000` kCHF/year. Or using latex syntax that it is `r consumption*t_op*cost/1000` $\frac{kCHF}{year}$.


### Labels, figures, tables, equations, references {#sec-tuto}

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

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 @eq-my-label. Use the character `-` instead of white spaces.

$$
k_{\mathrm{th}} = U_{\mathrm{env}} + \dot{m}_{\mathrm{air}} \cdot c_{p,air}
$$ {#eq-my-label}

Figures are displayed using the following structure `![caption](path to figure){@fig-xxx fig-align="left" width=70%}` and you refer to the figure with `@fig-xxx` like in @fig-intro.

![My introductive funny picture](Figures/intro_figure.PNG){#fig-intro fig-align="left" width=70%}

Of course you can also plot your own figures directly with a quarto chunk as in @fig-plots.
```{r nice-fig, fig.cap='Here is a nice figure!', out.width='80%', fig.asp=.75, fig.align='center'}
#| label: fig-plots
plot(pressure, type = 'b', pch = 19)
```


Just like figures, tables in latex format are printed only in a pdf document. You can create tables using this [link](https://www.tablesgenerator.com/markdown_tables). An example is given below on @tbl-occupancy. The caption of the table is set at the end with `Table: caption`. You can also add a label with the format `{#tbl-xxx}` after the caption.


|category|E$^{demand}$|Heat gains|Surface|Q$_{tot}$|
|--------  |:-|:----:|:--:|---:|
|classroom | 1  | 5  |  1 |  5 |
|restaurant| 2  | 5  |  2 |  3 |
|offices   | 3  |   9| 3  | 5  |
Table: My first table {#tbl-occupancy}


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:@tbl-kable). To label your table, add `#| label: tbl-xxx` in the chunk.


```{r nice-tab, tidy=FALSE}
#| label: tbl-kable
knitr::kable(
  head(iris, 5), caption = 'Here is a nice table',
  booktabs = TRUE

)
```


You can write citations, too. For example, we are using the **bookdown** package [@R-bookdown] in this sample book, which was built on top of R Markdown and **knitr** [@xie2015].

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](https://www.zotero.org) 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 build, 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. 


### 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. @fig-ggplot-figure shows an interactive plot using the library plotly.


```{r plot-library, echo=F, fig.cap= 'An interactive figure produced with plotly.'}
#| label: fig-ggplot-figure
library(ggplot2)
library(plotly, warn.conflicts=FALSE)

p <- ggplot(data = diamonds, aes(x = cut, fill = clarity)) +
            geom_bar(position = "dodge")
ggplotly(p)
```


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

```{r table-widget, echo=F, fig.cap= 'A table widget rendered via the DT package.'}
#| label: fig-kables
library(DT)
datatable(
  iris,
  caption = NULL
)
```

More information on labels and referencing is given [here](https://quarto.org/docs/authoring/cross-references.html)

This is a _sample_ book written in   [Quarto](https://quarto.org/). **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. This text writing language is based on a text language [markdown](https://daringfireball.net/projects/markdown/basics) enriched with some functionalities of the [Pandoc's Markdown](https://pandoc.org/MANUAL.html#pandocs-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](https://quarto.org/docs/get-started/hello/rstudio.html). 

### Display

To display your quarto file, use the command **quarto preview** @fig-preview in the terminal. The preview appears in your Web browser. 

![Quarto preview](Figures/quarto_preview.PNG){#fig-preview fig-align="left" width=70%}

You can also use the command **quarto render** @fig-render in the terminal. The render appears directly in VSCode @fig-vs. 

![Quarto render](Figures/quarto_render.PNG){#fig-render fig-align="left" width=70%}

![Quarto render in VSCode](Figures/render.PNG){#fig-vs fig-align="left" width=70%}

[^1]: <span style="font-family:Calibri; font-size: 0.8em;"> A Virtual Machine (VM) is a compute resource that uses software instead of a physical computer to run programs and deploy apps. </span>.