Generación de documentos con Rmarkdown

Rmarkdown

A partir de la versión 0.98.932 de Rstudio es muy sencillo generar documentos Rmarkdown que combinan texto, imágenes e instrucciones de R, más los resultados que dichas instrucciones produzcan (estos resultados pueden ser simples valores numéricos, tablas o gráficos). Dichos documentos puede exportarse en tres formatos:

html: para ser visualizados a través de navegadores web. Existe la posibilidad de que el documento se exporte como una página web o como una presentación html (similar a Power Point). Las últimas versiones de Rstudio permiten incluso generar sitios web completos, con diferentes páginas enlazadas entre sí.
doc: para ser directamente editados con Microsoft Word o LibreOffice Writer.
pdf: Para esta última opción es preciso que el ordenador del usuario disponga de una instalación válida de LaTeX. LaTeX es un completo (y complejo) sistema de edición de textos de código abierto que puede descargarse libremente para Windows (Miktex), para Mac (Mactex) y para Linux (TexLive, si bien lo habitual es que en los sistemas linux texlive venga ya instalado por defecto).

La clave para combinar texto, código R y gráficos es utilizar la sintaxis Rmarkdown. Esta sintaxis se emplea en un simple documento base que contiene el texto y las instrucciones de R, y que será posteriormente procesado a alguno de los formatos anteriores. La sintaxis Rmarkdown consiste simplemente en una colección de marcas que indican:

Los encabezados de capítulos o subcapítulos.
La presencia de negrillas o cursivas.
Los items de una lista.
El enlace a una página web.
La inserción de una figura.
…

Estas marcas consisten simplemente en asteriscos (*), barras bajas (_), corchetes, comillas, etc., cuyo uso puede verse en el menú de ayuda de Rstudio, dentro de la sección llamada Markdown quick reference. En este enlace es posible descargar una guía en pdf del lenguaje markdown. En este otro enlace podemos ver también un resumen en español del lenguaje markdown.

Historia

La sintaxis Rmarkdown deriva del lenguaje de marcas markdown, creado por John Gruber en 2004 con el objetivo de poder generar páginas web de manera sencilla. Rstudio ha adaptado este lenguaje con la denominación Rmarkdown con el objetivo de integrarlo con R y permitir la generación de documentos científicos. Para ello Rstudio emplea pandoc (John McFarlane, 2006), un conversor universal de formatos de texto, capaz de generar documentos word, pdf o html a partir de un documento de texto con marcas. El paquete de R knitr (Yihui Xie, 2007) es el encargado de hacer la “magia” necesaria para que markdown, R y pandoc interactúen y generen el documento final en el formato deseado por el usuario.

En la práctica el usuario no tiene que preocuparse por como se integran todos estos programas entre sí. De hecho la finalidad última de todas estas tecnologías es que el usuario se ocupe solo de redactar las ideas que quiere recoger en el texto (incluyendo entre dichas ideas los procedimientos estadísticos a aplicar), y es Rstudio el que se encarga de la tarea de formatear y presentar el documento.

Creación de un documento Rmarkdown.

Para crear un documento Rmarkdown en Rstudio basta acceder a File -> New File -> R Markdown:

Nos aparecerá entonces una ventana en la que podemos elegir qué tipo de archivo queremos crear. La opción por defecto es crear un documento de texto en html, word o pdf. Las otras opciones son crear una presentación, un archivo shiny (esta es una clase especial de archivo que permite generar “apps” que se ejecutan a través de un navegador web en un ordenador o dispositivo móvil), o usar una plantilla (template) predefinida. En nuestro caso vamos a elegir la opción por defecto, crear un documento HTML:

Introducimos un título y un autor en las casillas correspondientes y pulsamos OK. Rstudio nos mostrará entonces una plantilla como la de la siguiente imagen:

En esta plantilla podemos distinguir las tres clases de elementos que componen un archivo Rmarkdown:

La cabecera: como vemos, la plantilla comienza con una cabecera limitada por tres guiones (- - -) por encima y por debajo, donde figuran el título del documento, el autor, la fecha y el formato de salida (html en este caso). En esta cabecera se pueden incluir otras instrucciones para especificar otros formatos de salida, el aspecto de la salida (colores, tamaño de letra), etc.

