R Markdown se puede describir como “un formato eléctronico de documentación que facilita la creación de documentos, presentaciones e informes dinámicos desde R”. R Markdown puede generar documentos con segmentos (“chunks”) de código de R incrustados entre líneas de texto. Cuando se procesa el documento, estos segmentos se evalúan (si el usuario así lo desea) y los resultados se anidan en el documento de acuerdo con ciertas convenciones especificadas.

Ventajas:

  • El código R se puede incrustar en el informe, por lo que no es necesario mantener el informe y el código de R por separado

  • Incluir el código R directamente en un informe proporciona una estructura intuitiva para reproducir los análisis

  • El texto del informe está escrito como texto normal, por lo que no se requieren conocimientos de codificación (i.e. HTML)

  • La salida es un archivo HTML que incluye imágenes, bloques de código de salida R y texto. No se necesitan archivos adicionales, todo está incorporado en el archivo HTML.

  • Los informes son fáciles de compartir por correo o publicarlos en línea

  • Estos informes facilitan la colaboración y mejoran la reproducibilidad (entender los análisis es mucho mas fácil cuando hay texto explicativo, código de R, los resultados del código y los gráficos en un mismo archivo)

  • Se actualiza fácilmente tanto para incluir nuevos análisis como para integrar nuevos datos

 

Crear documentos R Markdown

Usaremos Rstudio para crear documentos R Markdown. Empiece por seleccionar “R Markdown …” en el menú desplegable que aparece cuando crea un nuevo archivo:

 

Nota: es posible que se le solicite aquí que instale varios paquetes necesarios para que R Markdown funcione.

 

Aparecerá una ventana que le pedirá un titulo y autor para el nuevo documento (esto no es tan relevante en este punto y puedo ser modificado fácilmente luego), así como el formato. Seleccione ‘HTML’ ya que nos interesa convertirlo a un formato de visualización universal. Puede cambiar sus preferencias de salida de ‘HTML’ a ‘PDF’ o ‘Word’ en cualquier momento:

 

Esto lo llevará a su primer archivo ‘.Rmd’ (o R Markdown). El nuevo archivo ya viene con una plantilla con instrucciones básicas:

 


Ejercicio 1

Cree un nuevo archivo R Markdown, escriba algunas líneas de texto y haga clic en “Knit” para ver cómo se verá su reporte.


 

Syntaxis Markdown

Markdown (y por extensión Rmarkdown) tiene sus propias reglas sintácticas. Sin embargo, este lenguaje es relativamente simple y fácil de dominar:

Código:

Resultado:

Crear encabezados de varios tamaños:

Header 1

Header 2

Header 3

Código:

Resultado:

Hacer texto en negrita, itálico, tachado, o superíndice

Código:

Resultado:

Añadir una imagen:

Código:

Resultado:

Crear un enlace a figshare


Ejercicio 2


2.1 Cree unos encabezados y sub-encabezados en su documento Rmarkdown


2.2 Añada texto con algunas palabras en negrita y en italica


2.3 Incruste una imagen de su organismo favorito (o un gif)


2.4 Añada un enlace URL

 

Incrustar código

Para incrustar el código de R, tenemos que definir un área donde se encuentra el código. Esta ‘área’ se conoce como un segmento (o ‘chunk’) y se define mediante:

 

Observe que el recuadro de R está en gris, mientras que el resto está en fondo blanco. Todo lo que se incluye en el segmento se evalúa y muestra de acuerdo con las especificaciones, aunque estas se pueden modificar.

 

Podemos, por ejemplo, agregar una nueva columna al conjunto de datos de ejemplo de iris:

Código:

Resultado:

data(iris)

iris$random.var <- rnorm(n = nrow(iris))

head(iris)
##   Sepal.Length Sepal.Width Petal.Length Petal.Width Species  random.var
## 1          5.1         3.5          1.4         0.2  setosa -0.23725619
## 2          4.9         3.0          1.4         0.2  setosa  1.30977300
## 3          4.7         3.2          1.3         0.2  setosa  1.17011472
## 4          4.6         3.1          1.5         0.2  setosa -0.47026536
## 5          5.0         3.6          1.4         0.2  setosa -0.04163948
## 6          5.4         3.9          1.7         0.4  setosa  1.03109690

 

