1 Qué es RMarkdown

(Para profundizar contenidos de este curso, o aprender otros aspectos no incluidos, sugerimos tener en cuenta este tutorial de RMarkdown).

De acuerdo a Wikipedia:

Markdown es un lenguaje de marcado ligero creado por John Gruber que trata de conseguir la máxima legibilidad y facilidad de publicación tanto en su forma de entrada como de salida, inspirándose en muchas convenciones existentes para marcar mensajes de correo electrónico usando texto plano.

2 Por qué usar RMarkdown?

Por que es:

Brevemente, los usuarios normales lo encontrarán útil en cualquier caso, especialmente cuando necesitas algo mejor que el texto plano pero menos funcional que MS Word. Para desarrolladores, si tienes pereza de escribir código HTML, amarás Markdown. Más aún, Github y muchos sitios favorecen markdown para archivos README en proyectos. Eso significa que necesitarás Markdown en tu vida de una manera u otra.

3 Cómo funciona

Los archivos rmarkdown son texto plano, con extensión .rmd.

El código se ejecuta clickeando en Knit, en el area de programación. El botón está al lado de la lupa. Se hace click en la flechita de opciones (al lado del ícono) se podrá observar que Knit genera reportes en formato html, pdf o `word.

Knit ejecuta todos los fragmentos de código y crea un nuevo markdown (.md) que incluye el código y su salida.

El archivo .md es luego procesado por pandoc que es responsable de generar el formato final.

Para crear un nuevo .rmd, en RStudio, lo más facil es File -> New File -> R Markdown....

4 Sintaxis

Los documentos .rmd tienen una estrcutura muy simple: 1. Encabezado 2. Cuerpo: en donde se desarrolla todo el documento. 3. Bibliografía o citas finales. (sección opcional).

4.1 Encabezados

Los archivos .rmd deben comenzar con un encabezado que define un conjunto de parámetros del reporte.

Por ejemplo, el siguiente encabezado pertenece al .rmd que genera este html:

---
title: 'Reportes con RMarkdown'
author: "Ignacio Cassol"
date: '2019-04-21'
output:
  html_document: #el output será un html.
    fig_caption: yes
    fig_height: 4
    fig_width: 4.5
    highlight: textmate
    keep_md: yes
    number_sections: yes #que las secciones/subsecciones tengan número
    self_contained: no
    theme: flatly #definición del look&feel del output. 
    toc: yes
    toc_depth: 2
---

4.1.1 Formatos de salidas

el comando output: del encabezado admite dos tipos de documentos: documents y presentations. Listamos los formatos disponibles:

  • beamer_presentation
  • github_document
  • html_document
  • ioslides_presentation
  • latex_document
  • md_document
  • odt_document
  • pdf_document
  • powerpoint_presentation
  • rtf_document
  • slidy_presentation
  • word_document

Dependiendo del formato, cada parámetro tiene sus propias opciones.

4.1.1.1 Sugerencias sobre formatos

Aquí encontrarás los formatos soportados de salida. La galería ejectua utiliza el comando render() para generar la salida. Es una opción válida. Nosotros estamos usando la opción de hacer click sobre el botón “Knit”.

Aquí encontrarás los posibles valores que pueden tomar los parámetros para el formato de salida HTML.

Aquí encontrarás una galería de temas (themes) para los outputs.

Te sugerimos explorar el formato de salida flexdashboard::flex_dashboard, útil para hacer presentaciones que simulan ser una web.

4.2 Cuerpo del .rmd

Luego del encabezado, ya estás en condiciones de comenzar a programar el documento. Para esto, tendrás que conocer la sintáxis básica.

Aquí encontrarás una guía de toda la sintaxis básica de R Markdown.

4.2.1 Secciones/subsecciones

Las secciones se señalan con #:

# Sección 1
## Sección 1.1
### Sección 1.1.1

Y se mostrará:

Sección 1

Sección 1.1

Sección 1.1.1

Las secciones pueden tener asociado un id para que se pueda hacer un link de referencia dentro del documento.

Ejemplo:

Esto es una cabecera con un Id

Enlace a esa cabecera

4.2.2 Listas con bullets:

* Item 1
    * Item 1.1
* Item 2
* Item 3

Y se mostrará:

  • Item 1
    • Item 1.1
  • Item 2
  • Item 3

4.2.3 Listas numeradas:

1. Item 1
2. Item 2
3. Item 3

Y se mostrará:

  1. Item 1
  2. Item 2
  3. Item 3

4.2.4 Estilos de lafuente

El texto en cursiva va decorado de guiones bajos o asteriscos, por ejemplo, _text_ o *texto*. El texto en negrita se programa utilizando un par de asteriscos dobles, por ejemplo, **texto**. Un par de tildes ~ convierte el texto en un subíndice, por ejemplo, H~3~PO~4~ representa H3PO4). Un par de ^ produce un superíndice, por ejemplo, Cu^2+^ produce Cu2+.

Ejemplos:

_text_ -> text

*text* -> text

*text* -> text

*text* -> text

4.2.5 Expresiones matemáticas

Las expresiones matemáticas se escriben con la sintaxis del lenguaje latex entre $. Por ejemplo:

$f(k) = {n \choose k} p^{k} (1-p)^{n-k}$ -> \(f(k) = {n \choose k} p^{k} (1-p)^{n-k}\).

Aquí puedes encontrar una cheat sheet con la sintaxis de Latex.

También se pueden definir entornos matemáticos entre $$. Por ejemplo:

$$X = \begin{bmatrix}1 & x_{1}\\
1 & x_{2}\\
1 & x_{3}
\end{bmatrix}$$

Y se mostrará:

\[X = \begin{bmatrix}1 & x_{1}\\ 1 & x_{2}\\ 1 & x_{3} \end{bmatrix}\]

4.3 Pestañas

Es posible organizar contenidos en pestañas como el siguiente ejemplo:

Esto se realiza agregando el atributo {.tabset} a una sección o subsección.

Por ejemplo:

## Quarterly Results {.tabset} 

### By Product

(tab content)

### By Region

(tab content)

Y se mostrará:

Quarterly Results

By Product

(tab content 1)

By Region

(tab content 2)

Es posible modificar el aspecto y el comportamiento de la sección de pestañas. El atributo .tabset-fade apaga/enciende el bloque seleccionado/deseleccionado. Y el atributo .tabset-pills le da formato de botones a las pestañas.

Por ejemplo:

Quarterly Results

By Product

(tab content 1)

By Region

(tab content 2)

4.3.1 Instrucciones varias

  1. Para marcar el texto como código en programación, usa un par de comillas invertidas, por ejemplo, `código` -> código.

  2. Los hipervínculos se crean utilizando la sintaxis [texto](enlace), por ejemplo, [RStudio](https://www.rstudio.com).

  3. La sintaxis de las imágenes es similar: sólo agrega un signo de exclamación, por ejemplo,![Texto alternativo o título de la imagen](ruta/a/imagen).

  4. Las notas al pie se colocan dentro de los corchetes después de ^[], por ejemplo, ^[Esta es una nota al pie.].

  5. Las líneas horizontales se generan con tres caracteres seguidos de -, * o _.

4.4 Bloques de código

Para los desarrolladores, este servicio es de mucha importancia. En R Markdown se pueden copiar partes de código de muchos lenguajes y setear su ejecución. Los bloques de código deberán estar decoradas con ```{} …código… ```.

Los bloques de código -según el seteo que se realice en el header del bloque- se ejecutan en el momento en que se compila el .rmd.

Hay muchas cosas que puede hacer en un bloque de código: puede producir salida de texto, tablas o gráficos. Tendrás un control preciso sobre todas estas salidas a través de las opciones que se pueden setear dentro de los corchetes. Por ejemplo, puede elegir ocultar la salida de texto a través de la opción results = 'hide', o configurar la altura de una imagen insertada en 4 pulgadas a través de fig.height = 4. Las opciones deben estar separadas por comas, por ejemplo:

```{r, chunk-label, results=‘hide’, fig.height=4}

