Capítulo 7 RMarkdown
7.1 Introducción
El proceso habitual para hacer un informe (o unas transparencias) en el que aparezcan gráficos o tablas resumen de algún análisis estadístico consiste en :
- Escribir el texto en un programa (Word, Powerpoint, Prezi, etc.)
- Realizar los cálculos estadísticos y gráficos en otro programa (R, Stata, Eviews, etc.)
- Pegar los gráficos y tablas en el documento de texto.
Este proceso tiene ciertas desventajas: dificulta la investigación reproducible, puede ser tedioso de rehacer si por ejemplo cambian ligeramente los datos, etc.
En R es posible realizar todo el informe, tanto la escritura del texto como la realización de los cálculos y gráficos, en un único documento. Hay varias formas de hacerlo, pero nos centraremos en los documentos RMarkdown (.Rmd).
Los documentos RMarkdown (.Rmd) facilitan mucho la realización de informes y transparencias ya que permiten combinar texto, código y resultados de la evaluación del código en un único documento. Si por ejemplo cambian los datos sólo habría que cambiar la ruta a los nuevos datos y el informe (gráficos, tablas etc…) se volvería a generar automáticamente con los nuevos datos.
Ya hemos trabajado con algunos documentos Rmarkdown (.Rmd); de hecho, todos los tutoriales del curso (incluido éste que estás viendo) se han elaborado usando ficheros .Rmd. Los tutoriales se escriben en ficheros RMarkdown, pero estos ficheros .Rmd se convierten a html, que suele ser el formato final en el que se muestran los tutoriales. En RStudio el proceso de conversión de .Rmd a .html consiste simplemente en pinchar un botón; además, simplemente cambiando una linea podemos convertir los documentos .Rmd a una gran variedad de formatos: html, pdf, word, iosslides, beamer, etc…
Si quieres ver algunos ejemplos de la gran variedad de formatos a los que puedes transformar un documento Rmd ve a la siguiente galería
7.1.1 Proceso para convertir los .Rmd a otro(s) formatos [OPCIONAL]
Como trabajamos con RStudio, en la práctica, procesar los ficheros .Rmd consistirá solamente en pinchar en el icono Knit. Muy fácil!!
No es necesario, pero quizá os interese saber cómo se procesan realmente los ficheros .Rmd para acabar convirtiéndose en html, pdf, etc.
La respuesta es que se ocupan de ello un paquete de R, knitr, y un programa llamado pandoc.
En palabras: knitr se ocupa de ejecutar todos los trozos con código R que haya en el fichero .Rmd, después de ejecutar el código, pegará los resultados de la evaluación del código (gráficos, tablas etc…) junto con el texto en un documento intermedio (con extensión .md), para después transferir este documento .md a pandoc que se encarga de traducirlo al formato elegido (html, pdf, …). Knitr sabe diferenciar el texto del código R porque éste se señaliza con unas marcas.
Visualmente:
7.2 Creando .Rmd’s en RStudio
En la práctica, RStudio facilita mucho la creación de documentos Rmarkdown. Para generar un documento .Rmd basta con seguir la siguiente ruta de menús: File > New File > R Markdown ...
Se abrirá una ventana que nos solicitará un título y un autor para nuestro .Rmd, así como el formato de salida.
Cuando aceptemos nos generará un documento/plantilla para nuestro .Rmd. Si queremos procesarlo o “knitearlo” tendremos que hacer click en el icono Knit
7.3 ¿Qué son los documentos .Rmd?
Son simplemente ficheros de texto (se pueden escribir en cualquier editor de texto, por ejemplo Notepad); PERO facilitan mucho la tarea de generar informes o transparencias con contenido estadístico, ya que permiten mezclar en un mismo documento texto y código R.
El código R (así como los resultados de la evaluación del código) se mostrarán automáticamente (gracias a knitr) en el documento final; de esta forma, se facilita mucho la realización de informes y transparencias ya que evita el tener que ir copiando los resultados (tablas, gráficos etc…) en el informe.
Veamos un ejemplo con un documento Rmarkdown muy sencillo:
---
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.Como veis, los documentos Rmarkdown tienen 3 partes o elementos:
- encabezamiento
- trozos de código R
- texto
Luego hablaremos de ellas. Antes veamos como quedaría el documento .Rmd tras ser procesado por knitr (“kniteado”). Tras pasar por knitr y pandoc se generará un documento .html que se verá así:
Como veis, el chunk con código R summary(iris) se ha ejecutado y se ha mostrado tanto el código como el resultado de su evaluación en unas cajas de texto.
7.4 Partes de los ficheros .Rmd
Los documentos Rmarkdown tienen 3 partes o elementos:
- Encabezamiento o yaml header
- Trozos de código R(chunks)
- Texto (escrito en markdown)
Veámoslas una a una.
7.4.1 Encabezamiento (yaml header)
Abajo tenéis un ejemplo sencillo de un yaml header:
---
title: "El título de mi informe"
author: "Yo mismo"
date: "Marzo de 2017"
output: html_document
---Como podéis imaginar, el encabezamiento se coloca al principio del documento y comienza y acaba con una marca de 3 guiones: ---
En el encabezamiento se introducen elementos básicos del documento como el título, el autor, fecha, y el formato de salida del documento. En el ejemplo hemos elegido como formato de salida html; si preferimos pdf, habría que sustituir output: html_document por output: pdf_document
El yaml header puede incluir otros elementos para personalizar un poco más el documento final o output. Abajo tenéis un ejemplo más complejo de un yaml header. Es el que utilizamos para hacer los tutoriales del curso de introducción a R.
---
title: "Documentos Rmarkdown (.Rmd)"
author: "Vicente Coll & Pedro J. Pérez"
date: "`r Sys.Date()`"
output:
html_document:
code_folding: show
theme: journal
toc: yes
toc_float: yes
---En la práctica, RStudio se ocupará por nosotros de escribir el encabezamiento de los documentos Rmarkdown.
7.4.2 Chunks (o código R)
Los trozos de código R o chunks permiten hacer análisis estadísticos y mostrar los resultados en el documento final.
Para que knitr distinga las instrucciones de R del texto normal tenemos que poner las instrucciones de R dentro de unas marcas o identificadores: ```{r} al principio y ``` al final.
Por ejemplo:
```{r}
summary(iris)
```Knitr interpreta ese trozo de texto como instrucciones de R porque van dentro de las marcas, y hará que R las ejecute y muestre los resultados en el documento final.
Los chunks pueden tienen diversas opciones que permiten una mayor flexibilidad en como se muestra el código y los resultados en el documento final. Las opciones más usadas son:
- echo
- eval
Por ejemplo, si introducimos este texto en nuestro fichero .Rmd:
```{r, echo = TRUE, eval = TRUE}
summary(iris)
```En este caso, se mostrará el chunk(echo = TRUE) y también se evaluará (eval = TRUE) y, por tanto, se mostrarán los resultados en el documento final. Se verá algo como:
summary(iris)## Sepal.Length Sepal.Width Petal.Length Petal.Width
## Min. :4.300 Min. :2.000 Min. :1.000 Min. :0.100
## 1st Qu.:5.100 1st Qu.:2.800 1st Qu.:1.600 1st Qu.:0.300
## Median :5.800 Median :3.000 Median :4.350 Median :1.300
## Mean :5.843 Mean :3.057 Mean :3.758 Mean :1.199
## 3rd Qu.:6.400 3rd Qu.:3.300 3rd Qu.:5.100 3rd Qu.:1.800
## Max. :7.900 Max. :4.400 Max. :6.900 Max. :2.500
## Species
## setosa :50
## versicolor:50
## virginica :50
##
##
## Mientras que si en el .Rmd escribimos lo siguiente:
```{r, echo = TRUE, eval = FALSE}
summary(iris)
```Se mostrará el código (echo = TRUE), pero no se evaluará (eval = FALSE) y ,por lo tanto, no se mostrarán los resultados en el documento final.
Si en el .Rmd escribimos lo siguiente:
```{r, echo = FALSE, eval = TRUE}
summary(iris)
```NO se mostrará el código (echo = FALSE), pero SI se evaluará (eval = FALSE) y ,por lo tanto, SI se mostrarán los resultados en el documento final.
Si en el .Rmd escribimos lo siguiente:
```{r, echo = FALSE, eval = TRUE, results = "hide"}
summary(iris)
```NO se mostrará el código (echo = FALSE), SI se evaluará (eval = FALSE), PERO como results = "hide" NO se mostrarán los resultados en documento final.
Hay más opciones sobre los chunks que nos permiten una mayor flexibilidad sobre como mostrar los resultados y el código; pero si quieres ver todas las opciones tendrás que ir a la página web de knitr o al cheat sheet sobre Rmarkdown
7.4.3 El texto (en Rmarkdown)
La parte principal de un informe suele ser texto (narratives). En un fichero .Rmd, todo lo que no sea encabezamiento o chunks será interpretado por knit como texto y lo mostrará tal cual; es decir, como texto.
Aquí podríamos acabar nuestro tutorial sobre como escribir texto en un fichero .Rmd; pero generalmente en un texto queremos resaltar ciertas palabras con negrita, o ponerlas en cursiva, o poner un titulo de sección y de sub-secciones. Todo esto lo tendremos que hacer utilizando Markdown. Markdown es un lenguaje de marcas ligero y muy sencillo de aprender (lo básico se aprende en unos 10 minutos) pero muy utilizado. Es posible que alguno de vosotros haya utilizado una variante de Markdown al escribir en negrita en Whatsapp.
El texto de un documento .Rmd es “simplemente” texto PERO está escrito en Markdown. Ahora lo veremos, pero antes vamos a ver un poco más sobre qué es Markdown.
7.4.3.1 ¿Qué es Markdown? [OPCIONAL]
Mardown es un lenguaje de marcado ligero ideado en 2004 por Jhon Grueber y Aaron Swartz. Podemos pensar que es un método de escritura: evidentemente sirve para escribir. 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.
La mayoría de vosotros escribís en Word. Es muy fácil escribir en Word pero un archivo word solo es posible leerlo en el programa WORD de Microsoft. Si intentas abrir un documento .doc en Notepad, éste será completamente ilegible; sin embargo, la mayoría de plataformas y servicios web saben interpretar y mostrar correctamente un documento escrito en Markdown.
Lo que escribas en Rmarkdown se mostrará tal cual en el documento final, pero lo más habitual es que quieras dar un poco de formato el texto: negritas, cursivas, listas, enlaces de internet, etc…
Todos estos formatos (negrita, …) se introducen en rmarkdown con marcas; por ejemplo si quieres que una palabra se resalte en negritas tienes que escribirla enmarcada en **: **esto se mostraría en negrita**
Para aprender las principales reglas de Rmarkdown podéis usar un editor on-line de Markdown y probar a escribir algo.
7.4.3.2 Aquí tienes algunas reglas de Markdown
Si abres el fichero el fichero: ./rmarkdown_ejemplos/ejemplo_Rmd_completo.Rmd, podrás ver un documento Rmd con algún ejemplo más: míralos y luego knitea el documento.
7.5 Más cosas de RMarkdown
En Rmarkdown se pueden introducir también:
7.5.1 Ecuaciones
Se pueden introducir formulas matemáticas escritas en Látex. Para formulas en linea se usa la marca $ y para formulas independientes se usa $$.
Para fórmulas en linea (o dentro del texto) se utiliza la marca
$al principio y final de la formula. Por ejemplo$\sum_{i=1}^n X_i$se mistaría así: \(\sum_{i=1}^n X_i\). Ves, la formula está dentro del texto, en una linea del texto.Para presentar una ecuación independiente (en una linea independiente), se usa la marca
$$al principio y final de la formula. Si escribes$$E = mc^{2}$$, se mostrará en una linea independiente tal que así:
\[E = mc^{2}\]
7.5.2 Imágenes
Para mostrar una imagen basta con poner:
Aunque yo prefiero hacerlo así:
```{r eval = TRUE, echo = TRUE}
knitr::include_graphics("./rmarkdown_ejemplos/imagenes/fucking_ages_image.jpeg")
```
Figure 7.1: Una imagén chula
7.5.3 Hyperlinks
Para poner hyperlinks se puede escribir lo siguiente: <http://www.wikipedia.es> y se mostrará así: http://www.wikipedia.es
Pero es mejor ponerlo así: [enlace a la Wikipedia](http://www.wikipedia.es) y se mostrará así: enlace a la Wikipedia
7.5.4 Notas al pie de página
Para poner notas al pie has de poner [^1] y luego al final del documento poner [^1]: esto es una nota al pie., y se verá esto: 1
7.5.5 Tablas
Habrá un tutorial especifico para tablas, pero lo más básico y sencillo es con la función kable():
``{r}
knitr::kable(summary(iris))
`` | Sepal.Length | Sepal.Width | Petal.Length | Petal.Width | Species | |
|---|---|---|---|---|---|
| Min. :4.300 | Min. :2.000 | Min. :1.000 | Min. :0.100 | setosa :50 | |
| 1st Qu.:5.100 | 1st Qu.:2.800 | 1st Qu.:1.600 | 1st Qu.:0.300 | versicolor:50 | |
| Median :5.800 | Median :3.000 | Median :4.350 | Median :1.300 | virginica :50 | |
| Mean :5.843 | Mean :3.057 | Mean :3.758 | Mean :1.199 | NA | |
| 3rd Qu.:6.400 | 3rd Qu.:3.300 | 3rd Qu.:5.100 | 3rd Qu.:1.800 | NA | |
| Max. :7.900 | Max. :4.400 | Max. :6.900 | Max. :2.500 | NA |
7.5.6 Aún más cosas
Hay más cosas, como referencias bibliográficas, pero ya será para el segundo curso de R.
A pesar de que Markdown permite formatear el texto, en ciertos sentidos es limitado; pero si quieres aún más flexibilidad en el output, tendrás que aprender html y mejor html+CSS.
Algunos ejemplos:
Si quieres introducir un párrafo en otro color tendrás que hacerlo en html, tendrás que escribir:
<FONT COLOR="Red">Esto se mostrará en ROJO!!</FONT>Esto se mostrará en ROJO!!
- si quieres centrar un párrafo, tendrás que escribir:
<CENTER>Este párrafo irá centrado</CENTER>
- Puedes insertar en tu documento (sólo si el output es html) una página web completa, para ello has de escribir:
<iframe src="http://www.eldiario.es/" height="400" width="800"></iframe>
- Un vídeo. Has de escribir:
<iframe width="560" height="315" src="https://www.youtube.com/embed/ACv9zaBa1A4" frameborder="0" allowfullscreen></iframe>
7.6 Investigación reproducible
Hemos hablado muy poco de investigación reproducible pero, es evidente que usar documentos .Rmd y trabajar con Rprojects facilita la investigación reproducible. No la garantiza del todo, para ello habría que ver/usar más herramientas (docker, packrat, github, …). No lo vamos a hacer, pero al menos señalar dos prácticas que facilitan que tus análisis se acerquen a ser reproducibles:
Cuando estás haciendo un análisis y quieres compartirlo hay que estar seguro de los packages que se necesitan cargar para replicarlo, por eso es bueno hacer el análisis desde una sesión nueva/fresca de R y cargar los paquetes al principio del script. Para ello, puede ser de utilidad saber que paquetes tienes cargados en un momento dado, y puedes saberlo con:
(.packages()).A pesar de que nosotros no lo hemos hecho, es recomendable introducir al final de los ficheros
.Rmdla siguiente instrucción:sessionInfo(). De esta forma, proporcionarás información sobre que ordenador, sistema operativo y versión de R utilizaste en tu análisis, así como de las opciones locales de tu sistema (idioma, etc …) y de los paquetes que tienes cargados en memoria. Por ejemplo, ahora mismo mi sessionInfo es:
## R version 3.5.1 (2018-07-02)
## Platform: x86_64-w64-mingw32/x64 (64-bit)
## Running under: Windows 10 x64 (build 17134)
##
## Matrix products: default
##
## locale:
## [1] LC_COLLATE=Spanish_Spain.1252 LC_CTYPE=Spanish_Spain.1252
## [3] LC_MONETARY=Spanish_Spain.1252 LC_NUMERIC=C
## [5] LC_TIME=Spanish_Spain.1252
##
## attached base packages:
## [1] grid stats graphics grDevices utils datasets methods
## [8] base
##
## other attached packages:
## [1] tmap_2.1-1 sf_0.7-1 ggThemeAssist_0.1.5
## [4] lubridate_1.7.4 hexbin_1.27.2 vcd_1.4-4
## [7] AER_1.2-5 survival_2.42-3 sandwich_2.5-0
## [10] lmtest_0.9-36 zoo_1.8-4 car_3.0-2
## [13] carData_3.0-2 bindrcpp_0.2.2 eurostat_3.3.1
## [16] emo_0.0.0.9000 gapminder_0.3.0 readxl_1.1.0
## [19] foreign_0.8-71 haven_2.0.0 forcats_0.3.0
## [22] stringr_1.3.1 dplyr_0.7.8 purrr_0.2.5
## [25] readr_1.2.1 tidyr_0.8.2 tibble_1.4.2
## [28] ggplot2_3.1.0 tidyverse_1.2.1 personal.pjp_0.1.0
## [31] usethis_1.4.0 devtools_2.0.1
##
## loaded via a namespace (and not attached):
## [1] backports_1.1.2 lwgeom_0.1-4
## [3] plyr_1.8.4 lazyeval_0.2.1
## [5] sp_1.3-1 splines_3.5.1
## [7] crosstalk_1.0.0 leaflet_2.0.2
## [9] digest_0.6.18 htmltools_0.3.6
## [11] qpcR_1.4-1 fansi_0.4.0
## [13] magrittr_1.5 memoise_1.1.0
## [15] openxlsx_4.1.0 remotes_2.0.2
## [17] modelr_0.1.2 prettyunits_1.0.2
## [19] colorspace_1.3-2 rvest_0.3.2
## [21] rgdal_1.3-6 xfun_0.4
## [23] callr_3.0.0 crayon_1.3.4
## [25] jsonlite_1.5 bindr_0.1.1
## [27] glue_1.3.0 gtable_0.2.0
## [29] webshot_0.5.1 pkgbuild_1.0.2
## [31] DEoptimR_1.0-8 abind_1.4-5
## [33] scales_1.0.0 DBI_1.0.0
## [35] miniUI_0.1.1.1 Rcpp_1.0.0
## [37] viridisLite_0.3.0 xtable_1.8-3
## [39] spData_0.2.9.4 units_0.6-1
## [41] Formula_1.2-3 stats4_3.5.1
## [43] htmlwidgets_1.3 httr_1.3.1
## [45] RColorBrewer_1.1-2 pkgconfig_2.0.2
## [47] XML_3.98-1.16 utf8_1.1.4
## [49] tidyselect_0.2.5 labeling_0.3
## [51] rlang_0.3.0.1 manipulateWidget_0.10.0
## [53] reshape2_1.4.3 later_0.7.5
## [55] tmaptools_2.0-1 munsell_0.5.0
## [57] cellranger_1.1.0 tools_3.5.1
## [59] cli_1.0.1 broom_0.5.0
## [61] evaluate_0.12 yaml_2.2.0
## [63] processx_3.2.0 knitr_1.20
## [65] fs_1.2.6 zip_1.0.0
## [67] robustbase_0.93-3 rgl_0.99.16
## [69] satellite_1.0.1 nlme_3.1-137
## [71] mime_0.6 formatR_1.5
## [73] xml2_1.2.0 compiler_3.5.1
## [75] rstudioapi_0.8 png_0.1-7
## [77] curl_3.2 e1071_1.7-0
## [79] stringi_1.2.4 highr_0.7
## [81] ps_1.2.1 desc_1.2.0
## [83] rgeos_0.4-2 lattice_0.20-35
## [85] Matrix_1.2-14 classInt_0.2-3
## [87] pillar_1.3.0 data.table_1.11.8
## [89] mapview_2.6.0 raster_2.8-4
## [91] httpuv_1.4.5 R6_2.3.0
## [93] bookdown_0.7 promises_1.0.1
## [95] KernSmooth_2.23-15 rio_0.5.16
## [97] sessioninfo_1.1.1 codetools_0.2-15
## [99] dichromat_2.0-0 MASS_7.3-50
## [101] assertthat_0.2.0 pkgload_1.0.2
## [103] rprojroot_1.3-2 minpack.lm_1.2-1
## [105] withr_2.1.2 hms_0.4.2
## [107] class_7.3-14 rmarkdown_1.10
## [109] shiny_1.2.0 base64enc_0.1-3Si quieres ver todos los paquetes que tienes instalados en tu ordenador, lo puedes hacer así:
pkgs_instalados <- installed.packages(fields = c("Package", "Version")) %>%
as.data.frame()7.7 Bibliografía
Tutorial oficial de Rmarkdown Muy bueno y muy completo. Quizás la primera opción para aprender.
Tutorial completo. Tutorial sencillo pero bastante completo. Bastante didáctico.
Pagina oficial de knitr. Solamente para verla. Usarla sólo cuando ya “pilotes”.
Cheat Sheet de Rmarkdon en castellano. Parece complicado, pero cuando te acostumbras es una fantástica chuleta.
Tutorial de Rmarkdown en español
Tutorial de Markdown en español
Customizing & Extending R Markdown. Tutorial del desarrollador de knitr. Corto pero avanzado.
esto es una nota al pie.↩