Objetivos del manual

Familiarizarse con el formato para reportes dinámicos Rmarkdown
Ser capaz de documentar el manejo y análisis de datos en R usando Rmarkdown

Paquetes a utilizar en este manual:

# vector con paquetes
ptqs <- c("leaflet", "remotes", "hadley/emo", "maRce10/sketchy", "knitr",
    "rmarkdown", "kableExtra", "rmdformats", "revealjs", "rticles",
    "tufte")

# bucle para instalar/cargar paquetes
instalado <- sapply(ptqs, function(y) {

    ptq <- strsplit(y, "/")[[1]]
    ptq <- ptq[length(ptq)]

    if (!ptq %in% installed.packages()[, "Package"]) {
        if (grepl("/", y))
            remotes::install_github(y, force = TRUE) else install.packages(y)
    }

    try(require(ptq, character.only = TRUE), silent = TRUE)
})

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

Baker. 2016. Nature

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. 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.

Ventajas de los reportes dinámicos con Rmarkdown:

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

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 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). 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:

Crear encabezados de varios tamaños

Código:

Resultado:

Encabezado 1

Encabezado 2

Encabezado 3

Opciones del texto

Código:

Resultado:

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

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:

include_graphics("./images/rmarkdown_icon.png")

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.

Crear enlaces (‘hyperlinks’)

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 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:

data(iris)

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

head(iris)

Sepal.Length	Sepal.Width	Petal.Length	Petal.Width	Species	random.var
5.1	3.5	1.4	0.2	setosa	-0.594
4.9	3.0	1.4	0.2	setosa	1.127
4.7	3.2	1.3	0.2	setosa	1.020
4.6	3.1	1.5	0.2	setosa	-1.991
5.0	3.6	1.4	0.2	setosa	1.951
5.4	3.9	1.7	0.4	setosa	0.174

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:

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	-0.8182
4.9	3.0	1.4	0.2	setosa	1.0581
4.7	3.2	1.3	0.2	setosa	0.9150
4.6	3.1	1.5	0.2	setosa	-0.8268
5.0	3.6	1.4	0.2	setosa	-0.6997
5.4	3.9	1.7	0.4	setosa	0.0013

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.

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:

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?

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:

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

Código:

Resultado:

El promedio del 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.

Recursos adicionales para personalizar documentos 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 (“- - -”) 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:

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

En este enlace se explican en detalle las opciones disponibles en el encabezado YAML de archivos Rmarkdown.

Emojis

El paquete emo permite añadir emojis al evaluar un código:

emo::ji("costa_rica")

🇨🇷

Tambien se puede incrustar en el texto 🇨🇷, como lo vimos mas arriba ⬆️ (ji("up_arrow"))

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.8182
4.9	3.0	1.4	0.2	setosa	1.0581
4.7	3.2	1.3	0.2	setosa	0.9150
4.6	3.1	1.5	0.2	setosa	-0.8268
5.0	3.6	1.4	0.2	setosa	-0.6997
5.4	3.9	1.7	0.4	setosa	0.0013
4.6	3.4	1.4	0.3	setosa	1.7156
5.0	3.4	1.5	0.2	setosa	-0.0279
4.4	2.9	1.4	0.2	setosa	0.2797
4.9	3.1	1.5	0.1	setosa	-0.1911

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

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):

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

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.

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:

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.

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:

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 bloque de código que generó el mapa:

Note el uso del argumento de as.is = TRUE en las opciones del bloque de código.

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:

---
title: "Documento Shiny"
output: html_document
runtime: shiny
---

El siguiente código crea una aplicación shiny dentro del documento Rmarkdown:

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.

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:

Herramientas adicionales para organizar análisis de datos

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:

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):

path <- tempdir()

make_compendium(name = "proyecto_x", path = path, format = "basic",
    Rproj = TRUE)

## 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.

Ejercicio 4

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

Reproduzca 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 kableExtra y incruste en su reporte el códifo de ejemplo en la documentación de la función kable_styling() de ese paquete