```

En el ejemplo anterior, el bloque de código recibió el nombre chunk-label.

Hay una gran variedad de opciones de configuración de los bloques de código. Además, combinados, ofrecen muchas más posibilidades. Aquí puedes ver algunas descripciones.

Esas opciones de salida se pueden personalizar indicando parámetros dentro del encabezado del bloque, que está entre {} Destacamos 5 argumentos:

  • include = FALSE evita que el código y los resultados aparezcan en el archivo finalizado. R Markdown aún ejecuta el código en el fragmento y los resultados pueden ser utilizados por otros fragmentos.
  • echo = FALSE evita que el código, pero no los resultados, aparezcan en el archivo finalizado. Esta es una manera útil de incrustar figuras.
  • message = FALSE evita que los mensajes generados por el código aparezcan en el archivo finalizado.
  • warning = FALSE evita que las advertencias generadas por el código aparezcan en el final.
  • fig.cap = "..." agrega un título a los resultados gráficos.

Aquí puede ver qué lenguajes soporta RMarkdown.

4.5 Tablas

En .rmd las tablas se escrbien de esta manera:

| Distribución      | Nombre en R |   | Distribución  | Nombre en R |
|-------------------|-------------|---|---------------|-------------|
| Binomial          | binom       |   | Uniforme      | unif        |
| Poisson           | pois        |   | Normal        | norm        |
| Geométrica        | geom        |   | t Student     | t           |
| Hipergeométrica   | hyper       |   | F Fisher      | F           |
| Binomial Negativa | nbinom      |   | Chi-Cuadrado  | chisq       |
|                   |             |   | Exponencial   | exp         |
|                   |             |   | Gamma         | gamma       |
|                   |             |   | Weibull       | weibull     |
|                   |             |   | W de Wilcoxon | wilcox      |

Y se mostrará:

Distribución Nombre en R Distribución Nombre en R
Binomial binom Uniforme unif
Poisson pois Normal norm
Geométrica geom t Student t
Hipergeométrica hyper F Fisher F
Binomial Negativa nbinom Chi-Cuadrado chisq
Exponencial exp
Gamma gamma
Weibull weibull
W de Wilcoxon wilcox

Hay diferentes páginas web que permiten generar tablas para .rmd:

  • Markdown Table Generator: pegando tablas de excel o archivos csv, genera el texto para copiar/pegar en RMarkdown.

  • Tables Generator: permite diseñar tablas con un editor propio y generar código para diferentes lenguajes: Latex, tablas HTML, Rmarkdown entre otras.

4.5.1 El paquete kable

Una de las maneras más simples de administrar tablas en RMarkdown es con el paquete kable.

Por ejemplo:

library(kableExtra)
knitr::kable(iris[1:5, ], caption = 'A caption')
A caption
Sepal.Length Sepal.Width Petal.Length Petal.Width Species
5.1 3.5 1.4 0.2 setosa
4.9 3.0 1.4 0.2 setosa
4.7 3.2 1.3 0.2 setosa
4.6 3.1 1.5 0.2 setosa
5.0 3.6 1.4 0.2 setosa

Aquí encontrarás excelente tutorial para aprovechar todas las potencialidades de kable.

4.5.2 El paquete datatable

Otra opción, para hacer tablas, es utilizando el paquete DT.

Ejemplo:

library(DT)
datatable(mtcars, rownames = FALSE, filter="top", options = list(pageLength = 5, scrollX=T) )

Aquí puedes encontrar un tutorial que muestras las potencialidades de DT.

5 Otros formatos de salida

La sintaxis vista hasta ahora es para generar archivos HTML ya que así lo indicamos en la cabecera a través de la instrucción

output: 
  html_document:
  ...

En esta sección presentaremos muy brevemente otros formatos de salida:

5.1 Presentaciones slidy

Para conocer esta manera de presentar la salida, abre un nuevo documento RMarkdown, pega y ejecuta el siguiente código:

---
title: "Habits"
author: John Doe
date: March 22, 2005
output: slidy_presentation
---

# In the morning

## Getting up

- Turn off alarm
- Get out of bed

## Breakfast

- Eat eggs
- Drink coffee

# In the evening

## Dinner

- Eat spaghetti
- Drink wine

---

<!-- ```{r, cars, fig.cap="A scatterplot.", echo=FALSE} -->
plot(cars)
<!--```

## Going to sleep

- Get in bed
- Count sheep

5.2 Presentaciones revealjs

Primero deberás instalar el paquete:

install.packages("revealjs")
library("revealjs")

Una vez instalado el paquete, abre un nuevo documento RMarkdown, pega y ejecuta el siguiente código:

---
title: "Habits"
author: John Doe
date: March 22, 2005
output: revealjs::revealjs_presentation
---

# In the morning

## Getting up

- Turn off alarm
- Get out of bed

## Breakfast

- Eat eggs
- Drink coffee

# In the evening

## Dinner

- Eat spaghetti
- Drink wine

## Going to sleep

- Get in bed
- Count sheep

5.3 Tutoriales interactivos

Recomendamos que pruebes el paquete learnr, que tiene una gran potencialidad y facilidad para crear tutoriales interactivos. No es la finalidad de este curso, explicar su funcionamiento pero destacamos que, con learnr es posible:

  • Pedir que el usuario ingrese código y que lo pueda ejecutar en el momento.
  • Avanzar, pregunta a pregunta.
  • Hacer quiz.
  • Mostrar videos (de Youtube o Vimeo).
  • Incluir componentes Shiny.

Aquí puedes encontrar un excelente tutorial de learnr. Te sugerimos ver, este ejemplo.

6 R Markdown Cheatsheet

Aquí puedes encontrar un resumen y esquema de RMarkdown, para facilitar la programación.