Sesión 9 R Markdown

R Markdown es una herramienta para crear documentos que combinan texto, código y resultados. Son totalmente reproducibles y generan documentos de diferentes formatos: PDF, Word, HTML, presentaciones y más.

Un archivo R Markdown es un archivo de texto plano que tiene la extensión .Rmd, en RStudio podemos seleccionar File > New File > R Markdown para generar un machote de un archivo R Markdown.

Básicos de R Markdown

El siguiente es un archivo de tipo R Markdown, es un archivo de texto plano con terminación .Rmd:

---
title: "Ejemplo"
author: "Teresa O."
date: "7/20/2020"
output: html_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

## R Markdown

This is an R Markdown document. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. For more details on using R Markdown see <http://rmarkdown.rstudio.com>.

When you click the **Knit** button a document will be generated that includes both content as well as the output of any embedded R code chunks within the document. You can embed an R code chunk like this:

```{r cars}
summary(cars)
```

## Including Plots

You can also embed plots, for example:

```{r pressure, echo=FALSE}
plot(pressure)
```

Note that the `echo = FALSE` parameter was added to the code chunk to prevent printing of the R code that generated the plot.

Los archivos R Markdown contienen tres tipos de contenido:

  1. Un encabezado YAML (opcional) rodeado de —

  2. Bloques de código de R rodeado de ```.

  3. Texto formateado con lenguaje Markdown (# Encabezado e _itálicas_).

Cuando abres un archivo .Rmd, obtienes una interfaz con el código y el output intercalados. Puedes ejecutar cada bloque de código haciendo clic el ícono de play, o línea por línea como en un script de R usual.

  • Utiliza RStudio para crear un machote de un archivo R Markdown, selecciona tipo de salida HTML. Repite seleccionando PDF, ¿qué cambia en el archivo de texto .Rmd?

Cuando presionas Knit en RStudio, o con código puedes utilizar la función knit knit("ejemplo.Rmd"), se ejecutan todos los bloques de código y se genera un documento markdown (.md) que incluye el código y su output. El archivo markdown es procesado entonces por pandoc que crea el archivo terminado, y pandoc puede crear las diferentes salidas (Word, PDF, HTML) a partir del mismo archivo markdown.

Imagen de https://github.com/hadley/r4ds
Imagen de https://github.com/hadley/r4ds

Markdown

Las secciones de texto de un archivo R Markdown utilizan el lenguaje Markdown, una colección simple de convenciones para dar formato a archivos de texto plano. La guía abajo, tomada de Hadley Wickham and Grolemund (2017), muestra como usar Markdown.

Formato de texto
------------------------------------------------------------

*cursiva*   ó _cursiva_
**negrita**   __negrita__
`code`
superscript^2^ y subscript~2~

Encabezados
------------------------------------------------------------

# Encabezado de primer nivel

## Encabezado de segundo nivel

### Encabezado de tercer nivel

Listas
------------------------------------------------------------

*   Elemento 1 en lista no enumerada

*   Elemento 2

    * Elemento 2a

    * Elemento 2b

1.  Elemento 1 en lista enumerada

1.  Elemento 2. La numeración se incrementa automáticamente en el output.

Enlaces e imágenes
------------------------------------------------------------

<http://ejemplo.com>

[texto del enlace](http://ejemplo.com)

![pie de página opcional](ruta/de/la/imagen.png)

Tablas 
------------------------------------------------------------

Primer encabezado     | Segundo encabezado
--------------------- | ---------------------
Contenido de la celda | Contenido de la celda
Contenido de la celda | Contenido de la celda
  • Crea un documento R Markdown donde describas la ciudad en que naciste, debe incluir al menos:
  1. encabezados de primer y segundo nivel, 2) enlaces, 3) formato de letras negritas o cursivas

Bloques de código

Para agregar código que se ejecutará en un archivo R Markdown se necesita insertar un bloque de código, para ello podemos:

  1. Usar el atajo Cmd/Ctrl + Alt + I

  2. El botón Insert en la barra de edición de RStudio.

  3. Escribir manualmente las comillas y corchetes: ```{r} y ```.

Por otra parte el atajo Cmd/Ctrl + Shift + Enter correrá todo el código del bloque.

  • En el archivo R Markdown que creaste en el ejercicio anterior agrega un bloque de código que filtre la informacion de educación del municipio en que naciste.

  • Agrega un bloque de código que genere una gráfica donde compares tu municipio con el resto de los de tu estado.

library(estcomp)
df_edu
#> # A tibble: 7,371 × 16
#>    state_code municipio_code region state_name   state_abbr municipio_name sex  
#>    <chr>      <chr>          <chr>  <chr>        <chr>      <chr>          <chr>
#>  1 01         001            01001  Aguascalien… AGS        Aguascalientes Total
#>  2 01         001            01001  Aguascalien… AGS        Aguascalientes Homb…
#>  3 01         001            01001  Aguascalien… AGS        Aguascalientes Muje…
#>  4 01         002            01002  Aguascalien… AGS        Asientos       Total
#>  5 01         002            01002  Aguascalien… AGS        Asientos       Homb…
#>  6 01         002            01002  Aguascalien… AGS        Asientos       Muje…
#>  7 01         003            01003  Aguascalien… AGS        Calvillo       Total
#>  8 01         003            01003  Aguascalien… AGS        Calvillo       Homb…
#>  9 01         003            01003  Aguascalien… AGS        Calvillo       Muje…
#> 10 01         004            01004  Aguascalien… AGS        Cosío          Total
#> # ℹ 7,361 more rows
#> # ℹ 9 more variables: pop_15 <dbl>, no_school <dbl>, preschool <dbl>,
#> #   elementary <dbl>, secondary <dbl>, highschool <dbl>, higher_edu <dbl>,
#> #   other <dbl>, schoolyrs <dbl>

Opciones de bloques de código

Los bloques de código pueden tener nombre y se puede pasar opciones a ellos.

  • Nombre del bloque: Se escribe después del identificador de tipo de bloque ```{r nombre-bloque} y sirve para navegar con mayor facilidad los bloques, las gráficas producidas en los bloques tendrán nombres útiles, se puede conjuntar con el uso de caches cuando el código es costoso de ejecutar.

  • Opciones: Los bloques de código se pueden personalizar con parámetros con opciones que se pasan en el encabezado del bloque: ```{r nombre-bloque, echo = FALSE, error = TRUE}. Hay más de 60 opciones (lista completa aquí http://yihui.name/knitr/options/). Entre las usadas más frecuentemente están:

    • eval = FALSE el código no se evaluará. Y por consiguiente tampoco habrá resultados de ese bloque. Esta opción es útil cuando queremos mostrar código ejemplo o deshabilitar un bloque temporalmente.

    • include = FALSE evalúa el código pero no imprime el código ni los resultados.

    • echo = FALSE oculta el código. Esta opción se utiliza para generar reportes reproducibles pero en los que el código no es de interés para el lector.

    • message = FALSE o warning = FALSE elimina los mensajes y alertas del reporte final, por ejemplo, quizá no queremos que se impriman los mensajes al cargar paquetes o unir tablas.

    • results = 'hide' esconde los resultados; fig.show = 'hide' esconde las gráficas.

    • error = TRUE por defecto los reportes de R Markdown genera error y no se crean cuando hay fallas en el código, la opción de error = TRUE permite que el proceso siga ignorando los errores.

    • fig.width = 7, fig.height = 3 se utilizan para ajustar el tamaño de las gráficas.

  • Opciones globales: En ocasiones buscamos modificar las opciones para todos los bloques de nuestro documento, por ejemplo, cuando queremos ocultar el código de todos los bloques, u ocultar todos los mensajes de alerta.

knitr::opts_chunk$set(
  echo = FALSE,
  warning = FALSE
)
  • Agrega nombre a los bloques de código de tu documento R Markdown y experimenta con las opciones que acabamos de revisar.

Tablas

Por defecto, R Markdown imprime data frames tal como se ven en la consola:

filter(df_edu, state_code == "09")
#> # A tibble: 48 × 16
#>    state_code municipio_code region state_name   state_abbr municipio_name sex  
#>    <chr>      <chr>          <chr>  <chr>        <chr>      <chr>          <chr>
#>  1 09         010            09010  Ciudad de M… CDMX       Álvaro Obregón Total
#>  2 09         010            09010  Ciudad de M… CDMX       Álvaro Obregón Homb…
#>  3 09         010            09010  Ciudad de M… CDMX       Álvaro Obregón Muje…
#>  4 09         002            09002  Ciudad de M… CDMX       Azcapotzalco   Total
#>  5 09         002            09002  Ciudad de M… CDMX       Azcapotzalco   Homb…
#>  6 09         002            09002  Ciudad de M… CDMX       Azcapotzalco   Muje…
#>  7 09         014            09014  Ciudad de M… CDMX       Benito Juárez  Total
#>  8 09         014            09014  Ciudad de M… CDMX       Benito Juárez  Homb…
#>  9 09         014            09014  Ciudad de M… CDMX       Benito Juárez  Muje…
#> 10 09         003            09003  Ciudad de M… CDMX       Coyoacán       Total
#> # ℹ 38 more rows
#> # ℹ 9 more variables: pop_15 <dbl>, no_school <dbl>, preschool <dbl>,
#> #   elementary <dbl>, secondary <dbl>, highschool <dbl>, higher_edu <dbl>,
#> #   other <dbl>, schoolyrs <dbl>

Podemos darles formato adicional con la función kable() del paquete knitr.

library(knitr)
filter(df_edu, state_code == "09", sex == "Total") |> 
  select(municipio_name, sex, pop_15, schoolyrs) |> 
  kable()
municipio_name sex pop_15 schoolyrs
Álvaro Obregón Total 597803 10.82800
Azcapotzalco Total 327926 11.17819
Benito Juárez Total 362779 13.81161
Coyoacán Total 506449 12.25350
Cuajimalpa de Morelos Total 154561 11.37112
Cuauhtémoc Total 446045 11.97258
Gustavo A. Madero Total 931274 10.70371
Iztacalco Total 315498 11.31946
Iztapalapa Total 1414880 10.20615
La Magdalena Contreras Total 189468 10.35696
Miguel Hidalgo Total 305043 12.95450
Milpa Alta Total 101038 9.36765
Tláhuac Total 278302 10.14577
Tlalpan Total 533682 11.22496
Venustiano Carranza Total 347026 11.12894
Xochimilco Total 317062 10.42979
  • Agrega una tabla a tu reporte (puedes usar nuevos datos) y usa la función kable() para agregar formato a la tabla.

Código en el texto

En ocasiones deseamos incluir información de los datos directamente en un párrafo, para esto usamos `r `. Por ejemplo:

Tenemos una muestra de `r nrow(sample_2006)` casillas. En las cuales el PAN obtuvo el `r 100 * sum(sample_2006$pan) / sum(sample_2006$total)` % de los votos

Cuando creamos el reporte los cálculos se insertan en el texto:

Tenemos una muestra de 7200 casillas. En las cuales el PAN obtuvo el 35.91703 % de los votos

Para insertar texto la función format() resulta útil pues permite ajustar el número de dígitos en la salida, y que no pase como arriba, también podemos usarla poner comas y mejorar la lectura:

format(12.123893, digits = 3)
#> [1] "12.1"
format(3452345, big.mark = ",")
#> [1] "3,452,345"
  • Agrega código en el texto de tu reporte.

Reportes con parámetros

Los documentos de R Markdown pueden incluir parámetros, esto resulta útil cuando quieres generar varios reportes con distintos valores de entrada, por ejemplo, un reporte por estado de la república, un reporte por trimestre, etc.

En este ejemplo queremos generar un reporte para cada estado:

---
output: html_document
params:
 estado: "01"
---

```{r setup, include=FALSE}
library(tidyverse)
library(estcomp)