Cuando se procesa su documento, el segmento de código se muestra en un cuadro gris y los resultados de ese código se muestran en un cuadro blanco. ¿Qué pasa si solo desea que se muestre la salida de su código? ¿O que su código se muestre pero no se ejecute realmente? Hay argumentos que puede agregar a cada uno de sus segmentos para especificar estas y otras opciones:

Añadir el argumento echo=FALSE

Código:

Resultado:

##   Sepal.Length Sepal.Width Petal.Length Petal.Width Species  random.var
## 1          5.1         3.5          1.4         0.2  setosa -0.90731282
## 2          4.9         3.0          1.4         0.2  setosa  0.44715324
## 3          4.7         3.2          1.3         0.2  setosa -0.09989386
## 4          4.6         3.1          1.5         0.2  setosa -0.34378078
## 5          5.0         3.6          1.4         0.2  setosa -1.40185765
## 6          5.4         3.9          1.7         0.4  setosa -1.26845146

 

Puede ver que el código está oculto pero se muestran los resultados.

Esta guia sobre las opciones de los ‘chunks’ puede ser muy útil:


Ejercicio 3


3.1 Utilice los argumentos eval, echo, include, collapse con diferentes valores (TRUE o FALSE) en un segmento donde corre head(iris). ¿Cómo afectan el resultado?


3.2 Haga lo mismo con los argumentos fig.width,dpi y fig.height en un segmento cuando corra cree un gráfico. ¿Cómo afecta esta vez?

 

Incrustar gráficos

Los gráficos se pueden incrustar en documentos Rmarkdown simplemente usando funciones de graficación como lo haría en un script de R normal.

Código:

 

Resultado:

 

También puede utilizar los argumentos:

  • dpi: define puntos por pulgada
  • fig.align: alineación de la figura en el documento html, puede ser left, right o center
  • fig.height y fig.width: define el tamaño de la figura

 

Incrustar código de R en texto

Es posible que haya notado a lo largo de este tutorial que tengo pequeños fragmentos de texto que parecen “segmentos de código”. Esto se conoce como incrustación de código en texto.

Esto se puede hacer de dos maneras:

1.Dar un texto con la apariencia de un segmento de código:

Código:

 

Resultado:

El promedio de el largo del sépalo es mean(iris$Sepal.Length)

 

2. Evaluar el código en el texto

Código:

Resultado:

El promedio del largo de sépalo para setosa es 5.006.

 

Plantillas de Rmarkdown

El paquete Rmarkdown puede generar resultados en HTML, PDF, MS Word, viñetas de paquetes de R, presentaciones Beamer y HTML5. Los formatos adicionales (o ‘variantes’ de estos formatos) están disponibles en otros paquetes de R. Algunos de esos paquetes son:

  • rmdformats
  • reveljs
  • artículos
  • tufte

Se pueden instalar de la siguiente manera:

install.packages("rmdformats")
install.packages("revealjs")
install.packages("rticles")
install.packages("tufte")

Una vez instalados, los nuevos formatos estarán disponibles a través del nuevo cuadro de diálogo Rmarkdown:

 

Metadatos (YAML)

Hay tres componentes básicos de un documento de R Markdown: los metadatos, el texto y el código. Los metadatos se escriben entre el par de tres guiones - - -. La sintaxis de los metadatos es YAML (YAML Ain’t Markup Language), por lo que a veces también se denomina metadatos YAML. La sangría es importante en YAML, así que debe añadirla a los subcampos (con respecto a un campo superior).

Este encabezado muestra las opciones mas comúnmente usadas en los metadatos YAML:

---
title: "Un titulo descriptivo y sin faltas ortograficas"
author: "Marcelo Araya"
date: "`r Sys.Date()`"
output: # Varios outputs mostrados solo para el ejemplo
  pdf_document:
    toc: yes
    fig_caption: yes
    df_print: kable
  html_document:
    fig_caption: yes
    number_sections: yes
    toc: yes
    toc_float: yes
    df_print: paged
