Rmarkdown (primeras ideas)

class: inverse, center, middle

<br>

#### Programación y manejo de datos con R (Slides 07)

### Rmarkdown (primeras ideas)

<br>

### Pedro J. Pérez

#### 2020, septiembre

###### (actualizadas el 07-09-2022)

<br><br>
  
#### e-mail: [pedro.j.perez@uv.es](mailto:pedro.j.perez@uv.es)
  
#### Web del curso: [https://perezp44.github.io/intro-ds-22-23-web](https://perezp44.github.io/intro-ds-22-23-web)

---
class: inverse, center, middle
background-image: url(imagenes/ss_00_new_logo_rmd.png)
background-position: 99% 1%
background-size: 5%

### La última étapa de un análisis es ... comunicar

#### Lo haremos con Rmarkdown

---
class: inverse, center, middle
background-image: url(imagenes/ss_00_new_logo_rmd.png)
background-position: 99% 1%
background-size: 5%

### ¿Qué es Rmarkdown? ¿Para que sirve?

<br>

#### Podemos pensar que es un ["entorno"](https://vimeo.com/178485416) para hacer informes/publicaciones/transparencias REPRODUCIBLES.

<br>

.center[Is an authoring framework for data science, combining your code, its results, and your prose. R Markdown documents are fully reproducible and support dozens of output formats, like PDFs, Word files, slideshows, and more]

<br>

---
background-image: url(imagenes/ss_00_new_logo_rmd.png)
background-position: 99% 1%
background-size: 4%

##### ¿de verdad necesito conocer Rmarkdown?

