Reportes dinámicos con RMarkdown

Completar hasta as 11:59 PM del viernes, 11 de agosto de 2023

Objetivo de la práctica

El objetivo de esta guía práctica es familiarizarnos con las herramientas fundamentales para crear documentos dinámicos que nos permitan combinar texto y análisis (código) en un único reporte utilizando RMarkdown.

En detalle, aprenderemos:

  1. Qué es la reproducibilidad y un flujo de trabajo reproducible
  2. Qué es escritura abierta con Markdown
  3. Qué es RMarkdown y cómo generar reportes dinámicos

1. Reproducibilidad

La reproducibilidad en ciencias sociales es esencial para garantizar resultados confiables y evitar casualidades. Imagina presentar hallazgos emocionantes en una conferencia y que te pidan que demuestres cómo llegaste a esos resultados. ¡La reproducibilidad se convierte en tu mejor amiga o peor enemiga en ese momento!

Cuando un estudio es reproducible, significa que has detallado claramente tu proceso de investigación para que cualquiera pueda seguirlo y obtener los mismos resultados. Esto no solo genera confianza en tu trabajo, sino que permite a otros construir sobre tus hallazgos y contribuir al conocimiento colectivo.

¿Cómo organizamos un proyecto reproducible? lo primero es definir una estructura de proyecto autocontenido:

  1. En este curso trabajaremos con un flujo de trabajo reproducible, basado en el sistema IPO. IPO es un protocolo de estructura digital de carpetas que permite organizar, procesar y documentar los datos de un proyecto de investigación para que cualquier persona pueda ejecutarlo y compartirlo.

  1. ¿Y cómo lo hacemos? Mediante los Rproject. Estos ya los conocemos, y son la raíz de nuestro proyecto que articula o abraza (como un pulpo) los demás componentes.

2. Escritura abierta (Markdown)

Probablemente, el programa que más se ha utilizado para la escritura sea Microsoft Word, desde pregrado hasta el mundo profesional.

Aunque útil, este procesador de texto tiene diversas barreas, ya sea de pago/licencias, problemas de versionamiento (difícil saber quién hizo qué) y no permiten reproducibilidad (tenemos que copiar y pegar). Aquí entra el texto plano.

Nota

El texto plano:

  • es un tipo de texto que se puede leer independiente del lector que use
  • es abierto y gratuito
  • permite combinar texto y análisis en un solo documento (reproducibilidad)
  • foco en el contenido, luego el formato
  • distintas opciones de salida (pdf, html, word, etc.)

Markdown es una clase especial de lenguaje que permite darle formato a texto simple con pocas marcas. Por ejemplo, poder hacer cursivas, negritas, incorporar links, etc.

Formatos básicos de Markdown

Escribe… …o… …para obtener 
Algo de texto en el párrafo.

Más texto
espacio entre lineas.

Algo de texto.

Algo de texto en el párrafo. Siempre utilizando espacios para dividir párrafos
`*Cursivas*` `_Cursivas_` Cursivas
`**Negrita**` `__Negrita__` Negrita
# Título 1

Título 1
## Título 2

Título 2
### Título 3

Título 3
(puedes llegar hasta un título N° 6 con ######)
`[Link text](http://www.example.com)` Link text
`![Image caption](/path/to/image.png)`

Class logo
` ```Inline code``` ` with backticks Inline code with backticks
> Citas

Citas

 
- Cosas en
- listas
- desordenadas
 
* Cosas en
* listas
* desordenadas

  • Cosas en

  • listas

  • desordenadas

 
1. Cosas en
2. listas
3. ordenadas
 
1) Cosas en
2) listas
3) ordenadas

  1. Cosas en

  2. listas

  3. ordenadas

 
Línea horizontal

---
 
Línea horizontal

***

Línea horizontal

3. Documentos dinámicos (RMarkdown)

R Markdown es un lenguaje que combina texto plano (Markdown) y código (R). Al mezclar ambos mundos en un solo documento .Rmd, permite la integración simúltanea de texto y análisis (código) a nuestros reportes. Esto es lo que se conoce como documentos dinámicos.

Por ejemplo, este sitio web está escrito con R Markdown, lo que nos permite demostrar cómo combinar código de R (gráficos, tablas y otros resultados) con texto plano, generando documentos reproducibles.

En el ambiente de RStudio, R Markdown es una librería de R que provee de una serie de herramientas para generar documentos dinámicos y publicarlos.

¡Veamos cómo se hace!

4. Generación de reporte

Paso 1: Instalar librerías

