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.
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
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.
Markdown (y por extensión Rmarkdown) tiene sus propias reglas sintácticas. Sin embargo, este lenguaje es relativamente simple y fácil de dominar:
Crear encabezados de varios tamaños:
Hacer texto en negrita, itálico, tachado, o superíndice
Añadir una imagen:
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
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:
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.05434013
## 2 4.9 3.0 1.4 0.2 setosa -0.74004660
## 3 4.7 3.2 1.3 0.2 setosa 0.83023623
## 4 4.6 3.1 1.5 0.2 setosa 0.65041377
## 5 5.0 3.6 1.4 0.2 setosa 0.90883735
## 6 5.4 3.9 1.7 0.4 setosa 0.29212533
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
## Sepal.Length Sepal.Width Petal.Length Petal.Width Species random.var
## 1 5.1 3.5 1.4 0.2 setosa 0.28410528
## 2 4.9 3.0 1.4 0.2 setosa -0.03487891
## 3 4.7 3.2 1.3 0.2 setosa 0.85089196
## 4 4.6 3.1 1.5 0.2 setosa -0.03433997
## 5 5.0 3.6 1.4 0.2 setosa -1.56612742
## 6 5.4 3.9 1.7 0.4 setosa 0.63217216
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?
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.
También puede utilizar los argumentos:
dpi
: define puntos por pulgadafig.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
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:
El promedio de el largo del sépalo es mean(iris$Sepal.Length)
El promedio del largo de sépalo para setosa es 5.006.
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:
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:
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
---
Los documentos de R Markdown también pueden generar contenido interactivo. Hay dos tipos de documentos interactivos de R Markdown: HTML Widgets y aplicaciones Shiny.
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’
El paquete shiny
crea aplicaciones web interactivas en R. Para llamar al código shiny
desde un documento R Markdown, agregue ‘runtime’: shiny a los metadatos YAML, como en este ejemplo:
---
title: "Documento Shiny"
output: html_document
runtime: shiny
---
El siguiente código generaría una aplicación shiny dentro del documento Rmarkdown, aunque este no puede ser incluida en el HTML:
# install.packages("shiny")
library(shiny)
ui <- fluidPage(
titlePanel("Ejemplo"),
sidebarLayout(
sidebarPanel(
sliderInput(inputId = "bins",
label = "Numero de barras:",
min = 1,
max = 50,
value = 30)
),
mainPanel(
plotOutput(outputId = "distPlot")
)
)
)
server <- function(input, output) {
output$distPlot <- renderPlot({
x <- faithful$waiting
bins <- seq(min(x), max(x), length.out = input$bins + 1)
hist(x, breaks = bins, col = "#3E4A89FF", border = "white",
xlab = "Tiempo de espera para la siguiente erupcion",
main = "Histograma del tiempo de espera")
})
}
# Crear Shiny app
shinyApp(ui = ui, server = server)
En el sitio https://shiny.rstudio.com/gallery pueden encontrar muchos ejemplos de aplicaciones shiny. Estas aplicaciones son complejas de incluir en archivos auto-contenidos y por ello no son tan amigables para reportes dinámicos como los que podemos generar con R markdown.
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.2841053 |
4.9 | 3.0 | 1.4 | 0.2 | setosa | -0.0348789 |
4.7 | 3.2 | 1.3 | 0.2 | setosa | 0.8508920 |
4.6 | 3.1 | 1.5 | 0.2 | setosa | -0.0343400 |
5.0 | 3.6 | 1.4 | 0.2 | setosa | -1.5661274 |
5.4 | 3.9 | 1.7 | 0.4 | setosa | 0.6321722 |
4.6 | 3.4 | 1.4 | 0.3 | setosa | -0.0463756 |
5.0 | 3.4 | 1.5 | 0.2 | setosa | -2.3275495 |
4.4 | 2.9 | 1.4 | 0.2 | setosa | 2.2236510 |
4.9 | 3.1 | 1.5 | 0.1 | setosa | -2.0544389 |
El paquete ‘kableExtra’ complementa esta función con muchas herramientas para personalisar el formato de las tablas en reportes dinámicos en R.
El argumento opts_knit
de knitr
permite definir opciones globales (aplicables a todos los ‘chunks’ a menos que se re-definan):
opts_chunk$set(root.dir = "..", eval = TRUE, echo = FALSE)
Ejercicio 4
leaflet
kableExtra
y incruste en su reporte el códifo de ejemplo en la documentación de la función kable_styling()
de ese paquete
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.1 magrittr_1.5
## [5] evaluate_0.14 highr_0.8 rlang_0.4.8 stringi_1.5.3
## [9] rmarkdown_2.4 tools_4.0.2 stringr_1.4.0 htmlwidgets_1.5.2
## [13] crosstalk_1.1.0.1 xfun_0.18 yaml_2.2.1 compiler_4.0.2
## [17] htmltools_0.5.0 knitr_1.30