19 Ensayo de prueba con R Markdown

Se creará un documento de R Markdown y se convertirá en HTML. Se revisará cómo mantener el archivo de Markdown intermedio, las figuras, y a qué hacerle commit a Git y subir a GitHub. Si GitHub es el lugar principal, se reproducirá directamente a markdown GitHub y nunca se creará el HTML.

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

19.1 Hello World

Se practicará con el documento R Markdown de RStudio.

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

Aquí se está modelando de la forma “caminar antes de correr”. Lo mejor es aumentar la complejidad en pequeños incrementos. Se pone a prueba la capacidad del sistema para hacer el “hola mundo” de los documentos de R Markdown antes de sumergirse en aguas fangosas por propia cuenta, con documentos plagados de errores.

Haga esto: File > New File > R Markdown …

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

Guarde este documento con un nombre de archivo y una ubicación razonables. El nombre de archivo debe terminar en .Rmd o .rmd. Guárdelo en el nivel superior de este proyecto de RStudio y el repositorio de Git, que también es el directorio de trabajo actual. Siga haciendo esto por un tiempo.

Tal vez quiera hacer commit aquí. Así que usted puede ver lo que está a punto de cambiar …

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

Enhorabuena, acaba de hacer su primer informe reproducible con R Markdown.

Tal vez quiera hacer commit aquí.

19.2 Haga push a GitHub

Haga push de los archivos existentes en la ventana emergente de Git a GitHub.

Revise el repositorio en el navegador.

¿Ve los nuevos archivos? ¿Un documento de R Markdown y el HTML asociado? Busque ambos en el navegador. Verifique esto:

  • El Rmd es bastante legible. Pero obviamente la salida no está ahí.
  • El HTML es feo.

19.3 Formato de salida

¿De verdad quiere el HTML? ¿Sólo quiere el HTML? Si es así, ¡puede omitir este paso!

El proceso mágico que convierte R Markdown en HTML es así: foo.Rmd -> foo.md -> foo.html. Tenga en cuenta el markdown intermedio, foo.md. Por defecto, RStudio lo descarta, pero es posible que desee retenerlo.

¿Por qué? GitHub da un tratamiento tan especial a los archivos markdown. Se representan en una forma casi similar a los HTML. Esto es genial porque conserva todos los encantos del texto sin formato, pero le da una forma de pseudo-página web de forma gratuita cuando visita el archivo en el navegador. Por el contrario, HTML se representa como texto sin formato en GitHub y tendrá que tomar medidas especiales para verlo de la manera que quiera.

En muchos casos, solo desea el markdown. En ese caso, se cambia el formato de salida a github_document. Esto significa que el render será foo.Rmd -> foo.md, donde foo.md es un markdown con GitHub. Si todavía desea el HTML pero también el markdown intermedio, hay una forma de solicitarlo también.

El formato de salida es una de las muchas cosas que pueden controlarse en el encabezado YAML - el texto en la parte superior de su archivo entre las líneas delanteras y traseras de ---.

Puede hacer algunos cambios a través del IDE RStudio: haga clic en el “engranaje” en la barra superior del editor de código fuente, cerca del botón “Knit HTML”. Seleccione “Output options” y vaya a la pestaña Opciones avanzadas y marque “Keep markdown source file”. El YAML ahora debe verse más como esto:

Debería haber notado la línea keep_md: true. También puede editar el archivo autónomamente para lograrlo.

De hecho esta edición manual es necesaria si desea mantener sólo markdown y obtener markdown de GitHub. En ese caso, el YAML debe tener este aspecto:

¡Guarde!

Quizás quiera hacer commit aquí.

Compílelo mediante el botón “Knit HTML”.

Vuelva a examinar el explorador de archivos. Además de foo.Rmd, debería ver foo.md. Si hay chunks de R que hacen figuras, el uso de formatos de salida markdown también hará que los archivos de figuras se almacenen en un sub-directorio llamado, foo_files.

Si hace commit y push de foo.md y todo lo que hay dentro de foo_files, entonces cualquier persona con permiso para ver su repositorio GitHub puede ver una versión decente del informe.

Si su formato de salida es html_document, debería ver foo.html. Si su formato de salida es github_document y ve foo.html, eso es sobrante de experimentos anteriores. Suprima eso. Sólo lo confundirá más tarde.

Tal vez quiera hacer commit aquí.

19.4 Haga push a GitHub

Haga push del estado actual de los archivos a GitHub.

Revise el repositorio en el navegador.

¿Ve las modificaciones y los nuevos archivos? El Rmd debe estar modificado (el YAML ha cambiado). Y debe haber ganado por lo menos, el archivo de reducción asociado.

  • Revise el archivo Markdown y compárelo con el HTML anterior.
  • ¿Ve cómo el markdown es mucho más útil en GitHub? Interiorícelo.

19.5 Póngale su sello

Seleccione todo menos el encabezado YAML y … suprímalo!

Escriba una sola oración.

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

```{r}
## Inserte su código aquí
```

Inserte de 1 a 3 líneas de código que comiencen la tarea a mano. “Ensaye” y ejecute esas líneas con el botón “Run” o el atajo de teclado correspondiente. ¡Debe asegurarse de que su código realmente funciona!

¿Satisfecho? ¡Guarde!

Tal vez quiera hacer commit aquí.

Ahora procese todo el documento a través de “Knit HTML”. ¡Voilà!

Tal vez quiera hacer commit aquí.

19.6 Haga su informe

De esta forma gradual, haga su informe. Agregue código a este chunk. Refínelo. Añada nuevos chunks. ¡Enloquézcase! Pero siga ejecutando el código “manualmente” para asegurarse de que funciona.

