Curso
Creación de informes con R Markdown
4 h
46K
En este artículo vamos a explorar un paquete esencial y muy útil de ciencia de datos que todo usuario de R debería conocer: R Markdown. Veremos qué es R Markdown, qué ventajas aporta, para qué se utiliza, cómo instalarlo, qué posibilidades ofrece para trabajar con código, texto y gráficos, qué sintaxis usa, qué formatos de salida admite y cómo compilar estos documentos y compartirlos con tus colaboradores.
Dado que R Markdown está especialmente adaptado al entorno de desarrollo integrado (IDE) RStudio, usaremos este IDE a lo largo del artículo. El tutorial de RStudio te guía en la instalación de RStudio y en cómo empezar a utilizarlo.
¡Vamos allá!
¿Qué es R Markdown?
R Markdown es un paquete gratuito y de código abierto para R que proporciona un espacio de trabajo para crear proyectos de ciencia de datos. Su gran ventaja es que te permite combinar código, texto y visualizaciones de datos en un único documento pulido, compartible y totalmente reproducible, que puede compilarse en una amplia variedad de formatos de salida, tanto estáticos como interactivos.
Algunos de sus formatos de salida más populares son HTML, PDF, Microsoft Word, presentaciones, aplicaciones, sitios web, paneles, informes, plantillas, artículos, libros, etc.
Además, R Markdown permite un seguimiento sencillo del control de versiones y es compatible con muchos lenguajes de programación además de R, como Python y SQL.
Si quieres profundizar en la creación de informes dinámicos con R Markdown, el curso Reporting with R Markdown es un excelente punto de partida.
Instalar R Markdown
Si utilizas R Markdown fuera de RStudio, se instala igual que cualquier otro paquete de R desde el repositorio CRAN (Comprehensive R Archive Network):
install.packages("rmarkdown")Tras la instalación, hay que cargar el paquete en el entorno de trabajo de R:
library(rmarkdown)En cambio, cuando trabajamos con R Markdown dentro de RStudio —que es lo que haremos en este tutorial— no es necesario instalar y cargar explícitamente el paquete rmarkdown. Si haces clic en File — New File — R Markdown en la barra de menús de RStudio, se abrirá un nuevo documento de R Markdown. En ese momento puede aparecer una notificación Install Required Packages, como esta:
Tras confirmar la instalación de los paquetes necesarios, en la ventana emergente que aparece escribe el título del documento y el nombre del autor (ambos opcionales pero recomendables), deja el resto de opciones tal cual y pulsa OK:
Documento predeterminado de R Markdown
En la sección anterior abrimos un nuevo documento de R Markdown en RStudio. Tiene este aspecto:
Incluye el título, el nombre del autor, la fecha actual y el formato de salida predeterminado que proporcionamos en la ventana emergente al crearlo. Después, aparecen algunos ejemplos de la sintaxis básica de R Markdown: cómo añadir y formatear bloques de código, añadir encabezados, insertar enlaces, enfatizar texto y generar gráficos.
A continuación veremos con más detalle varias funciones de R Markdown y su sintaxis. Por ahora, vamos a guardar este archivo por defecto y luego a compilarlo en el formato de salida seleccionado (en nuestro caso, HTML) para ver cómo queda.
Para guardar el archivo, haz clic en File — Save As... en la barra de menús de RStudio.
NOTA: el nombre del documento R Markdown que introdujimos antes no es lo mismo que el nombre del archivo. Debes guardar el archivo en el directorio del proyecto y, mientras trabajas, guardarlo periódicamente (File — Save).
Para compilar el archivo guardado en el formato de salida elegido (HTML), pulsa Knit en la barra de herramientas del archivo:
Así se ve nuestro documento de R Markdown por defecto en formato HTML:
Formato de texto en R Markdown
A menudo, el texto constituye la mayor parte de un proyecto de ciencia de datos. Por eso es importante saber cómo formatearlo en R Markdown para que sea fácil de leer, eficaz y convincente.
Si quieres aprender a usar R para análisis de datos y ciencia de datos y llevar tus habilidades de programación en R y de ciencia de datos al siguiente nivel, echa un vistazo a estos itinerarios de aprendizaje para principiantes y muy completos:
Encabezados
Podemos añadir distintos niveles de encabezado a un documento de R Markdown usando el símbolo almohadilla (#). La sintaxis es:
# Encabezado 1 (título principal)
## Encabezado 2 (sección)
### Encabezado 3 (subsección)
etc.
Al compilar, los encabezados anteriores se verán así:
Énfasis de texto
R Markdown permite añadir distintos tipos de énfasis al texto, como cursiva, negrita, tachado, superíndice o subíndice, de la siguiente manera:
- *italic* o _italic_
- **bold** o __bold__
- ~~strikethrough~~
- text^superscript^
- text~subscript~
A continuación se muestra cómo aparecen estos énfasis tras compilar:
Listas
Para crear una lista sin ordenar, podemos usar cualquiera de estas tres sintaxis:
* Item 1* Item 2* Item 3
o:
- Item 1- Item 2- Item 3
o:
+ Item 1+ Item 2+ Item 3
En todos los casos, el resultado tras compilar será el mismo:
Para crear una lista ordenada, usamos esta sintaxis:
1. Item 12. Item 23. Item 3
El resultado compilado será prácticamente igual, con una sangría delante de cada número.
Ten en cuenta que si eliminas un elemento de una lista ordenada, añades uno nuevo o te equivocas en algún número (por ejemplo, si escribes 20. en lugar de 2. en el ejemplo anterior), la numeración se corregirá automáticamente y se mostrará como corresponde:
Citas en bloque
Para las citas en bloque usamos el símbolo > antes del primer carácter del texto a citar:
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam hendrerit nisi sed sollicitudin pellentesque. Nunc posuere purus rhoncus pulvinar aliquam. Ut aliquet tristique nisl vitae volutpat. Nulla aliquet porttitor venenatis. Donec a dui et dui fringilla consectetur id nec massa. Aliquam erat volutpat. Sed ut dui ut lacus dictum fermentum vel tincidunt neque.
Se compilará así:
Añadimos una línea en blanco tras la cita en bloque para cerrar el formato.
Enlaces
Si quieres incluir un enlace como ruta directa, coloca la URL entre los símbolos < y >. Por ejemplo, la siguiente construcción:
se compilará como:
Si prefieres anclar un enlace a una palabra o a un fragmento breve de texto, usa la siguiente sintaxis (de nuevo con Google como ejemplo):
[Google](https://www.google.com/)
Esto se compilará como:
Imágenes
Para insertar una imagen en el texto, utiliza uno de estos enfoques:
- Si quieres añadir una imagen desde Internet:
- Si el archivo de imagen está guardado en la carpeta del proyecto donde está tu documento de R Markdown:
- Si el archivo de imagen está guardado en tu ordenador pero fuera de la carpeta del proyecto:
El texto alternativo describe brevemente qué aparece en la imagen y se muestra cuando el usuario no puede verla por cualquier motivo.
Veamos el primer enfoque con una imagen de Pixabay, cuya URL es https://cdn.pixabay.com/photo/2018/12/02/10/07/web-3850917_1280.jpg:
Al compilar el documento, la imagen se mostrará:
Saltos
En R Markdown hay varios tipos de saltos:
- Salto de línea: para empezar una línea nueva. Se implementa terminando la línea anterior con una barra invertida (\).
- Salto de párrafo: para empezar un párrafo nuevo. Se implementa añadiendo dos espacios al final del párrafo anterior.
- Salto de diapositiva: para empezar una diapositiva nueva en formatos de salida basados en diapositivas (presentaciones) o una sección nueva en el resto de formatos. Se implementa insertando una regla horizontal (***) en el documento.
- Salto de página: para comenzar una página nueva en los formatos donde aplique, por ejemplo en Microsoft Word. Se implementa insertando el comando \newpage en el documento.
Vamos a poner en práctica los tres primeros tipos de saltos. Debajo tienes un fragmento de Lorem ipsum con algunos símbolos de formato de R Markdown añadidos:
Lorem ipsum dolor sit amet, consectetur adipiscing elit.\Nam hendrerit nisi sed sollicitudin pellentesque.
Nunc posuere purus rhoncus pulvinar aliquam.
***
Ut aliquet tristique nisl vitae volutpat.
Así se compilará en un documento HTML:
Lorem ipsum dolor sit amet, consectetur adipiscing elit.Nam hendrerit nisi sed sollicitudin pellentesque.
Nunc posuere purus rhoncus pulvinar aliquam.
Ut aliquet tristique nisl vitae volutpat.
Formateo y ejecución de código en R Markdown
El código es otro componente esencial de cualquier proyecto de ciencia de datos. En R Markdown podemos ejecutar código (y no solo en el lenguaje R), mostrar el código y su salida, mostrar solo el código y ocultar su salida, mostrar solo la salida y ocultar el código fuente, etc.
El itinerario de carrera para principiantes R Programmer y el itinerario de habilidades R Programming son recursos muy útiles para aprender, practicar y afinar tus competencias de código en R.
Bloques de código
Para formatear y ejecutar un bloque de código de R en R Markdown, lo encerramos entre un par de triples acentos invertidos, con los primeros seguidos de una r entre llaves. Por ejemplo:
```{r}
print("Hello, World!")
```Si compilamos el documento sin ejecutar el código, el bloque se verá así:
Lenguaje de código
Al trabajar con R Markdown no estamos limitados a R, ya que el paquete admite muchos otros lenguajes. Para ejecutar código en otro lenguaje, indicamos su nombre en las llaves en lugar de R. Además, puede que necesitemos instalar y cargar paquetes adicionales en el entorno de R.
Por ejemplo, para poder usar Python en R Markdown, hay que instalar y cargar el paquete reticulate, que permite la comunicación en ambos sentidos (crear y acceder a variables) entre Python y R en el mismo documento.
Reescribamos el fragmento del ejemplo anterior en Python (después de instalar y cargar reticulate):
```{python}
print("Hello, World!")
```
Ejecución de bloques de código
Para ejecutar un bloque de código o las líneas seleccionadas cuando trabajas con R Markdown en RStudio, haz clic en el botón Run de la barra de herramientas del documento y elige la opción necesaria en el menú desplegable:
En la imagen anterior verás que cada opción de ejecución tiene su propio atajo de teclado, que puedes usar sin abrir el desplegable cada vez.
Nombrar bloques de código
Aunque no es obligatorio, es buena práctica nombrar los bloques de código. Puede resultar útil para referenciarlos a lo largo del documento, depurar, cambiar entre bloques, etc. Poner nombre a los bloques es especialmente importante en documentos largos con muchos bloques.
Añadimos el nombre entre llaves, justo después del nombre del lenguaje y separado por un espacio en blanco. El nombre no debe contener espacios.
En el ejemplo siguiente, añadimos el nombre hello_world al bloque:
```{r hello_world}
print("Hello, World!")
```Opciones de los bloques de código
Las opciones de bloque nos permiten controlar la evaluación del código, la salida, la decoración, la caché, la animación (si aplica) y los gráficos (si aplica), todo ello para cada bloque individual. Podemos añadir varias opciones al mismo bloque. En cuanto a la sintaxis, colocamos las opciones entre llaves justo después del nombre del bloque (si lo hay; en caso contrario, tras el nombre del lenguaje), separadas por comas.
R Markdown ofrece muchas opciones. Cada una tiene un valor por defecto, pero cuando decidimos usarlas normalmente queremos un valor distinto. Veamos algunas de las más populares y los valores que pueden interesarte:
echo=FALSE— el código no se mostrará en el documento final, solo su salida.eval=FALSE— el código del bloque no se ejecutará.include=FALSE— el bloque se ejecutará pero no se incluirá en el documento final.results— el valor por defecto es "markup"; otros valores son:- "hide" — la salida del código se ocultará en el documento final
- "hold" — la salida del código se mostrará con retraso, solo cuando se ejecute todo el bloque
- "asis" — la salida del código se pasará tal cual, sin reformatear.
message=FALSE— no se mostrarán los mensajes producidos por el código.error=FALSE— no se mostrarán los errores producidos por el código.warning=FALSE— no se mostrarán los avisos producidos por el código.highlight=FALSE— el código no se resaltará en el documento final.prompt=TRUE— se añadirá el símbolo > al inicio de cada línea de código mostrada en el documento final.
Aquí tienes algunos ejemplos de bloques que primero se ejecutaron en R Markdown en RStudio y luego se compilaron en el documento final:
Código en R Markdown:
Salida en el documento final:
Código en línea
Con el código en línea podemos insertar pequeñas porciones de código directamente en el texto del documento de R Markdown: se ejecutarán y sus resultados aparecerán incrustados en el texto. La sintaxis del código en línea es r <code>.
Aquí tienes un ejemplo sencillo de texto con código en línea:
There are `r 1+6` colors of the rainbow.
y así es como se muestra en el documento final:
There are 7 colors of the rainbow.
En la práctica, el código en línea se usa para agregar información sobre los datos y ayuda a evitar errores que pueden producirse si insertamos los números manualmente o si los datos cambian.
Gráficos en R Markdown
Generar gráficos en R Markdown implica ejecutar código que produce visualizaciones. Por tanto, todo lo comentado hasta ahora sobre el formateo y la ejecución de código en R Markdown, salvo el código en línea, también aplica aquí. La principal diferencia es que la salida será gráfica y no solo texto o números.
El itinerario de habilidades Data Visualization with R te ayudará a desarrollar las competencias necesarias para analizar y visualizar datos en R y, así, contar mejores historias basadas en datos.
Para personalizar gráficos en R Markdown, igual que en R base, usamos las herramientas de los paquetes de visualización de R, así como la función plot() de R base.
Sin embargo, para controlar el comportamiento de los gráficos en un documento de R Markdown, podemos usar opciones de bloque específicas de visualización. La mayoría son bastante concretas y, por tanto, quedan fuera del alcance de este tutorial introductorio. Veamos algunas opciones básicas útiles al graficar en R Markdown:
fig.show— valor por defecto "asis"; otros valores:- "hide" — los gráficos se generarán pero no se incluirán en el documento final
- "hold" — los gráficos se mostrarán con retraso, solo después de ejecutarse todo el bloque
- "animate" — todos los gráficos del bloque se combinarán en una animación.
fig.width— ancho del gráfico en pulgadas, 7 por defecto.fig.height— alto del gráfico en pulgadas, 7 por defecto.fig.align— alineación de los gráficos en el documento final: "left", "center" o "right".fig.cap— pie de figura como cadena de texto.fig.path— ruta al directorio donde se guardarán los archivos de los gráficos creados por el bloque.fig.ext— extensión de los archivos de gráficos generados por el bloque.
A continuación, algunos ejemplos de bloques específicos para gráficos en R Markdown, con su código fuente y el resultado compilado:
Código en R Markdown:
Salida en el documento final:
Formatos de salida
Hasta ahora solo hemos visto el documento HTML (html_document) como formato de salida. Sin embargo, R Markdown ofrece muchos otros, como Microsoft Word, Microsoft PowerPoint, PDF, cuadernos interactivos de R, paneles, etc.
Por ejemplo, los formatos de salida disponibles en R Markdown para crear documentos incluyen html_document, pdf_document, word_document, github_document, html_notebook, html_vignette, etc. En cambio, para crear presentaciones podemos usar: powerpoint_presentation, ioslides_presentation, slidy_presentation y beamer_presentation.
Para establecer el formato de salida de nuestro documento R Markdown, asignamos el valor correspondiente a la opción output en la cabecera del documento (también llamada cabecera YAML, de yet another markup language). Por ejemplo, en nuestro documento de trabajo el formato de salida es html_document, que también es el formato por defecto en R Markdown:
Para cambiarlo, sustituye html_document por el formato que necesites (pdf_document, word_document, powerpoint_presentation, etc.). Ahora, al pulsar Knit en la barra de herramientas del archivo, el documento se compilará en el formato seleccionado.
Publicar documentos de R Markdown
Para publicar un documento de R Markdown, haz clic en File — Publish en la barra de menús de RStudio y elige dónde quieres publicarlo:
Después, sigue las instrucciones según la opción elegida y pulsa Publish. Tu documento quedará listo para compartirlo con tus colaboradores.
Conclusión
Para cerrar, en este artículo has visto cómo empezar con R Markdown. Primero definimos qué es y para qué se usa. Luego comentamos cómo instalarlo, cómo dar formato al texto y a sus distintos componentes, cómo formatear y ejecutar código, cómo generar gráficos, qué formatos de salida ofrece, cómo compilar un documento en uno de esos formatos y cómo publicarlo para compartirlo con tu equipo.
Para practicar R Markdown, echa un vistazo a nuestro curso Reporting with R Markdown, que te ayudará a extraer información de los datos y a presentar tus hallazgos como PDF, archivo HTML o aplicación Shiny.
Temas