codigo_edo <- params$estado
df_edo <- df_edu %>% 
  filter(state_code == codigo_edo)
```

# Estado de `r df_edo$state_name[1]`

```{r plot_ggplot}
df_edu %>% 
  filter(state_code == codigo_edo, sex == "Total") %>% 
  ggplot(aes(x = pop_15, y = schoolyrs)) +
    geom_point() 
```

Como vemos en el ejemplo de arriba los parámetros se acceden como una lista usando la notación params$nombre.

Para generar documentos de R Markdown con parámetros podemos usar la opción Run with Parameters … en el menú del botón Knit, ó producir los reportes con código:

library(rmarkdown)
render("reporte_param.Rmd", params = list(estado = "01"))

Esta segunda opción suele ser más conveniente, tenemos un script desde el que generamos los reportes. Por ejemplo, con la función walk():

parametros <- tibble(
  codigo_edo = unique(df_edu$state_code),
  archivo = stringr::str_c("reporte-edo-", codigo_edo, ".html")
)

walk2(parametros$codigo_edo, parametros$archivo, 
      ~render(input = "rmarkdown/reporte_param.Rmd", params = list(estado = .x), 
              output_file = .y))
  • Crea un script para generar reportes estatales.

9.0.1 Recursos

  • Revisa el acordeón de R Markdown en Help > Cheatsheets > R Markdown Cheatsheet

  • Revisa la guía de referencia de R Markdown en Help > Cheatsheets > R Markdown Reference Guide

  • El libro R Markdown definitive guide escrito por Yihui Xie, J. J. Allaire, Garrett Grolemund es una excelente referencia.

  • Visita la galería de ejemplos en https://rmarkdown.rstudio.com/gallery.html.

Wickham, H. 2019. Advanced r. 2nd ed. Chapman & Hall/CRC the r Series. Chapman; Hall/CRC. https://adv-r.hadley.nz.
Wickham, Hadley. 2009. Ggplot2: Elegant Graphics for Data Analysis. 2nd ed. Springer Publishing Company, Incorporated.
———. 2011. “The Split-Apply-Combine Strategy for Data Analysis.” Journal of Statistical Software 40 (1): 1--29. http://www.jstatsoft.org/v40/i01/.
———. 2014. “Tidy Data.” Journal of Statistical Software, Articles 59 (10): 1–23. https://doi.org/10.18637/jss.v059.i10.
Wickham, Hadley, and Garrett Grolemund. 2017. R for Data Science: Import, Tidy, Transform, Visualize, and Model Data. 1st ed. O’Reilly Media, Inc.
Wilkinson, L., D. Wills, D. Rope, A. Norton, and R. Dubbs. 2005. The Grammar of Graphics. Statistics and Computing. Springer New York. https://books.google.com.mx/books?id=\_kRX4LoFfGQC.

References

Wickham, Hadley, and Garrett Grolemund. 2017. R for Data Science: Import, Tidy, Transform, Visualize, and Model Data. 1st ed. O’Reilly Media, Inc.