Si no lo trata como a un recién nacido, fracasará, de una manera más espectacular y críptica, cuando se ejecute remotamente 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 un montón de elementos del menú chunk y atajos de teclado para acelerar este flujo de trabajo. Compile todo el documento a menudo para detectar errores cuando sean fáciles de identificar y corregir. Guarde el documento con frecuencia y haga commit cada vez que alcance un punto que considere como una posición de “retroceso”.

Usted desarrollará su propio modo de trabajo, pero esto debería darle su primera experiencia exitosa en R Markdown.

19.7 Publique su reporte

Si ha estado haciendo HTML, puede ponerlo en la web en algún sitio, enviar un correo electrónico a un colaborador, o lo que sea.

No importa que, técnicamente, pueda publicar este informe simplemente subiendo una versión compilada 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 se encuentran muy frustrantes:

  • “Aquí está mi código”. Esto es cuando alguien sólo sube su código, por ejemplo, en R Markdown o el script en R Y se limitan a que otras personas simplemente miren su “producto”. La suposición implícita es que el público objetivo descargará el código y lo ejecutará. A veces el beneficio potencial simplemente no justifica este esfuerzo.

  • “Aquí está mi código HTML”. Esto es cuando alguien no se molestó en editar el formato de salida predeterminado y acepta sólo HTML. ¿Qué se supone que uno debe hacer con el HTML en GitHub?

Crear, hacer commit y push de markdown es una estrategia de publicación muy funcional y ligera. Utilice output: github_document o keep_md: true si la salida es html_document. En ambos casos, es fundamental también hacer commit y subir todo dentro de foo_files. Ahora la gente puede visitar y consumir su trabajo como cualquier otra página web.

Éste es (en cierto modo) otro ejemplo de mantener las cosas legibles tanto para las máquinas como para las personas. Haciendo que foo.Rmd esté disponible, otros pueden ver y ejecutar su código actual. Al compartir foo.md y/o foo.html, otros pueden navegar casualmente por su producto final y decidir si incluso quieren preocuparse por él.

19.8 HTML en GitHub

Los archivos HTML, como foo.html, no son inmediatamente útiles en GitHub (aunque sus versiones locales son fácilmente visibles). Revise uno y verá el código HTML en bruto. ¡Qué asco! Pero hay formas de obtener una vista previa: como https://rawgit.com o http://htmlpreview.github.io. Espere un poco de dolor con los archivos HTML dentro de repositorios privados. Cuando se convierte en vital para que todo el mundo vea el HTML apropiado en toda su extensión, es hora de utilizar una estrategia de publicación web más sofisticada.

Hay más ideas generales acerca de cómo hacer funcionar un repositorio de GitHub como un sitio web.

19.9 Resolución de problemas

Asegúrese de que RStudio y el paquete rmarkdown (y sus dependencias) estén actualizados. En caso de fallo catastrófico en R Markdown, considere que su software puede ser demasiado antiguo. R Markdown se ha desarrollado rápidamente (escrito en 2015-09), por lo que necesita una versión muy actual de RStudio y rmarkdown para disfrutar de todas las cosas que se describen en este curso.

Deshágase del .Rprofile, al menos temporalmente. Se ha encontrado que un .Rprofile “antiguo” que se ha acumulado arbitrariamente en los últimos años puede causar problemas. Específicamente, si tiene algo relacionado con knitr,markdown, rmarkdown y material de RStudio, puede estar impidiendo la instalación o el uso de los productos más recientes (véase más arriba). Comente todo el archivo o renómbrelo y vuelva a iniciar o reinstale RStudio.

Inserte un chunk en su documento .Rmd para que se muestre incluso cuando haya errores. Algunos errores son más fáciles de diagnosticar si puede ejecutar determinadas instrucciones en R durante la compilación y dejar más evidencia para el examen forense. Ponga este chunk:

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

cerca de la parte superior de su documento de R Markdown si desea continuar a pesar de los errores, es decir, convertir foo.Rmd en foo.md y/o foo.html a pesar de todo. Esto también es útil si está escribiendo un tutorial y desea un código de demostración que arroje un error. Es posible que desee mantener esto como un fragmento RStudio para facilitar la inserción.

Tolerar errores en un chunk específico. Si no desea aceptar globalmente errores, puede hacer esto para un chunk específico:

```{r wing-and-a-prayer, error = TRUE}
## su código incompleto va aquí ;)
```

Compruebe su directorio de trabajo. Se decepcionará a medida que aprenda con qué frecuencia sus errores son realmente mundanos y básicos. Cuando las cosas salen mal considere:

  • ¿Cuál es el directorio de trabajo?
  • ¿Está ese archivo que quiero leer/escribir en realidad donde creo que está?

Suelte estos comandos en chunks de R para comprobar lo anterior:

  • getwd() mostrará el directorio de trabajo en ejecución. Si usted juguetea con el directorio de trabajo con, por ejemplo, el ratón, ¿tal vez se establezca en un lugar para su desarrollo interactivo y otro cuando “Knit HTML” se hace cargo?
  • list.files() listará los archivos en el directorio de trabajo. ¿Está el archivo que desea incluido allí?

No intente cambiar el directorio de trabajo dentro de un documento de R Markdown. No lo haga. Vea knitr FAQ #5. Eso es todo.

No tenga prisa en crear una estructura de subdirectorios compleja. RStudio/knitr/rmarkdown (que trae el botón “Knit HTML”) son más bien obstinados acerca de que el directorio de trabajo esté configurado en la localización del archivo .Rmd y todos los archivos estén juntos en un gran directorio.