07_rmarkdown.qmd

---
title: '7 - Rmarkdown'
author: "Luz Frias"
execute:
  message: false
  warning: false
output:
  html_document:
    highlight: null
---

## ¿Qué vamos a hacer?

Hasta ahora hemos visto diferentes herramientas para crear visualizaciones sobre datos. En este capítulo, veremos cómo diseñar informes completos.

Los informes tienen varios elementos: títulos, párrafos, listas, gráficos, ... Y estos se pueden generar estática o dinámicamente. Además, los informes pueden estar en diferentes formatos: word, PDF, HTML, ... Todo esto se puede generar y automatizar gracias a _R Markdown_, que es una extensión de [_markdown_](https://en.wikipedia.org/wiki/Markdown) para R.

Antes de profundizar en su uso, visita la [Galería de R Markdown de RStudio](https://rmarkdown.rstudio.com/gallery.html) y mira los ejemplos de documentos estáticos, interactivos, cuadros de mando, presentaciones de diapositivas y libros. Todos estos ejemplos se han generado con _R Markdown_.

### Recomendaciones

Para seguir correctamente este capítulo, deberás tener instaladas las librerías `rmarkdown` y `tinytex`.

```{r, eval=FALSE}
# Ejecuta las siguiente líneas en el caso de que no las tengas instaladas
install.packages("rmarkdown")
install.packages("tinytex")
```

Además, este capítulo viene acompañado con una serie de ejemplos. Es recomendable que vayas viendo su código fuente y resultado mientras sigues cada uno de los apartados.

También deberás crear tus propios documentos de R Markdown, escribir bloques de texto y código y compilarlos. Compilar significa generar el documento resultante en el formato requerido: HTML, PDF, ...

Para crear un nuevo documento, haz click en RStudio en File / New File / R Markdown. Te dará a elegir título y formato, aunque luego podrás cambiarlo en el propio fichero.

![](resources/07_rmarkdown/new_rmarkdown.png)

Para compilar un documento, haz click en el botón de _Knit_ que sale en la parte superior del editor de código.

![](resources/07_rmarkdown/knit.png)

## Elementos principales

Un documento de _R Markdown_ se compone principalmente de texto formateado y bloques de código.

### Markdown

_Markdown_ es un lenguaje muy popular para generar texto formateado con una sintaxis simple. Además de para _R Markdown_, se utiliza en portales como [GitHub](http://github.com/) para publicar _issues_ o _pull requests_, [StackOverflow](https://stackoverflow.com/) para preguntar o responder y en la gran mayoría de las herramientas de generación de documentación.

Los títulos y cabeceras se ponen de la siguiente forma:

```
# Título nivel 1

## Título nivel 2

### Título nivel 3

y así sucesivamente...

###### Título nivel 6

```

Para poner diferentes párrafos, debes separarlos por una o más líneas en blanco.

```
Estoy escribiendo un párrafo.

Este es otro diferente.
```

Para incluir un salto de línea pero seguir dentro de un mismo párrafo, deja al menos 2 espacios y luego, un salto de línea.

```
Ahora todo en el mismo párrafo.  
Pero con un salto de línea.
```

Para añadir texto en negrita:

```
Esto es **muy importante**.
```

Y para hacerlo en cursiva:

```
Voy a hacer un análisis exploratorio sobre este *dataset*.
```

Si quieres combinar ambas, negrita y cursiva:

```
Mi ***negrita y cursiva***, todo junto.
```

Para incluir citas:

```
> Those hours of practice, and failure, are a necessary part of the learning process. Gina Sipley.
```

Las citas también pueden incluir varios párrafos: para hacerlo, hay que dejar una línea con `>` en blanco:

```
> Any fool can write code that a computer can understand. Good programmers write code that humans can understand.
>
> *Martin Fowler*
```

Las listas pueden ser numeradas o no. En el primer caso, anotamos el comienzo de cada elemento con su número, pudiendo indentar (con cuatro espacios o una tabulación) para hacer subniveles:

```
1. Introducción
2. Compilación
3. Elementos
    1. Markdown
    2. Bloques de código
4. Formatos
```

En el caso de no numeradas, podemos hacerlo con `*`, `-` o `+` delante de los elementos. También podemos utilizar la indentación para anidar niveles:

```
* Introducción
* Compilación
* Elementos
    * Markdown
    * Bloques de código
* Formatos
```

Podemos crear hipervínculos de la siguiente forma:

```
Utilizamos [GitHub](https://github.com/) para publicar código libre.
```

Y para insertar imágenes:

```
![Texto alternativo de la imagen](/ruta/hasta/mi/imagen.png)
```

Para formatear correctamente el código:

    ```
    library(ggplot2)
    library(palmerpenguins)
    
    ggplot(penguins, aes(x = flipper_length_mm, y = body_mass_g)) + 
      geom_point()
    ```

También podemos poner sub-índices y super-índices, con:

```
Be H~2~O my friend.

^40^K es un isótopo radioactivo del potasio.
```

> Consulta el ejemplo `01_basico.Rmd` con el código fuente y `01_basico.html` con el documento generado.

### Código

Además de código formateado con _markdown_, podemos insertar código en línea o en bloques que generen texto, tablas o gráficas.

Para insertar código _inline_:

````markdown
2 más 5 es `r '\x60r 2 + 5\x60'`.
````

Y para hacerlo en bloques:

````markdown
`r ''````{r}
x <- 2
y <- 5

x + y
```
````

> La diferencia entre el código en bloque tal y como lo hacemos aquí, frente al código formateado en markdown que veíamos en el apartado anterior, es que en este caso, se evalúa el código y, en el anterior, solo se muestra formateado.

Los bloques de código mostrarán en el documento el resultado de ejecutar la última línea. En el caso anterior, es un número, pero podemos hacerlo también con tablas y gráficas.

Para formatear correctamente una tabla en un documento, lo más fácil es utilizar `knitr::kable()`, que es compatible con documentos HTML, PDF y word.

````markdown
`r ''````{r}
library(palmerpenguins)

knitr::kable(head(penguins))
```
````

```{r}
library(palmerpenguins)

knitr::kable(head(penguins))
```

Y para incluir gráficas en nuestro documento, solo tenemos que incluir un bloque de código que acabe generando una gráfica.

````markdown
`r ''````{r}
library(ggplot2)

ggplot(penguins, aes(x = flipper_length_mm, y = body_mass_g)) + 
  geom_point()
```
````

```{r}
library(ggplot2)

ggplot(penguins, aes(x = flipper_length_mm, y = body_mass_g)) + 
  geom_point()
```

Los bloques de código se pueden personalizar con diferentes opciones. Las más habituales son:

* `eval`: con valores `TRUE` o `FALSE`. Determina si evaluar o no el código.

* `echo`: con valores `TRUE` o `FALSE`. Para mostrar o no el código en el documento resultante.

* `warning`, `message`, y `error`: con valores `TRUE` o `FALSE`. Para mostrar o no en la salida los errores, advertencias o mensajes del código evaluado.

Puedes consultar la lista completa de opciones [aquí](https://bookdown.org/yihui/rmarkdown/r-code.html).

Por ejemplo, para no mostrar el warning de las filas que tienen valores NA al generar el gráfico anterior, haríamos:

````markdown
`r ''````{r, warning = FALSE}
library(ggplot2)

ggplot(penguins, aes(x = flipper_length_mm, y = body_mass_g)) + 
  geom_point()
```
````

Si, en general, todos los bloques de código tienen las mismas opciones, es habitual ponerlas en un bloque con el nombre `setup` que las fija comunes. De esta forma, no hay que repetirlo en cada bloque nuevo.

````markdown
`r ''````{r, setup}
knitr::opts_chunk$set(message = FALSE, warning = FALSE, echo = FALSE)
```
````

> Consulta el ejemplo `02_codigo.Rmd` con el código fuente y `02_codigo.html` con el documento generado.

## Formatos

`R Markdown` permite generar documentos en formatos diversos. Aunque al crear un informe con RStudio nos permite elegirlo, también lo podemos cambiar en la cabecera, en el parámetro `output`.

Algunos de estos formatos tienen ciertas particularidades, que exploraremos en esta sección.

### HTML

Para exportar a HTML, el valor de output será `html_document`. Por ejemplo:

```
---
title: "Mi informe"
author: "Grace Hopper"
output: html_document
---
```

Es útil añadir una tabla de contenidos que contenga vínculos a cada una de las secciones. Para hacerlo, añadiremos dentro de las opciones de `html_document` la opción `toc` (_table of contents_). También es personalizable el nivel hasta el cual cubrir con la tabla de contenidos con `toc_depth`, o ponerlo flotante a la izquierda con `toc_float`. Incluso, dentro de este último, podemos controlar el comportamiento del scroll al hacer click en el índice con `smooth_scroll` o como se colapsan / expanden las sub-secciones con `collapsed`.

```
---
title: "2 - HTML"
author: "Luz Frias"
output:
  html_document:
    toc: true
    toc_float:
      collapsed: false
      smooth_scroll: false
---
```

Podemos organizar el contenido utilizando pestañas (en lugar de poner las secciones una debajo de la otra) aplicando la clase `.tabset`. Esto provoca que las sub-secciones se muestren en pestañas diferentes.

```
## Mi análisis exploratorio

### Gráfico 1

Contenido de la primera pestaña.

### Gráfico 2

Contenido de la segunda pestaña.

```

También podemos personalizar el estilo del HTML resultante, con:

* `theme`, que controla el tema de _bootstrap_ (el framework de maquetación que utiliza internamente). Algunos temas válidos son: default, cerulean, journal, flatly, darkly, readable, spacelab, united, cosmo, lumen, paper, sandstone, simplex, y yeti.
* `highlight`, controla el estilo aplicado al código (cómo se muestran las palabras reservadas, los símbolos, etc.). Algunos valores válidos son: default, tango, pygments, kate, monochrome, espresso, zenburn, haddock, breezedark, y textmate. Pasando el valor null se elimina el estilo especial sobre el código.

```
---
title: "Ejemplo"
output:
  html_document:
    highlight: tango
    theme: paper
---
```

Recuerda que una de las principales ventajas de HTML es que permite incluir elementos interactivos. Esto significa que, si necesitamos incluir mapas de `leaflet` o gráficos de `plotly`, el documento generado deberá ser HTML. Estos elementos interactivos no son compatibles con PDF, Word, ni otros formatos estáticos.

Puedes consultar más opciones de personalización de documentos HTML [aquí](https://bookdown.org/yihui/rmarkdown/html-document.html).

### PDF

Al exportar a PDF, tenemos algunas personalizaciones que también estaba disponibles en HTML. Algunas estarán más limitadas, al ser un formato estático.

Por ejemplo, para poner una tabla de contenidos, tenemos disponibles los parámetros `toc` y `toc_float`. Pero no están disponibles aquellos específicos de la interactividad de HTML, como el control del scroll o el colapsar / expandir secciones.

```
---
title: "Un ejemplo en PDF"
output:
  html_document:
    toc: true
    toc_float: true
---
```

De personalización, solo tenemos la capacidad de alterar cómo se resalta el código, con la propiedad `highlight`. Se utiliza igual que como detallábamos con HTML.

```
---
title: "3 - HTML y PDF"
author: "Luz Frias"
output:
  pdf_document:
    toc: true
    highlight: tango
---
```

> Consulta el ejemplo `03_html_pdf.Rmd` con el código fuente y los dos documentos que genera, `03_html_pdf.html` y `03_html_pdf.pdf`.

### Presentaciones

También podemos utilizar `R Markdown` para generar presentaciones de diapositivas.

Tenemos varios motores de diapositivas disponibles: `ioslides`, `Slidy`, `Beamer`, ... Vamos a ver ejemplos del primero, pero todos están bien documentados [aquí](https://bookdown.org/yihui/rmarkdown/presentations.html).

Cada sección que definamos será una diapositiva diferente. Por ejemplo, para crear una presentación con tres diapositivas:

````markdown
`r ''````{r}

## Diapositiva con listado

* Elemento 1
* Elemento 2
* Elemento 3

## Diapositiva con tabla

`r ''````{r}
library(palmerpenguins)
library(ggplot2)

head(penguins)
```

## Diapositiva con gráfico

`r ''````{r}
ggplot(penguins, aes(x = flipper_length_mm, y = body_mass_g)) + 
  geom_point()
```

````

> Tienes este ejemplo en `04_slides.Rmd` y su salida `04_slides.html`.

En el documento resultante, podremos utilizar la funcionalidad de `ioslides`, como avanzar de diapositiva con la tecla espacio o las fechas, o cambiar los modos de presentación con atajos de teclado:

* `f`: pantalla completa
* `w`: cambio a pantalla ancha o estrecha
* `o`: para ver una visión general

Consulta todas las opciones disponibles de `ioslides` [aquí](https://bookdown.org/yihui/rmarkdown/ioslides-presentation.html)

## Uso avanzado

### Parametrización

_R Markdown_ es muy potente para automatizar reportes. Para hacer esto resulta muy útil contar con parámetros, que podrán alterar el resultado de la evaluación de nuestros documentos. De esta forma, podemos reutilizar un mismo informe en escenarios parecidos. Como por ejemplo, extraer informes para rangos de fechas diferentes. Imagina que tienes que presentar un informe de resultados cada mes: puedes reutilizar el mismo documento parametrizando la fecha.

Para declarar los parámetros, utiliza la opción `fields`. Le puedes dar un valor por defecto a cada caso.

```
---
title: Análisis exploratorio de pingüinos
output: html_document
params:
  my_species: Adelie
  my_sex: female
---
```

Estos parámetros están accesibles en los bloques de código del documento a través de la lista de solo lectura `params`. Para consultar los parámetros del ejemplo anterior:

```
params$my_species
params$my_sex
```

Un ejemplo de documento completo, alterado por el uso de estos parámetros:

````markdown
---
title: Análisis exploratorio de pingüinos
output: html_document
params:
  my_species: Adelie
  my_sex: female
---

`r ''````{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE, warning = FALSE, message = FALSE)
```

# Ámbito de análisis

Este documento muestra los pingüinos con estas características:

* Especie: `r '\x60r params$my_species\x60'`
* Sexo: `r '\x60r params$my_sex\x60'`

`r ''````{r}
library(palmerpenguins)
library(dplyr)

mis_pinguinos <- penguins %>%
  filter(species == params$my_species, sex == params$my_sex)
```

Contamos con `r '\x60r nrow(mis_pinguinos)\x60'` observaciones con estas características. Una muestra:

`r ''````{r}
knitr::kable(head(mis_pinguinos))
```

````

Y para generar el documento con los parámetros requeridos, tenemos dos opciones: hacerlo interactivamente desde RStudio con `Knit with parameters` o automático en código con la función `rmarkdown::render(params = ...)`.

En el primer caso, tenemos la opción encima del editor:

![](resources/07_rmarkdown/knit_params.png)

En el segundo caso, utilizamos el argumento `params`:

```
rmarkdown::render("05_params.Rmd", params = list(
  my_species = "Gentoo",
  my_sex = "female"
))
```

> Tienes este ejemplo en `05_params.Rmd` y su salida `05_params.html`. Prueba a ejecutar el código anterior con diferentes valores en sus parámetros y observa el resultado. Recuerda que debes establecer tu _working directory_ en la misma carpeta donde se encuentre el informe.

## Profundiza

Para saber más sobre los conceptos que hemos visto, puedes consultar alguna de estas referencias:

* [Galería de ejemplos de R Markdown de RStudio](https://rmarkdown.rstudio.com/gallery.html): con código y resultado de varios ejemplos de uso de R Markdown, en diferentes formatos.
* [Chuleta de R Markdown](https://github.com/rstudio/cheatsheets/raw/master/rmarkdown-2.0.pdf): muy útil para tener a mano con las funcionalidades más habituales de R Markdown.
* [Guía completa de uso de R Markdown](https://bookdown.org/yihui/rmarkdown/): documentación completa de uso, útil para consultar todas las posibles opciones en cada formato.

## Conclusiones

Nos podemos quedar con las siguientes ideas como resumen de este tema:

* `R Markdown` es una herramienta potente de automatización de informes.
* Combina texto formateado y bloques de código.
* El texto formateado se escribe utilizando _markdown_.
* El código se escribe con _R_.
* Permite diferentes formatos de salida: HTML, PDF, Word, presentaciones de diapositivas, ...
* Podemos parametrizar los informes para reutilizar el mismo documento en situaciones similares.

## Actividades

### Actividad 1

Realiza un pequeño análisis exploratorio sobre el _dataset_ de pingüinos, combinando texto formateado, tablas y gráficas, en un documento en _R Markdown_.

Intenta utilizar la mayor parte de los elementos que hemos visto:

* Títulos de diferentes niveles.
* Partes del texto resaltada en negrita o cursiva.
* Listas.
* Código _inline_.
* Bloques de código.
* Tablas.
* Gráficas.
* Etcétera.

### Actividad 2

Sobre el informe que acabas de diseñar, personaliza su apariencia al exportarlo a HTML:

1. Explora varias opciones de `theme` y `highlight`.
2. Experimenta con las diferentes personalizaciones de la tabla de contenidos.

Quédate con la que más te guste. Podrás reutilizar esta combinación en los documentos próximos que elabores.