---

Documentos interactivos

Los documentos de R Markdown también pueden generar contenido interactivo.

HTML widgets

Los HTML Widgets se implementan con el paquete R htmlwidgets, que conecta herramientas de JavaScript que crean aplicaciones interactivas, como gráficos y tablas Se han desarrollado varios paquetes que emplean HTML widgets como dygraphs, DT y leaflet. En este sitio (https://www.htmlwidgets.org) se muestran una variedad de widgets disponibles así como instrucciones de como desarrollarlos.

El siguiente código utiliza el paquete leaflet para generar un mapa interactivo:

# install.packages("leaflet")
library(leaflet)

ll_map <- leaflet()

ll_map <- addTiles(map = ll_map)

ll_map <- setView( map = ll_map, lat = 5.527448, lng = -87.057245, zoom = 13)

addPopups( map = ll_map, lat = 5.527448, lng = -87.057245, popup = 'Isla del Coco')

 

Este es el ‘chunk’ que generó el mapa:

 

Note el uso del argumento de as.is = TRUE en las opciones del ‘chunk’

 

Cuadros con knitr::kable

El paquete knitr también provee una función para mostrar datos tabulares de forma ordenada y ‘limpia’ en los reportes dínamicos:

knitr::kable(iris[1:10, ])
Sepal.Length Sepal.Width Petal.Length Petal.Width Species random.var
5.1 3.5 1.4 0.2 setosa -0.9073128
4.9 3.0 1.4 0.2 setosa 0.4471532
4.7 3.2 1.3 0.2 setosa -0.0998939
4.6 3.1 1.5 0.2 setosa -0.3437808
5.0 3.6 1.4 0.2 setosa -1.4018577
5.4 3.9 1.7 0.4 setosa -1.2684515
4.6 3.4 1.4 0.3 setosa 0.5182991
5.0 3.4 1.5 0.2 setosa 1.4508394
4.4 2.9 1.4 0.2 setosa 0.4296722
4.9 3.1 1.5 0.1 setosa 0.6241219

 

El paquete ‘kableExtra’ complementa esta función con muchas herramientas para personalisar el formato de las tablas en reportes dinámicos en R.

 

Opcionales adicionales en knitr

El argumento opts_knit de knitr permite definir opciones globales (aplicables a todos los ‘chunks’ a menos que se re-definan):

opts_knit$set(root.dir = "..", eval = TRUE, echo = FALSE)


Ejercicio 4


  • Cree un reporte dinámico que incluya un mapa dinámico de Costa Rica usando el paquete leaflet



  • Instale el paquete kableExtra y incruste en su reporte el códifo de ejemplo en la documentación de la función kable_styling() de ese paquete


 

Referencias

Session information

## R version 4.0.2 (2020-06-22)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 20.04 LTS
## 
## Matrix products: default
## BLAS:   /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.9.0
## LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.9.0
## 
## locale:
##  [1] LC_CTYPE=pt_BR.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=es_CR.UTF-8        LC_COLLATE=pt_BR.UTF-8    
##  [5] LC_MONETARY=es_CR.UTF-8    LC_MESSAGES=pt_BR.UTF-8   
##  [7] LC_PAPER=es_CR.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=es_CR.UTF-8 LC_IDENTIFICATION=C       
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] leaflet_2.0.3
## 
## loaded via a namespace (and not attached):
##  [1] digest_0.6.25     R6_2.4.1          jsonlite_1.7.0    magrittr_1.5     
##  [5] evaluate_0.14     highr_0.8         rlang_0.4.7       stringi_1.4.6    
##  [9] rmarkdown_2.3     tools_4.0.2       stringr_1.4.0     htmlwidgets_1.5.1
## [13] crosstalk_1.1.0.1 xfun_0.16         yaml_2.2.1        compiler_4.0.2   
## [17] htmltools_0.5.0   knitr_1.29