Produciendo informes con knitr
Última actualización: 2024-09-05 | Mejora esta página
Tiempo estimado: 75 minutos
Hoja de ruta
Preguntas
- ¿Cómo puedo integrar programas e informes?
Objetivos
- Valor de informes reproducibles
- Conceptos básicos de Markdown
- Fragmentos de código en R
- Opciones de fragmentos
- Código R en línea
- Otros formatos de salida
Informes de análisis de datos
Los analistas de datos tienden a escribir muchos informes, describiendo sus análisis y resultados, para sus colaboradores o para documentar su trabajo para referencia futura.
Es común que muchos nuevos usuarios comiencen escribiendo una rutina R con todos sus trabajos. Luego simplemente envien el análisis por un correo electrónico a su colaborador, describiendo los resultados y adjuntando el script y varios gráficos. Éste método puede ser problemático, ya que al discutir los resultados, a menudo hay confusión sobre qué gráfico corresponde a cuál resultado.
Escribir informes formales, con Word o LaTeX, puede simplificar esto, al incorporar el análisis y los resultados a un documento único. Pero arreglando el formato del documento para hacer que las figuras se vean bien y corregir saltos de página rebeldes puede ser tedioso y llevar mucho tiempo.
Crear una página web (como un archivo html) usando R markdown hace que el todo sea mas sencillo. El reporte puede ser muy largo, así que figuras altas que no cabrían normalmente en una página, pueden incluirse en tamaño original, ya que el lector las puede ver simplemente desplazando la página. Dar formato es simple y fácil de modificar, por lo que podemos dedicar más tiempo a nuestros análisis y no a la redacción de informes.
Programación literaria
Idealmente, dichos informes de análisis son documentos reproducibles: Si se descubre un error, o si se agregan algunos temas adicionales a los datos, puedes volver a compilar el informe y obtener los resultados, nuevo o corregido (en lugar de tener que reconstruir figuras, pegarlas en un documento de Word y luego editar manualmente varios resultados detallados).
La herramienta clave para R es knitr, que te permite crear un documento que es una mezcla de texto y algunos fragmentos de código. Cuando el documento es procesado por knitr, los fragmentos del código R serán ejecutados, y los gráficos u otros resultados serán insertados.
Este tipo de idea ha sido llamado “programación literaria”.
knitr te permite mezclar básicamente cualquier tipo de texto con cualquier tipo de código, pero te recomendamos que uses R Markdown, que mezcla Markdown con R. Markdown es un ligero lenguaje de marcado para crear páginas web y también otros formatos.
Creando un archivo R Markdown
Dentro de R Studio, haz clic en Archivo; Nuevo archivo; R Markdown y obtendrás un cuadro de diálogo parecido a éste:
Puedes mantener el valor predeterminado (salida HTML), pero dale un título.
Componentes básicos de R Markdown
El fragmento inicial de texto contiene instrucciones para R: le das un título, autor y fecha, y díle que va a querer producir una salida html (en otras palabras, una página web).
---
title: "Documento inicial **R Markdown**"
author: "Karl Broman"
date: "23 de Abril de 2015"
output: html_document
---
Puedes eliminar cualquiera de esos campos si no los quieres incluidos. Las comillas dobles no son estrictamente necesarias en este caso. Pero en su mayoría son necesarias si deseas incluir dos puntos en el título.
RStudio crea el documento con un texto de ejemplo para ayudarte a empezar. Observa a continuación que hay fragmentos como
```{r} summary(cars) ```
Estos son fragmentos de código R que serán ejecutados por knitr y reemplazados por sus resultados. Más sobre esto más tarde.
También fíjate en la dirección web que se coloca
entre corchetes angulares (<>
) así como los
asteriscos dobles en **Knit**
. Esto es Markdown.
Markdown
Markdown es un sistema para escribir páginas web marcando el texto tanto como lo haría en un correo electrónico en lugar de escribir código html. El texto marcado es convertido a html, reemplazando las marcas con el código HTML.
Por ahora, borremos todas las cosas que están ahí y escribamos un poco de markdown.
Haces las cosas en negrita usando dos asteriscos,
como esto: ** negrita **
, y haces cosas italicas
usando guiones bajos, como esto: _italics_
.
Puedes hacer una lista con viñetas escribiendo una lista con guiones o asteriscos, como esta:
* negrita con doble asterisco
* itálica con guiones bajos
* tipografía estilo código fuente con acento inverso/grave
o así:
- negrita con doble asterisco
- itálica con guiones bajos
- tipografía estilo código fuente con acento inverso/grave
Cada uno aparecerá como:
- negrita con doble asterisco
- itálica con guiones bajos
- tipografía estilo código fuente con acento inverso/grave
Puedes usar el método que prefieras (guiones o asteriscos), pero se consistente. Esto mantiene la legibilidad del código.
Puedes hacer una lista numerada simplemente usando números. Puedes incluso usar el mismo número una y otra vez si lo deseas:
1. negrita con doble asterisco
1. itálica con guiones bajos
1. tipografía estilo código fuente con acento inverso/grave
Esto aparecerá como:
- negrita con doble asterisco
- itálica con guiones bajos
- tipografía estilo código fuente con acento inverso/grave
Puedes crear encabezados de sección de diferentes tamaños iniciando
una línea con un cierto número de símbolos #
:
# Título
## Sección principal
### Subsección
#### Sub-subsección
Tú compilas el documento R Markdown a una página web html haciendo clic en el “Knit HTML” en la esquina superior izquierda. Y ten en cuenta el pequeño signo de interrogación junto a él; haz clic en el signo de interrogación y obtendrá un “Markdown Quick Reference” (con la sintaxis Markdown) así como para la documentación de RStudio en R Markdown.
Desafío
Crea un nuevo documento R Markdown. Elimina todos los fragmentos de código R y escribe un poco de Markdown (algunas secciones, algunos textos en itálica, y una lista de ítemes).
Convierte el documento a una página web.
Un poco más de Markdown
Puedes hacer un hipervínculo como éste:
[text to show](http://the-web-page.com)
.
Puedes incluir un archivo de imagen como éste:
![caption](http://url/for/file)
Puedes hacer subíndices (por ejemplo, F2) con
F~2
y superíndices (p. F2) con
F^2^
.
Si sabes cómo escribir ecuaciones en [LaTeX] (http://www.latex-project.org/),
te alegrará saber que puedes usar $ $
y $$ $$
para insertar ecuaciones matemáticas, como $E = mc^2$
y
$$y = \mu + \sum_{i=1}^p \beta_i x_i + \epsilon$$
Fragmentos de código R
Markdown es interesante y útil, pero el poder real proviene de la mezcla entre markdown y fragmentos de código R. Esto es R Markdown. Cuando procesado, el código R se ejecutará; si producen figuras, las figuras se insertarán en el documento final.
Los fragmentos del código principal se ven así:
```{r load_data} gapminderEs decir, coloca un fragmento de código R entre
```{r chunk_name}
y```
. Es una buena idea darle a cada fragmento un nombre, ya que te ayudarán a corregir los errores y, si alugnos gráficos son producidos, los nombres de archivo estarán basados en el nombre del fragmento de código que los produjo.Desafío
Agrega fragmentos de código para
- Cargar el paquete ggplot2
- Leer los datos del gapminder
- Crear un gráfico
Cómo se compilan las cosas
Cuando presionas el botón “Knit HTML”, el documento R Markdown es procesado por knitr y un documento Markdown simple es producido (así como, potencialmente, un conjunto de archivos de figuras): el código R es ejecutado y reemplazado por ambas la entrada y la salida; si las figuras son producidas, se incluyen enlaces a esas figuras.
Los documentos Markdown y figura son entones procesados por la herramienta pandoc, que convierte el archivo Markdown en un archivo html, con las figuras embebidas.
Opciones de fragmento
Hay una variedad de opciones quen afectan la forma en que los fragmentos de código son tratado
- Usa
echo=FALSE
para evitar que se muestre el código en sí. - Usa
results="hide"
para evitar que se impriman los resultados. - Usa
eval=FALSE
para tener el código mostrado pero no evaluado. - Usa
warning=FALSE
ymessage=FALSE
para ocultar cualquier advertencia o mensajes producidos - Usa
fig.height
yfig.width
para controlar el tamaño de las figuras producidas (en pulgadas).
Entonces podrías escribir:
```{r load_libraries, echo=FALSE, message=FALSE} library("dplyr") library("ggplot2") ```
A menudo habrá opciones particulares que querrás usar repetidamente; para esto, puede establecer las opciones de fragnento global, de esta forma:
```{r global_options, echo=FALSE} knitr::opts_chunk$set(fig.path="Figs/", message=FALSE, warning=FALSE, echo=FALSE, results="hide", fig.width=11) ```
La opción fig.path
define dónde se guardarán las
figuras. El /
aquí es realmente importante; sin él, las
figuras se guardarían en el lugar estándar, pero solo con los nombres
que están con Figs
.
Si tienes varios archivos R Markdown en un
directorio común, es posible que quieras usar fig.path
para
definir prefijos separados para los nombres de archivo de figura , como
fig.path="Figs/cleaning-"
y
fig.path="Figs/analysis-"
.
Desafío
Usa las opciones de fragmentos para controlar el tamaño de una figura y ocultar el código.
Código R en línea
Puedes hacer cada número de tu informe reproducible. Usa
`r
y `
para un fragmento de código en línea,
al igual que: `r round(some_value, 2)`
. El código será
ejecutado y reemplazado con el valor del resultado.
No dejes que estos fragmentos en línea se dividan en líneas.
Tal vez anteceda el párrafo con un fragmento de código más grande que
hace cálculos y define cosas, con include=FALSE
para ese
largo fragmento (que es lo mismo que echo=FALSE
y
results="hide"
).
Redondear puede generar diferencias en el resultado en tales
situaciones. Es posible que desees 2.0
,
peroround (2.03, 1)
resultará solo2
.
La función myround
en el paquete R/broman maneja
esi.
Desafío
Prueba un poco de código R en línea.
Otras opciones de salida
También puedes convertir R Markdown en un documento
PDF o Word. Haz clic en el pequeño
triángulo junto al botón “Knit HTML” para obtener un
menú desplegable. O podrías poner
pdf_document
o
word_document
en el encabezado del
archivo.
Recursos
Puntos Clave
- Informes mixtos escritos en R Markdown usando un programa escrito en R.
- Especificar opciones de fragmento para controlar el formateo.
- Usar
knitr
para convertir estos documentos en PDF y en otros formatos.