- **SÍ!!** Puede [transformar tu forma de trabajar](https://rfortherestofus.com/2019/03/r-killer-feature-rmarkdown/)

- Todos tenemos que hacer documentos con algún contenido estadístico: informes o transparencias o .... **`Rmarkdown`** hace posible que podamos hacer esos documentos **directamente desde R**. Además, nuestros informes serán [Reproducibles!!](https://www.youtube.com/watch?v=s3JldKoA0zw)

##### además, con Rmd se pueden generar multitud de outputs

- Por ejemplo, visita [está galería](https://rmarkdown.rstudio.com/gallery.html) o [este listado](https://rmarkdown.rstudio.com/formats.html)

<br>

##### le damos una oportunidad a **R**markdown?? 🤔  ok, vale!!!

- Vamos a trabajar con .bg-orange[documentos Rmd]; es decir, con documentos con **extensión** .bg-orange[extensión .Rmd]

<br>

##### ¿cómo se crea un fichero .Rmd?

- Por menús de RStudio: **File > New File > R Markdown ...**

---
background-image: url(imagenes/ss_00_new_logo_rmd.png)
background-position: 99% 1%
background-size: 4%

##### los documentos `.Rmd` tienen 3 partes

1. Encabezamiento (yaml header)  
2. Trozos de código R (R chunks)  
3. Texto (narratives)

##### Un ejemplo

.pull-left[

````
---
title: "El título de mi informe"
author: "Yo mismo"
date: "Marzo de 2017"
output: html_document
---

En este informe haremos un resumen (o summary) del conjunto de datos iris.

```{r}
summary(iris)
```

El trozo de arriba es un chunk de código R. Cuando compile el documento, knitr ejecutará el código y mostrará los resultados en el documento final.

Con esto finalizamos este informe.
````

]

.pull-right[

- Cada .Rmd file se compila en su sesión.

- El wd es donde está el archivo .Rmd

]

---
background-image: url(imagenes/ss_00_new_logo_rmd.png)
background-position: 99% 1%
background-size: 4%

##### (I) El encabezamiento o "yaml header"

- Se (suele) poner al ppio del documento, entre estas marcas: `---`

- En el yaml son importantes los espacios y la indentación

- [Aquí](https://scienceloft.com/technical/useful-yaml-options-for-generating-html-reports-in-r/) puedes aprender más sobre el `yaml`, o en el [manual de Pandoc](https://pandoc.org/MANUAL.html)

##### Otro ejemplo de yaml

```
---
title: "Documentos Rmarkdown (.Rmd)"
author: "Pedro J. Pérez"
date: "`r Sys.Date()`"  
output:
  html_document:
    code_folding: show
    theme: journal
    toc: yes
    toc_float: yes
---
```

---
background-image: url(imagenes/ss_00_new_logo_rmd.png)
background-position: 99% 1%
background-size: 4%

##### (IIa) Código R (chunks)

- Para que `knitr` sepa qué partes del .Rmd es código R, deben ir dentro de estas marcas:

````
```{r}

```    
````

##### Por ejemplo

````
```{r}   
# Se pueden poner comentarios (de la forma habitual)
aa <- c(1, 4, 16, 64)
sqrt(aa)
```    
````

- Cuando `knitr` procese el chunk, lo interpretará como código R y ejecutará las instrucciones y mostrará en el documento final el output generado por el chunk.

##### Por ejemplo, el anterior chunk generará el siguiente output:

```r
# Se pueden poner comentarios (de la forma habitual)
aa <- c(1, 4, 16, 64)
sqrt(aa)
#> [1] 1 2 4 8
```

---
background-image: url(imagenes/ss_00_new_logo_rmd.png)
background-position: 99% 1%
background-size: 4%

##### Los chunks pueden tener opciones

- Estas opciones permiten una mayor flexibilidad a la hora de decidir cómo mostrar el código y los resultados en el documento final. Las opciones más usadas son: `echo` y `eval`.

- Por ejemplo:

.pull-left[
````
```{r, echo = TRUE, eval = TRUE}   
library(tidyverse)
iris %>% summarise(across(1:3, mean))
```
````
]

.pull-right[
````
```{r, echo = TRUE, eval = FALSE} 
library(tidyverse)
iris %>% summarise(across(1:3, mean))
```    
````
]

.pull-left[

```r
library(tidyverse)
iris %>% summarise(across(1:3, mean))
#>   Sepal.Length Sepal.Width Petal.Length
#> 1     5.843333    3.057333        3.758
```
]

.pull-right[

```r
library(tidyverse)
iris %>% summarise(across(1:3, mean))
```
]

<br>

- Una opción más a conocer es : .yellow-h[results = "hide"]

- Si quieres ver las opciones disponibles para los chunks tendrás que ir a la [página web de knitr](https://yihui.name/knitr/options/), a la [cheat sheet sobre Rmarkdown](https://raw.githubusercontent.com/rstudio/cheatsheets/master/rmarkdown-2.0.pdf), o a la [Reference Guide](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf)

---
background-image: url(imagenes/ss_00_new_logo_rmd.png)
background-position: 99% 1%
background-size: 4%

##### chunk inicial con "global settings"

- Sí, los documentos `.Rmd` suelen tener un chunk inicial con las opciones por defecto para los siguientes chunks.

- Por ejemplo, el chunk inicial que suelo usar es parecido a este:

````
```{r chunk-setup, include = FALSE}
knitr::opts_chunk$set(echo = TRUE, eval = TRUE, message = FALSE, warning = FALSE,
                      collapse = TRUE,
                      #fig.width = 7, #fig.height= 7,
                      fig.asp = 7/9, out.width = "95%", 
                      fig.align = "center", fig.show = "hold")
                      
options(scipen = 999) #- para quitar la notación científica
```
````

---
background-image: url(imagenes/ss_00_new_logo_rmd.png)
background-position: 99% 1%
background-size: 4%

##### nueva sintaxis para las opciones de los chunks

- Con [knitr v1.35](https://github.com/yihui/knitr/releases) se ha habilitado una nueva sintaxis para las opciones de los chunks.

- Ahora se pueden escribir así:

````
```{r}
#| echo = FALSE, fig.width = 10,
#| fig.cap = "This is a long caption."

plot(cars)
```
````

---
background-image: url(imagenes/ss_00_new_logo_rmd.png)
background-position: 99% 1%
background-size: 4%

##### (II b) Código R ... pero ... inline

- La mayoría del código suele ir en los chunks, pero a veces necesitamos .yellow-h[inline code]; es decir, codigo R dentro de nuestro texto.

##### Por ejemplo

- Si quiero describir un df puedo hacerlo así: "El data.frame iris  tiene 150 filas y 5 variables"

- Pero es mejor hacerlo con .yellow-h[inline code]. Para ello tienes que poner el código R dentro de estas marcas:  <span style="background-color: #e5e5e5; border-radius: 3px; padding: 4px; font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;"><code>&grave;r &grave;</code></span>

---
background-image: url(imagenes/ss_00_new_logo_rmd.png)
background-position: 99% 1%
background-size: 4%

##### (III) El texto (o narratives)

- Todo lo que no es el yaml o un chunk, es texto. El texto se escribe en [Markdown](https://es.wikipedia.org/wiki/Markdown)

##### ¿qué narices es esto de Markdown?

- **Markdown** es un lenguaje de marcas diseñado para escribir fácilmente para la web y que sea también fácilmente legible.

- Markdown fue creado por Jhon Grueber y [Aaron Swartz](https://es.wikipedia.org/wiki/Aaron_Swartz). Para saber más sobre Aaron Swartz puedes ver [este documental](https://www.youtube.com/watch?v=7jhdj0vKbYo)

-  La ventaja de escribir en Markdown es que es un lenguaje muy fácil de aprender y que como está basado en un formato de texto plano, es y será compatible con la mayoría de plataformas.

- En este otro [tutorial  de Markdown](https://www.markdowntutorial.com/), se puede leer lo siguiente:

> Markdown is a way to write for the web. It’s written in what nerds like to call “plaintext”. Plaintext is just the regular alphabet, with a few familiar symbols. Unlike cumbersome word processing applications, text written in Markdown can be easily shared between computers, mobile phones, and people. It’s quickly becoming the writing standard for academics, scientists, writers, and many more. Websites like GitHub and reddit use Markdown to style their comments.

---
background-image: url(imagenes/1920px-Markdown-mark.svg.png)
background-position: 99% 1%
background-size: 4%

##### Para aprender Rmarkdown podéis usar un [editor on-line de Markdown](https://vuejs.org/v2/examples/) y probar a escribir algo.
 
<img src="data:image/png;base64,#../imagenes/rmarkdown_ejemplos/imagenes/imagen_ejemplo_markdown.PNG" width="58%" style="display: block; margin: auto;" />

---
background-image: url(imagenes/1920px-Markdown-mark.svg.png)
background-position: 99% 1%
background-size: 4%

##### más cosas sobre cómo escribir **texto** en Markdown

- Mardown es un lenguaje **estoico**

- R Markdown sigue la sintáxis de [Pandoc's Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown)

<br>

- Si en una frase/linea de texto hay 2 espacios o más, estos se reducen a un espacio.

- Para que una linea pase a ser de verdad otra linea, hay que dejar 2 o más espacios al final.

- Una (o mas lineas) en blanco generan un nuevo párrafo.

<br>

- Para crear más espacio entre párrafos (una linea en blanco extra): `<br>`

- Si queremos dejar extra espacio entre 2 palabras: `&nbsp;` `&ensp;` o `&nbsp;`

<br>

- Los espacios de lineas que empiezan con `|` se mantienen (🤓)

---
background-image: url(imagenes/1920px-Markdown-mark.svg.png)
background-position: 99% 1%
background-size: 4%

##### más cosas sobre Rmarkdown

<br>

- **Ecuaciones**: admite ecuaciones en Latex si van entre **$** para ecuaciones inline y **$$** para ecuaciones independientes. [Aquí](http://www.sciweavers.org/free-online-latex-equation-editor) tienes un editor de ecuaciones en latex online, y [aquí](https://dereksonderegger.github.io/570L/16-rmarkdown-tricks.html) algunos ejemplos de ecuaciones escritas en Latex.

<br>

- **Hyperlinks**: Si escribes **`<https://www.rstudio.com/>`** o **`[Web de RStdudio](https://www.rstudio.com/)`**, cuando los procese `knitr`, se convertirán en hyperlinks.

<br>

- **Notas al pie**: si quieres poner una nota al pie aquí`^[el texto que quieres en la nota al pie]`

<br>

- **Tablas**: por ejemplo `knitr::kable(df)`, o `gt::gt(df)`, o `DT::datatable(df)` y más. Si te interesa el tema de las tablas puedes visitar [esto](https://perezp44.github.io/intro-ds-21-22-web/tutoriales/tt_08_tablas-Rmarkdown.html) o [esto](https://rfortherestofus.com/2019/11/how-to-make-beautiful-tables-in-r/)

---
background-image: url(imagenes/1920px-Markdown-mark.svg.png)
background-position: 99% 1%
background-size: 4%

##### tuneando tu informe .html

- Puedes cambiar algunos aspectos de tu documento html. Puedes verlo [aquí](https://bookdown.org/yihui/rmarkdown/html-document.html#appearance-and-style.)

- Con CSS se puede personalizar completamente el aspecto de los documentos html que se generan con Rmarkdown. Aunque no sepas CSS tienes una gran variedad de formatos predefinidos. Puedes ver un listado [aquí](https://www.datadreaming.org/post/r-markdown-theme-gallery/),  [aquí](https://github.com/gadenbuie/cleanrmd)o [aquí](https://github.com/juba/rmdformats).

- El paquete [bslib](https://rstudio.github.io/bslib/) facilita el tuneado de los html. Puede ver el listado de themes   `bslib::bootswatch_themes()`.

- El paquete [thematic](https://rstudio.github.io/thematic/) puede hacer que los gráficos reflejen el theme de RStudio que estas usando: sólo hay que hacer `thematic_on()`

---

##### Imágenes

.pull-left[
Se pueden insertar así: `![](ruta a-la-imagen-chula)`,

![](data:image/png;base64,#https://upload.wikimedia.org/wikipedia/commons/thumb/5/51/A_la_pla%C3%A7a%21_Guanyem_Barcelona_%2817927128471%29.jpg/300px-A_la_pla%C3%A7a%21_Guanyem_Barcelona_%2817927128471%29.jpg)
]

.pull-right[
... aunque yo prefiero hacerlo así:

````
```{r,  echo = FALSE, eval = TRUE, fig.asp = 4/2, out.width = "69%", fig.align = "center"}
knitr::include_graphics(here::here("imagenes", "mola-mazo.jpg")
```    
````

]

##### Videos

````
```{r, echo = FALSE, eval = TRUE}
library("vembedr")
embed_url("https://www.youtube.com/watch?v=ACv9zaBa1A4")
```
````

---
 
##### 2+2 supervideos de NV

.pull-left[

<div class="vembedr">
<div>
<iframe src="https://www.youtube.com/embed/ZkECLuuRwTg" width="533" height="300" frameborder="0" allowfullscreen="" data-external="1"></iframe>
</div>
</div>
]

.pull-right[

<div class="vembedr" align="center">
<div>
<iframe src="https://www.youtube.com/embed/NOPBudtl9z4" width="533" height="300" frameborder="0" allowfullscreen="" data-external="1"></iframe>
</div>
</div>
]

---

#### Referencias

- **R Markdown: The Definitive Guide (Xie et al., 2019)**: <https://bookdown.org/yihui/rmarkdown/>

- **Rmarkdown Cookbook (Xie et al., 2021)**: <https://bookdown.org/yihui/rmarkdown-cookbook/>

- **RMD for scientists (Tierney 2020)**: <https://rmd4sci.njtierney.com/>

<br>

- Tutoriales de RStudio: <https://rmarkdown.rstudio.com/articles.html>

- Vídeos de RStudio: <https://rmarkdown.rstudio.com/lesson-1.html>

<br>

- Rmarkdown cheat sheet: <https://raw.githubusercontent.com/rstudio/cheatsheets/master/rmarkdown-2.0.pdf>

- Rmarkdown Reference: <https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf>

- Página web de `knitr`: <https://yihui.org/knitr/options/>