class: center, middle, inverse, title-slide # Programming Tools in Data Science ## Lecture #2: RMarkdown ### Samuel Orso ### 27 September 2021 --- # What is RMarkdown? <img src="images/markdown.png" style="width:150px; position:absolute; top:7%; left:45%" /> * RMarkdown: `R` + `markdown` * `markdown` contrasts `markup` languages (e.g. HTML) which require syntax that can be quite difficult to decipher for the uninitiated * RMarkdown is a framework that provides a literate programming format for data science. * **Literate programming**: programmers add narrative context with code to produce documentation for the program simultaneously. * **Reproducible research**: the whole process (collecting data, performing analysis, producing output,...) can be reproduced the same way by someone else. --- # What is RMarkdown? > In a nutshell, R Markdown stands on the shoulders of knitr and Pandoc. The former executes the computer code embedded in Markdown, and converts R Markdown to Markdown. The latter renders Markdown to the output format you want (such as PDF, HTML, Word, and so on). .right[-- <cite>R Markdown: The Definitive Guide</cite>] <img src="images/workflow.png" width="631" height="300" style="display: block; margin: auto;" /> --- # Is there a reproducibility crisis? <img src="images/reproducibility.png" width="453" height="385" style="display: block; margin: auto;" /> --- # Create a RMarkdown document Within RStudio, click `File` → `New File` → `R Markdown`. <img src="images/rmd_new.png" width="750" height="450" style="display: block; margin: auto;" /> --- # Important features of `markdown` * Three aspect: YAML metadata, text, code chunks --- # Important features of `markdown` ## 1. YAML Ain't Markup Language * Body of the document where everything * Surrounded by `---` * Options comprises: author, date, output format, table of content, themes, code folding, ... * Play with <https://data-analytics-lab.shinyapps.io/rmarkdown/> --- # Important features of `markdown` ## 2. Text * Core body, essential for explaining your analysis. * Markdown syntax comprises: * emphasis (*&ast;italics&ast;*, **&ast;&ast;bold&ast;&ast;**, or &grave;`code style`&grave;) * headers (# ## ###) * lists (* - + for unnumbered and 1. for numbered) * hyperlinks (<> ()[]) * blockquotes (>) * picture/gif ( !()[]) * tables (usually better to use `knitr::kable()`) --- # Important features of `markdown` ## 2. Text * `\(\LaTeX\)` in RMarkdown using the syntax `$math expression$` * Cross-referencing sections using syntax `\@ref(label)` * Citations and bibliographies can automatically be generated with RMarkdown * **You can always use HTML** * Play with <https://data-analytics-lab.shinyapps.io/rmarkdown/> --- # Important features of `RMarkdown` ## 3. Code Chunks Code chunks are specific to `RMarkdown`. It allows to embed `R` code within your document. To insert these chunks within your RMarkdown file, use either: - the keyboard shortcut Ctrl + Alt + I (OS X: Cmd + Option + I) - the Add Chunk command in the editor toolbar - by typing the chunk delimiters ` ```{r label, some option}` and ` ``` ` --- # Important features of `RMarkdown` ## 3. Code Chunks Most common chunk options: - `eval`: (TRUE; logical) whether to evaluate the code chunk; - `echo`: (TRUE; logical or numeric) whether to include R source code in the output file; - `warning`: (TRUE; logical) whether to preserve warnings (produced by warning()) in the output like we run R code in a terminal (if FALSE, all warnings will be printed in the console instead of the output document); - `cache`: (FALSE; logical) whether to "*cache*" a code chunk. It may be convenient to avoid re-running the computations and save time. - `dependson`: (label) allows to refer to objects in other chunk. --- # Important features of `RMarkdown` ## 3. Code Chunks Plot figure options: - `fig.path`: ('figure/'; character) prefix to be used for figure filenames (fig.path and chunk labels are concatenated to make filenames); - `fig.show`: ('asis'; character) how to show/arrange the plots; - `fig.width`, `fig.height`: (both are 7; numeric) width and height of the plot, to be used in the graphics device (in inches) and have to be numeric; - `fig.align`: ('default'; character) alignment of figures in the output document (possible values are left, right and center; - `fig.cap`: (NULL; character) figure caption to be used in a figure environment. --- class: sydney-blue, center, middle # Play 5 minutes with `https://data-analytics-lab.shinyapps.io/rmarkdown/` <img src="images/qrcode_data-analytics-lab.shinyapps.io.png" width="300" height="300" style="display: block; margin: auto;" /> --- # Printing an output as a table with `knitr::kable()` ```r data("iris") knitr::kable(iris[1:5,]) ``` | 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 | There are many more options that can be set to have particularly good looking table with the `knitr` and `kableExtra` packages ([click here for a detailled documentation](https://bookdown.org/yihui/rmarkdown-cookbook/kable.html)). --- # Extended table options with `knitr::kable()` and `kableExtra` ```r library(kableExtra) mtcars[1:3, 1:8] %>% kbl() %>% kable_paper(full_width = F) %>% column_spec(2, color = spec_color(mtcars$mpg[1:3]), link = "https://haozhu233.github.io/kableExtra/") %>% column_spec(6, color = "white", background = spec_color(mtcars$drat[1:3], end = 0.7), popover = paste("am:", mtcars$am[1:3])) ``` <table class=" lightable-paper" style='font-family: "Arial Narrow", arial, helvetica, sans-serif; width: auto !important; margin-left: auto; margin-right: auto;'> <thead> <tr> <th style="text-align:left;"> </th> <th style="text-align:right;"> mpg </th> <th style="text-align:right;"> cyl </th> <th style="text-align:right;"> disp </th> <th style="text-align:right;"> hp </th> <th style="text-align:right;"> drat </th> <th style="text-align:right;"> wt </th> <th style="text-align:right;"> qsec </th> <th style="text-align:right;"> vs </th> </tr> </thead> <tbody> <tr> <td style="text-align:left;"> Mazda RX4 </td> <td style="text-align:right;color: rgba(68, 1, 84, 1) !important;"> <a href="https://haozhu233.github.io/kableExtra/" style="color: rgba(68, 1, 84, 1) !important;"> 21.0 </a> </td> <td style="text-align:right;"> 6 </td> <td style="text-align:right;"> 160 </td> <td style="text-align:right;"> 110 </td> <td style="text-align:right;color: white !important;background-color: rgba(67, 191, 113, 1) !important;" data-toggle="popover" data-container="body" data-trigger="hover" data-placement="right" data-content="am: 1"> 3.90 </td> <td style="text-align:right;"> 2.620 </td> <td style="text-align:right;"> 16.46 </td> <td style="text-align:right;"> 0 </td> </tr> <tr> <td style="text-align:left;"> Mazda RX4 Wag </td> <td style="text-align:right;color: rgba(68, 1, 84, 1) !important;"> <a href="https://haozhu233.github.io/kableExtra/" style="color: rgba(68, 1, 84, 1) !important;"> 21.0 </a> </td> <td style="text-align:right;"> 6 </td> <td style="text-align:right;"> 160 </td> <td style="text-align:right;"> 110 </td> <td style="text-align:right;color: white !important;background-color: rgba(67, 191, 113, 1) !important;" data-toggle="popover" data-container="body" data-trigger="hover" data-placement="right" data-content="am: 1"> 3.90 </td> <td style="text-align:right;"> 2.875 </td> <td style="text-align:right;"> 17.02 </td> <td style="text-align:right;"> 0 </td> </tr> <tr> <td style="text-align:left;"> Datsun 710 </td> <td style="text-align:right;color: rgba(253, 231, 37, 1) !important;"> <a href="https://haozhu233.github.io/kableExtra/" style="color: rgba(253, 231, 37, 1) !important;"> 22.8 </a> </td> <td style="text-align:right;"> 4 </td> <td style="text-align:right;"> 108 </td> <td style="text-align:right;"> 93 </td> <td style="text-align:right;color: white !important;background-color: rgba(68, 1, 84, 1) !important;" data-toggle="popover" data-container="body" data-trigger="hover" data-placement="right" data-content="am: 1"> 3.85 </td> <td style="text-align:right;"> 2.320 </td> <td style="text-align:right;"> 18.61 </td> <td style="text-align:right;"> 1 </td> </tr> </tbody> </table> --- # Mathpix to easily insert math equation in `\(\LaTeX\)` <blockquote> Mathpix Snip digitizes handwritten or printed text, and copies outputs to the clipboard that can be pasted into LaTeX editors like Overleaf, Markdown editors like Typora, Microsoft Word, and more. .right[-- <cite>Mathpix Snip</cite>] </blockquote> <div align="center"> <iframe width="560" height="315" src="https://www.youtube.com/embed/Pc_6aKPYBwQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> </div> Find more informations [here](https://mathpix.com/). --- # `xaringan::infinite_moon_reader()` for live preview of your document Instant preview without fully rebuilding HTML, and the linked navigation <img src="images/gif_inf_m_r.gif" width="606" height="360" style="display: block; margin: auto;" /> --- # To go further * <https://www.markdownguide.org/> * <https://rmarkdown.rstudio.com/> * [R Markdown: The Definitive Guide](https://bookdown.org/yihui/rmarkdown/) --- class: sydney-blue, center, middle # Question ? .pull-down[ <a href="https://ptds.samorso.ch/"> .white[<svg viewBox="0 0 384 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg"> <path d="M369.9 97.9L286 14C277 5 264.8-.1 252.1-.1H48C21.5 0 0 21.5 0 48v416c0 26.5 21.5 48 48 48h288c26.5 0 48-21.5 48-48V131.9c0-12.7-5.1-25-14.1-34zM332.1 128H256V51.9l76.1 76.1zM48 464V48h160v104c0 13.3 10.7 24 24 24h104v288H48z"></path></svg> website] </a> <a href="https://github.com/ptds2021/"> .white[<svg viewBox="0 0 496 512" style="height:1em;position:relative;display:inline-block;top:.1em;" xmlns="http://www.w3.org/2000/svg"> <path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"></path></svg> GitHub] </a> ]