Rmarkdown (primeras ideas)

background-image: url(data:image/png;base64,#imagenes/ss_00_new_logo_rmd.png)
background-position: 0% 70%
background-size: 39%

class: inverse, center, middle

<br>

###### Curso de introducción a R (SFPIE)

### Rmarkdown (primeras ideas)

<br>

### Pedro J. Pérez

#### 2021, junio

###### (actualizadas el 08-06-2021)

<br><br><br>
###### e-mail: [<i class="fas  fa-envelope "></i>](mailto:pedro.j.perez@uv.es) [pedro.j.perez@uv.es](mailto:pedro.j.perez@uv.es)

###### Web del curso: [<i class="fas  fa-link "></i>](https://perezp44.github.io/curso_R_SFPIE_2021/) https://perezp44.github.io/curso_R_SFPIE_2021/

---
class: inverse, center, middle
background-image: url(data:image/png;base64,#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(data:image/png;base64,#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(data:image/png;base64,#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(data:image/png;base64,#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(data:image/png;base64,#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(data:image/png;base64,#imagenes/ss_00_new_logo_rmd.png)
background-position: 99% 1%
background-size: 4%

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

- Para que `knitr` sepa que 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(data:image/png;base64,#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 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(data:image/png;base64,#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.

<br>

- 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(data:image/png;base64,#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(data:image/png;base64,#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=vXr-2hwTk58)

-  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(data:image/png;base64,#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,#/home/pjpv/Escritorio/slides_curso-R_2021_ok/imagenes/rmarkdown_ejemplos/imagenes/imagen_ejemplo_markdown.PNG" width="58%" style="display: block; margin: auto;" />

---
background-image: url(data:image/png;base64,#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(data:image/png;base64,#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

<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-20-21-web/tutoriales/tt_08_tablas-Rmarkdown.html) o [esto](https://rfortherestofus.com/2019/11/how-to-make-beautiful-tables-in-r/)

---

##### 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=""></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=""></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>

- Videos 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/>