Reportes dinámicos
Objetivos del manual
Familiarizarse con el formato para reportes dinámicos Rmarkdown/quarto
Ser capaz de documentar el manejo y análisis de datos en R usando Rmarkdown/quarto
Paquetes a utilizar en este manual:
1 Crisis de reproducibilidad en la ciencia
La mayoría de los procedimientos (incluyendo análisis de datos) en estudios científicos no se pueden replicar
El compartir datos y análisis de forma transparente y detalladamente documentada, en formatos que puedan ser reproducidos por otros investigadores es una de las principales herramientas para lidiar con este problema.
Gallagher et al. 2020. Nature Eco & Evo
Las herramientas programáticas como R tienden naturalmente a facilitar la reproducibilidad ya que el código de un análisis se puede registrar y compartir fácilmente. Muchos lenguajes de programación permiten la generación de reportes dinámicos, los cuales resultan fundamentales para hacer manejo de datos y análisis estadísticos reproducibles. La principal forma en que R facilita la investigación reproducible es utilizando un documento que es una combinación de contenido y código de análisis de datos. Los reportes dinámicos suelen contener toda la información necesaria para que otros investigadores puedan replicar todos los pasos de análisis que generaron los resultados de artículos científicos. Por tanto son una herramienta indispensable para mejorar la reproduciblidad en la ciencia.
En R la herramienta mas popular para la generación de reportes dinámicos es Rmarkdown. Rmarkdown 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 bloques de código de R (“chunks”) incrustados entre líneas de texto. Cuando se procesa el documento, estos bloques se evalúan (si el usuario así lo desea) y los resultados se “imprimen” en el documento de acuerdo con ciertas convenciones.
Quarto es una herramienta muy similar a Rmarkdown. La diferencia mas importante es la capacidad de quarto para generar reportes usando otros lenguajes de programación. Sin embargo, en términos de sintaxis ambos formatos son muy parecidos. La mayoría de las funcionalidades mostradas acá son válidas para ambos formatos (en este enlace se puede encontrar una comparación detallada de ambos formato).
1.1 Ventajas de los reportes dinámicos con Rmarkdown/quarto:
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 programación (i.e. R o HTML) para comprenderlos
El resultado es un archivo HTML que incluye imágenes, bloques de código con los comandos de R, los resultados de estos códigos 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 actualizan fácilmente para incluir nuevos análisis y/o integrar nuevos datos
2 Crear documentos R Markdown/quarto
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/quarto funcione.
Aparecerá una ventana que le pedirá un título 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) o ‘.qmd’ (quarto). El nuevo archivo ya viene con una plantilla con instrucciones básicas:
2.1 Ejercicio 1
Cree un nuevo archivo R Markdown o quarto, escriba algunas líneas de texto y haga clic en “Knit” para ver cómo se verá su reporte.
3 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:
3.1 Crear encabezados de varios tamaños
Código:
Resultado:
4 Encabezado 1
4.1 Encabezado 2
4.1.1 Encabezado 3
4.2 Opciones del texto
Código:
Resultado:
Hacer texto en negrita, itálico, tachado, o superíndice
4.3 Añadir una imagen
Código:
Resultado:
También podemos añadir una imagen con la función include_graphics() del paquete knitr.
Código:
Resultado:
Note que esta opción nos permite hacer uso de los argumentos del bloque de código dedicados a la graficación, y po r tanto es una opción mas flexible.
4.4 Crear enlaces (‘hyperlinks’)
Código:
Resultado:
Crear un enlace a figshare
4.5 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
4.6 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 bloque de código (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:
Resultado:
| Sepal.Length | Sepal.Width | Petal.Length | Petal.Width | Species | random.var |
|---|---|---|---|---|---|
| 5.1 | 3.5 | 1.4 | 0.2 | setosa | 0.28291 |
| 4.9 | 3.0 | 1.4 | 0.2 | setosa | 1.12667 |
| 4.7 | 3.2 | 1.3 | 0.2 | setosa | -1.06662 |
| 4.6 | 3.1 | 1.5 | 0.2 | setosa | 0.73385 |
| 5.0 | 3.6 | 1.4 | 0.2 | setosa | -0.07117 |
| 5.4 | 3.9 | 1.7 | 0.4 | setosa | 0.17405 |
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 bloques para especificar estas y otras opciones:
4.7 Ocultar código
Añadir el argumento echo=FALSE
Código:
Resultado:
| Sepal.Length | Sepal.Width | Petal.Length | Petal.Width | Species | random.var |
|---|---|---|---|---|---|
| 5.1 | 3.5 | 1.4 | 0.2 | setosa | -1.21560 |
| 4.9 | 3.0 | 1.4 | 0.2 | setosa | -0.78151 |
| 4.7 | 3.2 | 1.3 | 0.2 | setosa | 1.28619 |
| 4.6 | 3.1 | 1.5 | 0.2 | setosa | -0.13427 |
| 5.0 | 3.6 | 1.4 | 0.2 | setosa | -0.49963 |
| 5.4 | 3.9 | 1.7 | 0.4 | setosa | -2.63334 |
Puede ver que el código está oculto pero se muestran los resultados.
Esta guía sobre las opciones de los bloques de código puede ser muy útil:
En este enlace se detallan todos los argumentos disponibles para personalizar los bloques de código.
4.8 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.
4.8.0.1 Código:
4.8.0.2 Resultado:
4.9 Ejercicio 3
3.1 Utilice los argumentos eval, 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 out.width, fig.width,dpi y fig.height en un segmento que cree un gráfico. ¿Cómo afecta esta vez?
4.10 Incrustar código de R en el texto
Es posible que haya notado a lo largo de este tutorial que tengo pequeños fragmentos de texto que parecen “bloques de código”. Esto se conoce como incrustación de código en texto.
Esto se puede hacer de dos maneras:
4.10.0.1 1.Dar un texto con la apariencia de un segmento de código:
4.10.0.2 Código:
4.10.0.3 Resultado:
El promedio del largo del sépalo es mean(iris$Sepal.Length)
4.10.0.4 2. Evaluar el código en el texto
4.10.0.5 Código:
4.10.0.6 Resultado:
El promedio del largo de sépalo para setosa es 5.006.
5 Recursos adicionales para personalizar documentos Rmarkdown
5.1 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 (“- - -”) generalmente al inicio del documento. 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:
En este enlace se explican en detalle las opciones disponibles en el encabezado YAML de archivos Rmarkdown.
5.2 Emojis
El paquete emo permite añadir emojis al evaluar un código:
🇨🇷
Tambien se puede incrustar en el texto 🇨🇷, como lo vimos mas arriba ⬆️ (ji("up_arrow"))
5.3 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:
| Sepal.Length | Sepal.Width | Petal.Length | Petal.Width | Species | random.var |
|---|---|---|---|---|---|
| 5.1 | 3.5 | 1.4 | 0.2 | setosa | -1.21560 |
| 4.9 | 3.0 | 1.4 | 0.2 | setosa | -0.78151 |
| 4.7 | 3.2 | 1.3 | 0.2 | setosa | 1.28619 |
| 4.6 | 3.1 | 1.5 | 0.2 | setosa | -0.13427 |
| 5.0 | 3.6 | 1.4 | 0.2 | setosa | -0.49963 |
| 5.4 | 3.9 | 1.7 | 0.4 | setosa | -2.63334 |
| 4.6 | 3.4 | 1.4 | 0.3 | setosa | -0.14534 |
| 5.0 | 3.4 | 1.5 | 0.2 | setosa | -0.73692 |
| 4.4 | 2.9 | 1.4 | 0.2 | setosa | 0.69442 |
| 4.9 | 3.1 | 1.5 | 0.1 | setosa | -0.00822 |
El paquete kableExtra complementa esta función con muchas herramientas para personalizar el formato de las tablas en reportes dinámicos en R.
5.4 Opciones adicionales en knitr
El argumento opts_knit de knitr permite definir opciones globales (aplicables a todos los bloques a menos que se re-definan):
5.5 Presentaciones y otros opciones de formato
Note en la ventana de creación de un nuevo documento Rmarkdown las opciones adicionales de formato:
Los reportes dinámicos se pueden generar en otros formatos incluyendo presentaciones, pdf y documentos de word.
5.6 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
Una vez estos paquetes han sido instalados, los nuevos formatos estarán disponibles a través del nuevo cuadro de diálogo Rmarkdown:
6 Documentos interactivos
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.
6.1 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:
Código
6.2 Aplicaciones shiny
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:
El siguiente código crea una aplicación shiny dentro del documento Rmarkdown:
Código
sketchy::load_packages("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)
Note que esta aplicación no funciona en documentos estáticos de Rmarkdown. 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.
7 Publicar reportes en linea con Rpubs
La plataforma en linea Rpubs permite publicar los reportes en formato HTML. Esta opción simplifica mucho el compartir códigos, análisis y resultados ya que solamente necesitamos enviar el la dirección URL. Aún mas, podemos seguir actualizando los reportes y la misma dirección URL seguirá conteniendo las versiones actualizadas de los reportes.
Para enviar nuestros reportes HTML a Rpubs debemos primero hacer una cuenta en el sitio. Luego de esto simplemente tenemos que usar el enlace “publish” en la esquina superior derecha de los reportes:
8 Herramientas adicionales para organizar análisis de datos
8.1 Proyectos de Rstudio
Los proyectos de Rstudio crean carpetas donde se guardan los archivos relacionados a un análisis específico (código y datos) y hacen de esta carpeta el directorio de trabajo por defecto cuando se abre el proyecto. Se pueden crear de esta forma:
Luego aparecera una seria de ventanas donde pueden escoger que tipo de proyecto y el nombre de este:
8.2 Compendios de investigación
Los compendios de investigación son estructuras de carpetas pre-definidas que permiten seguir un orden lógico e intuitivo para organizar los archivos usados y generados en un análisis de datos de un proyecto de investigación. El paquete sketchy genera estos compendios, permitiendo al usuario seleccionar entre una gama de compendios comunes en la comunidad científica. Este ejemplo crea el compendio básico (uno de los 14 que vienen con el paquete):
Código
Creating directories ...
proyecto_x
│
├── data/
│ ├── processed/ # modified/rearranged data
│ └── raw/ # original data
├── manuscript/ # manuscript/poster figures
├── output/ # all non-data products of data analysis
└── scripts/ # code
Done.El paquete crea archivos Rmarkdown con plantillas para el análisis de datos (carpeta “scripts”) y escritura de manuscritos (carpeta “manuscript”). Corra path en la consola de R para ver la dirección de la carpeta donde se creo el compendio.
8.3 Ejercicio 4
Cree un reporte dinámico que incluya un mapa dinámico de Costa Rica usando el paquete
leafletReproduzca alguno de los ejemplos disponibles en el sitio del paquete dygraphs (https://rstudio.github.io/dygraphs/) e incrústelo en su reporte dinámico
Instale el paquete
kableExtray incruste en su reporte el códifo de ejemplo en la documentación de la funciónkable_styling()de ese paqueteCree una presentación Rmarkdown utilizando la opción “Presentation” en la ventana de creación
Genere un reporte dinámico en formato PDF
Cree un proyecto de Rstudio para organizar los contenidos del curso
Cree un compendio de investigación con sketchy
8.4 Referencias
- R Markdown: The Definitive Guide
- Rmarkdown custom format
- Rmarkdown website
- Jacolien van Rij: Rmarkdown variants
- Danielle Quinn: R Lessons
- Vaidyanathan, Ramnath, Yihui Xie, JJ Allaire, Joe Cheng, and Kenton Russell. 2019. Htmlwidgets: HTML Widgets for R. https://github.com/ramnathv/htmlwidgets.
Información de la sesión
R version 4.1.2 (2021-11-01)
Platform: x86_64-pc-linux-gnu (64-bit)
Running under: Ubuntu 22.04.2 LTS
Matrix products: default
BLAS: /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.10.0
LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.0
locale:
[1] LC_CTYPE=es_CR.UTF-8 LC_NUMERIC=C
[3] LC_TIME=es_CR.UTF-8 LC_COLLATE=es_CR.UTF-8
[5] LC_MONETARY=es_CR.UTF-8 LC_MESSAGES=es_CR.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] tufte_0.13 rticles_0.25 revealjs_0.9 rmdformats_1.0.4
[5] rmarkdown_2.25 knitr_1.45 sketchy_1.0.2 emo_0.0.0.9000
[9] remotes_2.4.2.1 leaflet_2.2.0
loaded via a namespace (and not attached):
[1] rstudioapi_0.13 magrittr_2.0.3 R6_2.5.1
[4] rlang_1.1.2 fastmap_1.1.1 stringr_1.5.0
[7] tools_4.1.2 packrat_0.9.2 xfun_0.41
[10] cli_3.6.1 jquerylib_0.1.4 htmltools_0.5.7
[13] crosstalk_1.2.0 yaml_2.3.7 digest_0.6.33
[16] assertthat_0.2.1 lifecycle_1.0.4 bookdown_0.36
[19] crayon_1.5.2 purrr_0.3.4 htmlwidgets_1.5.4
[22] glue_1.6.2 evaluate_0.23 xaringanExtra_0.7.0
[25] stringi_1.7.12 compiler_4.1.2 generics_0.1.2
[28] jsonlite_1.8.7 lubridate_1.8.0