Cree 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

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.1 (2021-08-10)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 20.04.2 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=es_ES.UTF-8      
##  [2] LC_NUMERIC=C              
##  [3] LC_TIME=es_CR.UTF-8       
##  [4] LC_COLLATE=es_ES.UTF-8    
##  [5] LC_MONETARY=es_CR.UTF-8   
##  [6] LC_MESSAGES=es_ES.UTF-8   
##  [7] LC_PAPER=es_CR.UTF-8      
##  [8] LC_NAME=C                 
##  [9] LC_ADDRESS=C              
## [10] LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=es_CR.UTF-8
## [12] LC_IDENTIFICATION=C       
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets 
## [6] methods   base     
## 
## other attached packages:
##  [1] tufte_0.12          rticles_0.24       
##  [3] revealjs_0.9        rmdformats_1.0.4   
##  [5] rmarkdown_2.14      sketchy_1.0.2      
##  [7] remotes_2.4.2       leaflet_2.1.1      
##  [9] car_3.1-0           carData_3.0-5      
## [11] sjPlot_2.8.10       lmerTest_3.1-3     
## [13] lme4_1.1-29         Matrix_1.3-4       
## [15] scales_1.2.0        MASS_7.3-54        
## [17] emo_0.0.0.9000      viridis_0.6.2      
## [19] viridisLite_0.4.0   xaringanExtra_0.7.0
## [21] ggplot2_3.3.6       RColorBrewer_1.1-3 
## [23] kableExtra_1.3.4    knitr_1.39         
## 
## loaded via a namespace (and not attached):
##   [1] minqa_1.2.4         colorspace_2.0-3   
##   [3] ellipsis_0.3.2      rsconnect_0.8.26   
##   [5] sjlabelled_1.2.0    rprojroot_2.0.3    
##   [7] estimability_1.3    parameters_0.18.1  
##   [9] fs_1.5.2            rstudioapi_0.13    
##  [11] farver_2.1.1        fansi_1.0.3        
##  [13] mvtnorm_1.1-3       lubridate_1.8.0    
##  [15] xml2_1.3.3          splines_4.1.1      
##  [17] cachem_1.0.6        sjmisc_2.8.9       
##  [19] pkgload_1.2.4       jsonlite_1.8.0     
##  [21] nloptr_2.0.3        ggeffects_1.1.2    
##  [23] packrat_0.8.0       broom_0.8.0        
##  [25] effectsize_0.7.0    compiler_4.1.1     
##  [27] httr_1.4.3          backports_1.4.1    
##  [29] sjstats_0.18.1      emmeans_1.7.4-1    
##  [31] assertthat_0.2.1    fastmap_1.1.0      
##  [33] cli_3.3.0           formatR_1.12       
##  [35] htmltools_0.5.3     prettyunits_1.1.1  
##  [37] tools_4.1.1         coda_0.19-4        
##  [39] gtable_0.3.0        glue_1.6.2         
##  [41] dplyr_1.0.9         Rcpp_1.0.9         
##  [43] jquerylib_0.1.4     vctrs_0.4.1        
##  [45] svglite_2.1.0       nlme_3.1-152       
##  [47] crosstalk_1.2.0     insight_0.17.1     
##  [49] xfun_0.31           stringr_1.4.0      
##  [51] ps_1.7.1            brio_1.1.3         
##  [53] testthat_3.1.4      rvest_1.0.2        
##  [55] lifecycle_1.0.1     devtools_2.4.3     
##  [57] ragg_1.2.2          yaml_2.3.5         
##  [59] memoise_2.0.1       gridExtra_2.3      
##  [61] sass_0.4.1          stringi_1.7.8      
##  [63] highr_0.9           bayestestR_0.12.1  
##  [65] desc_1.4.1          boot_1.3-28        
##  [67] pkgbuild_1.3.1      rlang_1.0.4        
##  [69] pkgconfig_2.0.3     systemfonts_1.0.4  
##  [71] evaluate_0.15       lattice_0.20-44    
##  [73] purrr_0.3.4         htmlwidgets_1.5.4  
##  [75] labeling_0.4.2      processx_3.6.1     
##  [77] tidyselect_1.1.2    bookdown_0.27      
##  [79] magrittr_2.0.3      R6_2.5.1           
##  [81] generics_0.1.2      DBI_1.1.3          
##  [83] pillar_1.8.0        withr_2.5.0        
##  [85] mgcv_1.8-36         abind_1.4-5        
##  [87] datawizard_0.4.1    tibble_3.1.8       
##  [89] performance_0.9.0   modelr_0.1.8       
##  [91] crayon_1.5.1        uuid_1.1-0         
##  [93] utf8_1.2.2          usethis_2.1.6      
##  [95] grid_4.1.1          isoband_0.2.5      
##  [97] callr_3.7.0         digest_0.6.29      
##  [99] webshot_0.5.3       xtable_1.8-4       
## [101] tidyr_1.2.0         numDeriv_2016.8-1.1
## [103] textshaping_0.3.6   munsell_0.5.0      
## [105] bslib_0.3.1         sessioninfo_1.2.2

Reportes dinámicos con Rmarkdown

Programación y métodos estadísticos avanzados en R

Marcelo Araya-Salas, PhD

“2022-10-31”

Objetivos del manual

Crisis de reproducibilidad en la ciencia

Ventajas de los reportes dinámicos con Rmarkdown:

Crear documentos R Markdown

Ejercicio 1

Syntaxis Markdown

Crear encabezados de varios tamaños

Encabezado 1

Encabezado 2

Encabezado 3

Opciones del texto

Añadir una imagen

Crear enlaces (‘hyperlinks’)

Ejercicio 2

Incrustar código

Ocultar código

Incrustar gráficos

Código:

Resultado:

Ejercicio 3

Incrustar código de R en el texto

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

Código:

Resultado:

2. Evaluar el código en el texto

Código:

Resultado:

Recursos adicionales para personalizar documentos Rmarkdown

Metadatos (YAML)

Emojis

Cuadros con knitr::kable

Opciones adicionales en knitr

Presentaciones y otros opciones de formato

Plantillas de Rmarkdown

Documentos interactivos

HTML widgets

Aplicaciones shiny

Publicar reportes en linea con Rpubs

Herramientas adicionales para organizar análisis de datos

Proyectos de Rstudio

Compendios de investigación

Ejercicio 4

Referencias