El primero paso para inciar un documento R Markdown en R Studio es instalar (o actualizar según sea el caso) la librería asociada. Al instalarla, también se descargan otras dependencias que permiten trabajar y publicar con RMarkdown (como knitr y también tinitex, que permite generación documentos pdf vía Latex).

Pero primero, llamemos a un viejo conocido: el paquete pacman.

install.packages("pacman") # en caso de no tener pacman instalado
library(pacman)

Ahora, instalemos las librerías para generar nuestro archivo .Rmd

pacman::p_load(rmarkdown,
               knitr)

Paso 2: Crear un nuevo archivo en Rmarkdown

  1. Una vez cargados los paquetes deben dirigirse a File > New File > R Markdown.

  2. Luego deben darle un título, poner su nombre y especificar un formato de salida, ya sea en HTML, PDF o Word.

  1. Se creará un archivo con un YAML , donde se especifican opciones generales del documento entre tres guiones (—); y un chunk, o trozo de código.

El YAML es muy importante, y consta de tres partes mínimas: título, autor y opción de formato de salida. Hay más opciones que iremos viendo durante el curso.

  1. Ahora, ya pueden comenzar a escribir sus informes en RMarkdown. Veamos otras configuraciones.

Paso 3: Crear el archivo con formato desde el .Rmd

Para generar el documento, en la salida que especifiquemos, presionamos el botón de Knitr. El Knitear permite compilar el documento tejiendo o uniendo el contenido de manera secuencial. Combinará el texto plano y el código de R (en chunks) a partir de las instrucciones que le dimos en el YAML.

Al knitear el documento, le estamos dando la instrucción a R de que pase este archivo Markdown (.md) por un convertidor universal llamado pandoc. En la práctica, este proceso se le conoce como renderizar.

El resultado aparece en el visor (Viewer) de R, o se puede seleccionar otra opción de visualización desde la rueda de configuración al lado del botón knitr.

El documento queda grabado como archivo (ej: probando.html) en el mismo directorio del archivo .Rmd

Paso 4: Opciones de chunks

La manera en que integramos código de R en un archivo RMarkdown es mediante chunks, que son trozos de código dentro de nuestra hoja. Estos permiten hacer análisis estadísticos dentro del documento visualizando los resultados en el documento final.

Los chunks se ven así dentro del .Rmd:

# El codigo va aquí

````

4.1 Añadir Chunks

Hay tres formas de insertar chunks:

  1. Pulsar ⌘⌥I en macOS o Control + Alt + I en Windows

  2. Pulsa el botón “Insert” en la parte superior de la ventana del editor

  1. Escribirlo manualmente (no recomendado)

4.2 Nombrar chunks

Se puede añadir nombres a los chunks para hacer más fácil la navegación por el documento. Si no incluyes un nombre, el chunk seguirá apareciendo, pero no sabrás lo que hace.

Para añadir un nombre, inclúyelo inmediatamente después de la {r en la primera línea del chunk. Los nombres no pueden contener espacios, pero sí guiones bajos y guiones.

Importante: Todos los nombres de chunk de tu documento deben ser únicos.

```{r nombre-chunk}
# El codigo va aquí

````

4.3 Opciones de chunks

Hay distintas opciones diferentes que puedes establecer para cada chunk. Puedes ver una lista completa en la Guía de referencia de RMarkdown o en el sitio web de knitr.

Las opciones van dentro de la sección {r} del chunk:

```{r nombre-chunk, message = F, echo = F}
# El codigo va aquí

````

Las opciones de chunk más comunes son estas:

  • echo=FALSE: El código no se muestra en el documento final, pero los resultados si

  • message=FALSE: Se omiten los mensajes que genera R (como todas las notas que aparecen después de cargar un paquete)

  • warning=FALSE: Se omiten las advertencias que genera R

  • include=FALSE: El chunk se sigue ejecutando, pero el código y los resultados no se incluyen en el documento final

Atajos de configuración de chunk: dar clic en el pequeño icono de engranaje en la esquina superior derecha de cualquier chunk:

Resumen

Hoy aprendimos a generar documentos dinámicos con RMarkdown. En detalle, aprendímos:

  1. Qué es la reproducibilidad y un flujo de trabajo reproducible
  2. Qué es escritura abierta con Markdown
  3. Qué es RMarkdown y cómo generar reportes dinámicos

Reporte de progreso

Completar el reporte de progreso correspondiente a esta práctica aquí. El plazo para contestarlo es hasta el día viernes de la semana en la que se publica la práctica correspondiente.

Video de práctica

Foro