Los chunks: son las cajitas grises que contienen código R. Estas cajas están enmarcadas por tres acentos graves (```)al inicio y al final. En la primera linea de la caja, junto a los tres acentos y entre llaves se puede asignar un nombre a cada chunk, así como diversas opciones sobre el comportamiento del mismo. Así, por ejemplo, la opción echo=TRUE indica que el contenido de chunk se muestra en la salida, y echo=FALSE que no se muestra.

El texto: se escribe directamente en el editor sobre el fondo blanco. Para dar formato al texto se usan una serie de marcas. Así por ejemplo, un hashtag (#) indica que el texto que viene a continuación es un título de primer nivel. Dos hashtags (##) indican un título de segundo nivel. Un texto que se encierre entre parejas de asteriscos (dos asteriscos delante y dos detrás) se muestra en negrilla. Un solo asterisco indica cursivas. En este enlace podemos ver un resumen en español del lenguaje markdown.

Cuando se procesa un documento Rmarkdown:

El texto se formatea de acuerdo con lo que especifican las marcas utilizadas en el mismo.
El código R se ejecuta y realiza los cálculos o gráficos especificados, que se incluyen en el documento de salida en la posición de los chunks correspondientes.

Para procesar el archivo Rmarkdown y generar el documento definitivo basta con pinchar en el botón knit que se encuentra en la parte superior de la ventana de edición de Rstudio:

Si procesamos la plantilla de ejemplo, como resultado obtenemos un documento html como el siguiente:

Como podemos ver, el contenido de este documento html se corresponde con el contenido del documento Rmarkdown original. Podemos ver el título, autor y fecha que hemos puesto, así como el texto que aparece en negrilla, un enlace a una página web y los resultados generados por el código R contenido en los distintos chunks.

Insertar un nuevo chunk

Para insertar un nuevo chunk en nuestro documento Rmarkdown tenemos dos opciones:

Pinchar el icono en la parte superior de la ventana de edición de Rstudio.
Pulsar Alt-Ctrl-I (en Windows y Linux) o Alt-Cmd-I en Mac

Ejecución interactiva del código R.

Como hemos visto, al pinchar el botón knitr se procesa el documento completo. No obstante es posible, desde la misma ventana de edición de Rstudio, ir ejecutando el código R a medida que lo vamos introduciendo en los chunks. Tenemos varias opciones para ello:

Para ejecutar una linea, basta poner el cursor sobre ella y pulsar Ctrl-Enter (en windows y linux), o Cmd-Enter (en Mac).
Para ejecutar varias lineas, basta marcarlas con el ratón y pulsar también Ctrl-Enter (en windows y linux) o Cmd-Enter (en Mac)
Para ejecutar el contenido completo de un chunk basta situar el ratón en cualquier lugar del chunk y pulsar Alt-Ctrl-C (en windows) o Alt-Cmd-Enter (en Mac). De modo alternativo, se puede pulsar el botón triangular verde () de la esquina superior derecha del chunk.
En la parte superior de la ventana de edición de Rstudio se puede pulsar en el botón Run (), que mostrará varias opciones: ejecutar una linea, varias lineas o el chunk completo.

Opciones para Rmarkdown en Rstudio

En Rstudio al lado del botón knit hay una ruedecilla dentada:

que al pulsarla nos despliega un menú de opciones. Podemos elegir:

Si los documentos procesados por knit en html se muestran en una ventana nueva (“Preview in Window”, es la opción por defecto), o en el panel lateral derecho dentro de Rstudio (“Preview in Viewer Pane”).
Si los resultados de ejecutar los chunks de R interactivamente se muestran en la misma ventana de edición donde estamos escribiendo el código (opción Chunk Output Inline), o si se muestran en la consola de Rstudio (opción Chunk Output in Console)
Pinchando en Output Options aparece el menú:

en el que podemos elegir si incluir o no una tabla de contenidos (índice de las distintas secciones del documento), el tipo de coloreado (highlightning) de la sintaxis de R, y el tema global del archivo resultante (el tema especifica el tipo de letra, su tamaño, los colores de los títulos, …)

Más información.

Dentro de Rstudio, en el botón de ayuda (Help) encontramos una sección llamada Markdown quick reference, que ofrece, como su propio nombre indica, una referencia rápida a los códigos más usuales del lenguaje markdown.

En internet pueden encontrarse infinidad de recursos para manejar todas las posibilidades de Rmarkdown. Citamos unos pocos: