18  Prueba de R Markdown

Crearemos un documento R Markdown y lo representaremos en HTML. Analizamos cómo conservar el archivo Markdown intermedio, las cifras y qué enviar a Git y enviar a GitHub. Si GitHub es el lugar principal, renderizamos directamente en rebajas con sabor a GitHub y nunca creamos HTML.

Aquí está la documentación oficial de R Markdown: http://rmarkdown.rstudio.com

18.1 Hola Mundo

Practicaremos con el documento estándar R Markdown de RStudio.

Inicie RStudio en un proyecto que sea un repositorio de Git que esté conectado a un repositorio de GitHub.

Aquí estamos modelando “caminar antes de correr”. Es mejor aumentar la complejidad en pequeños incrementos. Probamos la capacidad de nuestro sistema para representar el “hola mundo” de los documentos de R Markdown antes de enturbiar las aguas con nuestros documentos, que probablemente tienen errores.

Haz esto: File > New File > R Markdown …

  • Ponle un título informativo. Esto aparecerá en el documento pero no necesariamente tiene nada que ver con el nombre del archivo. ¡Pero el título y el nombre del archivo deberían estar relacionados! ¿Por qué confundirse? El título es para ojos humanos, por lo que puede contener espacios y puntuación. El nombre del archivo es para humanos y computadoras, por lo que debe tener palabras similares, pero sin espacios ni puntuación.
  • Acepte el Autor predeterminado o edítelo si lo desea.
  • Acepte el formato de salida predeterminado de HTML.
  • Haga clic en Aceptar.

Guarde este documento en un nombre de archivo y ubicación razonables. El nombre del archivo debe terminar en .Rmd o .rmd. Guarde en el nivel superior de este proyecto RStudio y en el repositorio Git, que también es el directorio de trabajo actual. Confía en mí y hazlo por un tiempo.

Quizás quieras realizar un commit en este punto. Eso te ayudará a ver exactamente qué está sucediendo con tus archivos, porque aparecerá como una “diferencia” en el panel de Git. Hacer que los cambios sean muy visibles es uno de los grandes beneficios de usar Git.

Haga clic en “Knit HTML” o haga File > Knit Document. RStudio debería mostrar una vista previa del HTML resultante. Mire también el explorador de archivos. Debería ver el documento original de R Markdown, es decir, foo.Rmd Y el HTML resultante foo.html.

Felicitaciones, acaba de realizar su primer informe reproducible con R Markdown.

Este es otro buen momento para realizar cambios.

18.2 Enviar a GitHub

Envíe el estado actual a GitHub.

Ve a visitarlo en el navegador.

¿Ves los nuevos archivos? ¿Un documento R Markdown y el HTML asociado? Visita ambos en el navegador. Verifica esto:

  • Rmd es bastante legible. Pero el resultado obviamente no está ahí.
  • HTML es feo.

18.3 Formato de salida

¿Realmente quieres HTML? ¿Solo quieres HTML? ¿Estás absolutamente seguro? Si es así, ¡puedes saltarte este paso!

El proceso mágico que convierte tu R Markdown en HTML es el siguiente:

foo.Rmd --> foo.md --> foo.html

Tenga en cuenta el markdow, foo.md. De forma predeterminada, RStudio descarta esto, ¡pero es posible que desees conservar ese archivo markdow!

¿Por qué? GitHub brinda un tratamiento muy especial a los archivos markdow. Se representan casi como HTML. Esto es genial porque conserva todos los encantos del texto plano, pero te ofrece una pseudopágina web gratuita cuando visitas el archivo en el navegador. Por el contrario, HTML se representa como texto sin formato en GitHub y tendrás que tomar medidas especiales para verlo como deseas.

En muchos casos, solo deseas el markdown. En ese caso, cambiamos el formato de salida a github_document. Esto significa que el renderizado se verá así:

foo.Rmd --> foo.md

donde foo.md es un markdown con sabor a GitHub. Si aún desea el HTML pero también el markdown intermedia, también hay una manera de solicitarlo.

Este punto que estamos señalando sobre la importancia de los archivos .md es la razón por la que tantos paquetes R tienen un archivo NEWS.md y README.md, a menudo generados a partir de README.Rmd.

El formato de salida es una de las muchas cosas que podemos controlar en la parte frontal YAML de los documentos .Rmd, es decir, el texto en la parte superior de su archivo entre las líneas iniciales y finales de ---.

Puede realizar algunos cambios en YAML a través del IDE de RStudio: haga clic en el “engranaje” en la barra superior del editor de código fuente, cerca del botón “Knit HTML”. Seleccione “Opciones de salida”, vaya a la pestaña Avanzado y marque “Mantener archivo markdown”. Su YAML ahora debería parecerse más a esto:

---
title: "Something fascinating"
author: "Jenny Bryan"
date: "`r format(Sys.Date())`"
output:
  html_document:
    keep_md: true
---

Deberías haber obtenido la línea keep_md: true. También puedes simplemente editar el archivo tú mismo para lograrlo. El IDE solo expone una pequeña fracción de lo que es posible configurar en YAML.

De hecho, es necesaria una edición manual si desea mantener solo el markdown y obtener un markdown con sabor a GitHub. En ese caso, haz que tu YAML se vea así:

---
title: "Something fascinating"
author: "Jenny Bryan"
date: "`r format(Sys.Date())`"
output: github_document
---

¡Guardar!

Quizás quieras realizar un commit en este punto.

Renderizar mediante el botón “Knit HTML”.

Ahora vuelva a visitar el explorador de archivos. Además de foo.Rmd, ahora deberías ver foo.md. Si hay fragmentos de R que forman figuras, el uso de formatos de salida de rebajas también hará que esos archivos de figuras queden en un subdirectorio con un nombre sensato, como foo_files.

Si confirma y presiona foo.md y todo lo que está dentro de foo_files, cualquiera que tenga permiso para ver su repositorio de GitHub podrá ver una versión decente de su informe.

Si su formato de salida es html_document, aún debería ver foo.html. Si su formato de salida es github_document y ve foo.html, eso es un resto de experimentos anteriores. Borra eso. Sólo te confundirá más tarde.

Quizás quieras realizar un commit aquí.

18.4 Enviar a GitHub

Envíe el estado actual a GitHub.

Ve a visitarlo en el navegador.

¿Ves las modificaciones y los nuevos archivos? Su .Rmd debería modificarse, es decir, debería ver los cambios que realizó en el frontmatter de YAML. Y debería haber obtenido, al menos, el archivo de rebajas asociado, foo.md.

  • Visite el archivo markdown y compárelo con nuestro HTML anterior.
  • ¿Ves cómo el markdown es mucho más útil directamente en GitHub? Interioriza esta lección.

18.5 Ponle tu sello

Seleccione todo menos el frontmatter YAML y… ¡bórrelo!

Escribe una sola oración.

Inserte un fragmento de R vacío, a través del menú “Chunk” en la parte superior derecha del editor de código fuente o con el método abreviado de teclado correspondiente.

```{r, eval=TRUE}`r ''`
## inserte su brillante código aquí
```

Inserta de 1 a 3 líneas de código funcional que sea relevante para ti o para el proyecto donde estás experimentando. “Recorre” y ejecuta esas líneas usando el botón “Ejecutar” o el método abreviado de teclado correspondiente. ¡DEBES asegurarte de que tu código realmente funcione!

¿Satisfecho? ¡Guarde!

Quizás quieras realizar un commit aquí.

Ahora renderice todo el documento mediante “Knit HTML”. ¡Voilá!

Quizás quieras realziar un commit aquí. Y enviar. Y admire su progreso en GitHub.

18.6 Desarrolla tu informe

De esta manera incremental, desarrolle su informe. Agregue código a este fragmento. Refinelo. Agrega nuevos trozos. Pero siga ejecutando el código “manualmente” para asegurarse de que realmente funcione.

Si el código no funciona, puedo garantizarle que fallará, de una manera más espectacular y críptica, cuando se ejecute con los brazos extendidos a través de “Knit HTML” o rmarkdown::render().

Limpie su espacio de trabajo, reinicie R y vuelva a ejecutar todo periódicamente, si las cosas se ponen raras. Hay muchos elementos de menú fragmentados y atajos de teclado para acelerar este flujo de trabajo. Represente todo el documento con frecuencia para detectar errores cuando sean fáciles de identificar y corregir. Guarde con frecuencia y confirme cada vez que llegue a un punto que desee como posición de “retroceso”.

Pronto desarrollarás tu propio mojo, pero esto debería brindarte tu primera experiencia exitosa con R Markdown.

18.7 Publica tu informe

Si ha estado creando HTML, puede publicarlo en algún lugar de la web, enviarlo por correo electrónico a su colaborador, lo que sea.

Pase lo que pase, técnicamente puedes publicar este informe simplemente enviando una versión renderizada a GitHub. Sin embargo, ciertas prácticas hacen que este esfuerzo de publicación sea más satisfactorio para su audiencia.

Aquí hay dos comportamientos que encuentro muy frustrantes:

  • “Aquí está mi código. He aquí”. Esto es cuando alguien solo publica su fuente, es decir, R Markdown o código R, Y realmente quiere que otras personas aprecien su “producto”. La suposición implícita es que el público objetivo descargará todos los datos y el código y los ejecutará localmente.
  • “Aquí está mi HTML. He aquí”. Esto es cuando alguien acepta la salida predeterminada solo HTML. Recuerde, los humanos no pueden leer los archivos HTML en GitHub. Por lo tanto, la suposición implícita es que el público objetivo descargará el repositorio y apuntará su navegador a este archivo HTML para poder verlo. ¿HTML en GitHub? No es legible por humanos.

A veces es muy poco realista esperar que su audiencia tome las medidas adicionales descritas anteriormente. A menudo, con un cambio muy pequeño por tu parte, puedes crear un artefacto en GitHub que tu público objetivo puede apreciar de inmediato.

Crear, confirmar y enviar markdowns (es decir, archivos .md) es una estrategia de publicación muy funcional y liviana. Utilice output: github_document o, si la salida es html_document, agregue keep_md: true. En ambos casos, es fundamental confirmar y enviar todo lo que esté dentro de foo_files, es decir, cualquier figura que se haya creado. Ahora la gente puede visitar y consumir tu trabajo en GitHub, como cualquier otra página web.

Este es (más o menos) otro ejemplo de un principio generalmente válido, que es mantener las cosas legibles por máquinas y humanos, siempre que sea posible. Al hacer que foo.Rmd esté disponible, otros pueden ver y ejecutar su código real. Al compartir también foo.md y/o foo.html, otros pueden explorar casualmente su producto final y decidir si quieren obtener y ejecutar el código.

18.8 HTML en GitHub

Los archivos HTML, como foo.html, no son útiles de inmediato en GitHub (aunque sus versiones locales se pueden ver fácilmente). Visita uno y verás el HTML sin formato. Qué asco. Pero hay formas de obtener una vista previa: como http://htmlpreview.github.io. Espere mucho dolor con los archivos HTML dentro de repositorios privados (de ahí las recomendaciones anteriores para enfatizar la reducción). Cuando se vuelve vital para todo el mundo ver HTML adecuado en todo su esplendor, es hora de utilizar una estrategia de publicación web más sofisticada.

Tengo más ideas generales sobre cómo hacer que un repositorio de GitHub funcione como un sitio web.

18.9 Solución de problemas

Asegúrese de que RStudio y el paquete rmarkdown (y sus dependencias) estén actualizados. En caso de una falla catastrófica al renderizar el documento estándar de R Markdown, considere que su software puede ser demasiado antiguo. Detalles sobre el sistema utilizado para representar este documento y cómo verificar su configuración:

  • versión rmarkdown r packageVersion("rmarkdown"). Usar packageVersion("rmarkdown") para comprobar el tuyo.
  • r R.version.string. Usar R.version.string para comprobar el tuyo.
  • RStudio IDE 2021.9.0.341 (“Ghost Orchid” Preview). Use RStudio > About RStudio o RStudio.Version()$version para comprobar el tuyo.

Deshazte de tu .Rprofile, por lo menos temporalmente. He descubierto que un .Rprofile “maduro” que se ha acumulado al azar a lo largo de los años puede causar problemas. Específicamente, si tiene algo relacionado con knitr, markdown, rmarkdown o el propio RStudio, es posible que esté impidiendo la instalación o el uso de los beneficios más recientes. Comente todo el archivo o cámbiele el nombre a otro y reinicie o incluso reinstale RStudio.

“Ignoré tu consejo y agregué un montón de código a la vez. Ahora mi Rmd no se procesa.” Si no puedes descubrir qué está mal leyendo los mensajes de error, elige uno:

  • BElimine estos cambios, vuelva a un estado funcional (posiblemente sin código) y restáurelos gradualmente. Ejecute su código de forma interactiva para asegurarse de que funcione. Renderice el documento completo con frecuencia. ¡Confirme después de cada adición exitosa! Cuando vuelvas a introducir el código roto, ahora será parte de un pequeño cambio y la raíz del problema será mucho más fácil de identificar y solucionar.
  • Dígale a knitr que siga adelante, incluso en presencia de errores. Algunos problemas son más fáciles de diagnosticar si puede ejecutar declaraciones R específicas durante el renderizado y dejar más evidencia para el examen forense.

    • Inserta este trozo cerca de la parte superior de tu documento .Rmd:

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

    • Si no es deseable aceptar errores globalmente, aún puedes especificar error = TRUE para un fragmento específico como este:

      ```{r wing-and-a-prayer, error = TRUE}`r ''`
## tu código incompleto va aquí ;)
```
  • Adaptar la estrategia “git bisect”:
    • Coloque knitr::knit_exit() en algún lugar temprano de su documento .Rmd, ya sea en código R en línea o en un fragmento. Continúe moviéndolo antes hasta que todo funcione. Ahora muévalo hacia abajo en el documento. Con el tiempo, podrá limitar la ubicación de su código roto lo suficiente como para encontrar las líneas y solucionarlo.

Consulta tu directorio de trabajo. Te romperá el corazón saber con qué frecuencia tus errores son realmente mundanos y básicos. Pregúntame cómo lo sé. Cuando las cosas van mal, considere:

  • ¿Qué es el directorio de trabajo?
  • ¿Ese archivo que quiero leer/escribir está realmente donde creo que está?

Coloque estos comandos en fragmentos de R para comprobar lo anterior:

  • getwd() mostrará el directorio de trabajo en tiempo de ejecución. Si jugó con el directorio de trabajo con, por ejemplo, el mouse, ¿tal vez esté configurado en un lugar para su desarrollo interactivo y en otro cuando “Knit HTML” se haga cargo?
  • list.files() enumerará los archivos en el directorio de trabajo. ¿El archivo que deseas está ahí?

No intente cambiar el directorio de trabajo dentro de un documento de R Markdown. Simplemente no lo hagas. Ver Preguntas frecuentes sobre knitr #5. Esos es todo.

No tenga prisa por crear una estructura de subdirectorios complicada. RStudio/knitr/rmarkdown (que le ofrece el botón “Knit HTML”) son bastante obstinados acerca de que el directorio de trabajo se establezca en la ubicación archivo .Rmd y sobre todos los archivos que viven juntos en un gran directorio feliz. Todo esto se puede solucionar. Por ejemplo, recomiendo el paquete here para crear rutas de archivos, una vez que necesite subdirectorios. Pero no hagas esto hasta que realmente lo necesites.