Guía hiper-básica a RMarkdown

Antes de empezar: ¿Markdown?

RMarkdown es un derivado de otro lenguaje que se llama Markdown. Básicamente, Markdown es un lenguaje de preprocesamiento de HTML: esto significa que vos escribís en Markdown algo que se puede procesar como HTML (HTML es el lenguaje en el cual se escriben los sitios web, por ejemplo). La sintaxis de Markdown permite especificar cuestiones básicas de formato como cursivas, negritas, títulos de distinto tamaño, imágenes, links, listas con viñetas o listas numeradas y fragmentos de código ejecutable. De cierta forma, escribir un archivo con markdown no es muy distinto a escribir un archivo en Word, por ejemplo, y después aplicarle un formato particular. La diferencia es que en Word lo aplicás a través de la interfaz gráfica (es decir, a través del programa Word y sus bellos botoncitos) y en markdown lo marcás con una sintaxis particular.

Por ejemplo, el párrafo anterior se ve de la siguiente forma antes de ser procesado:

El título está marcado con dos ##: un solo símbolo marca el título más grande (llamado H1); mientras más símbolos, más abajo en la jerarquía de títulos. Luego, los links tienen una doble estructura: la palabra que queremos linkear entre corchetes y luego el link de destino entre paréntesis. Finalmente, los asteriscos se usan para marcar las cursivas y las negritas. Como habrán visto, Markdown es un lenguaje muy sencillo y está pensado para que sea fácil de leer.

R + Markdown

No hay que ser una luminaria para entender, ahora, que RMarkdown es una versión de Markdown que se puede usar con R. Se trata de un tipo de archivo donde podemos escribir texto con formato (es decir, embellecerlo con cursivas, negritas, títulos, tablas, referencias bibliográficas, imágenes; todo lo que harías en un documento de Word) y además podés agregar código ejecutable y mostrar los resultados. Ese documento además se puede procesar como un html (si querés subirlo a un blog), como pdf o como Word.

Todo esto facilita la reproducibilidad: la posibilidad de volver a correr un mismo análisis y obtener (o no) los mismos resultados. En general se tiende a pensar la reproducibilidad como algo importante entre investigadores: Pepito corre una investigación y encuentra X resultado; si Fulanita corre el mismo análisis con la misma base de datos, debería obtener el mismo resultado (si es que Pepito fue un investigador sensato y transparente). Sin embargo, la reproducibilidad también es importante intra investigadores: varias veces nos encontramos en la necesidad de volver a correr nuestros mismos análisis, ya sea porque encontramos un error o porque modificamos la cantidad original de datos. Si el código de nuestro análisis está limpio y ordenado, solo tendremos que reemplazar la dirección del archivo de nuestra base de datos y no tocar nada más.

Antes de empezar, tenemos que instalar dos paquetes: knitr, que sirve para construir los archivos, y rmarkdown, que es el paquete que permite crear los archivos RMarkdown. El código para instalarlos es el siguiente:

install.packages(c("knitr", "rmarkdown"))

A diferencia de otros paquetes, estos no necesitan ser cargados (con la función library()) cada vez que los vamos a usar, así que una vez que los instales ya podés olvidarte de ellos.

Ahora sí, manos a la obra. RMarkdown es un tipo de archivo, por lo tanto para generarlo vamos a File > New File > RMarkdown, o desde el cuadradito blanco con un botón de + de color verde. Cuando lo abras te va a aparecer lo siguiente:

Todo lo que te aparece acá lo podés cambiar más adelante, así que mi sugerencia es que no sobrecargues tu memoria de trabajo y toques directamente Ok. De todos modos, ya podés empezar a ver lo que te mencioné antes: a partir de un RMarkdown podés exportar o convertir tu archivo a html, a pdf o a word. Se pueden crear documentos, que es lo que vamos a hacer, pero también se pueden crear Presentaciones tipo PowerPoint, aplicaciones web con un paquete llamado Shiny, y también podés cargar tus propias plantillas de formato. Pero por el momento, nos quedamos con un documento básico.

Luego de apretar Ok, se abre el documento RMarkdown con una plantilla, es decir, un modelo prefabricado con algunas marcas propias de Markdown. Hay tres grandes tipos de información importante:

1. El primer segmento de las primeras líneas, encerrado entre guiones (---). Se le llama bloque de código YAML y es donde se va a setear la configuración general del documento. Allí aparece por default la información que elegimos en la pantalla anterior, pero podemos también editarlo a mano para agregar otras cosas (como un subtítulo, por ejemplo). El formato YAML es muy sencillo: palabras seguidas por dos puntos.

   

   Imagen del fragmento YAML

2. El segundo segmento importante van a ser los bloques de código y los identificás porque empiezan con tres tildes invertidas (o tildes graves, para el francés) ``` y porque aparece en gris. La línea entre llaves {} contiene la información sobre cómo se tiene que ejecutar ese bloque de código. A estos bloques de código se los llama chunk y podés agregar más bloques con Code > Insert chunk o el atajo de teclado que te muestre.

   

   Imagen del chunk de código en R.

3. Finalmente, todo lo que está por fuera de esos bloques de código es el texto plano, es decir, el texto que podemos editar en Markdown para darle un formato de la misma forma en que trabajamos con un documento de Word.

   

   Imagen del fragmento de texto predeterminado.

Y antes de ver un poco más cómo podemos aprovechar esto, quiero que veas la magia de RMarkdown: hacé click en el botón de Knit que está en el menú justo arriba del documento. Te va a pedir que le pongas nombre al archivo, luego en la consola van a aparecer cosas raras y finalmente, en el panel del visor abajo a la derecha, vas a tener una previsualización de cómo se vería ese documento con el formato aplicado. Justamente, knit significa tejer en inglés: lo que hace es tejer el texto que creamos con el lenguaje markdown y lo convierte en un archivo html.

¿Y ahora?

Ahora, mi sugerencia es que pruebes modificando esta plantilla a ver qué pasa. El modelo usa el dataframe cars, pero podés incorporar el fragmento de código que prefieras. Podés encontrar más información sobre cómo customizar el texto en esta guía de RStudio. En el próximo post vamos a ver cómo podemos customizar un documento de RMarkdown, es decir, cómo podemos controlar qué se muestra y qué no, de qué forma exportarlo y otras cosas más.

Como siempre, recordá que podés suscribirte a mi blog para no perderte ninguna actualización, y si te quedó alguna consulta no dudes en contactarme. Y, si te gusta lo que hago, podés invitarme un cafecito desde Argentina o un kofi.