Sintaxis en un reporte

Ahora vamos a ver como se trabaja en cada una de las secciones de un reporte. Cada una tiene una sintaxis distinta, parece mucho, pero veremos que no se aleja de lo que cada uno ya sabe.

Encabezado

El encabezado es una serie de instrucciones organizadas entre tres guiones (---) que determinan las propiedades globales del documento, como el título, el formato de salida, información de autoría, etc… También ahí se pueden cambiar opciones asociadas al formato de salida, como el estilo de la tabla de contenidos o índice.

Éstas propiedades se definen en un formato llamado YAML, el cual permite definir listas jerarquizadas de una forma humanamente legible. Por ejemplo:

RMarkdown
Quarto

---
title: "Mi primer RMarkdown"
output: 
  html_document:
    code_download: true
    toc: true
    toc_float: false
---

define dos variables principales, “title” y “output”. “Output” a su vez contiene un elemento “htm_document”, el cual contiene tres elementos: “code_download”, “toc” y “toc_float”.

---
title: "Mi primer RMarkdown"
format:
  html:
    code-tools: true
toc: true
---

define dos variables principales, “title” y “format”. “format” a su vez contiene un elemento “html” que define el formato de salida y contiene una nueva opción: “code-tools: true”. Esto permite visualizar el código fuente que genera la web cuando ya está publicada. “toc : true” generará una tabla de contenidos.

Importante

Es muy importante mantener el escalonado, o identación de los elementos, ya que ésta define la jerarquía de cada elemento. Muchos de los errores a la hora de knitear ocurren porque el archivo tiene problemas en la identación del encabezado.

Bloques de código

El código de R que va a leer datos, analizarlos y generar figuras, tablas o números se organiza en bloques (o chunks) delimitados por tres acentos graves (```) y se diferencia del resto de archivo con un fondo gris. Todo lo que incluyas entre estos delimitadores será interpretado por R como código e intentará ejecutarlo al knitear el archivo. Cualquier resultado del código (gráficos, tablas, texto, etc…) será insertado en el documento final en el mismo orden que están en el archivo R Markdown.

Instrucciones

Para insertar un nuevo chunk podés:

Usar el botón Insert
El atajo de teclado Ctrl+Alt+I
Escribir a mano!

El código en cada bloque se ejecuta como si fuera ejecutado en la terminal y todo resultado se muestra en el documento (ya vamos a ver formas de controlar esto). Por ejemplo, este bloque de código

```{r sumar}
1 + 1
```

va a insertar esto en el documento de salida:

[1] 2

Importante

Es muy importante no romper los límites de los bloques. Un problema común es accidentalmente eliminar un acento grave al final de un bloque de código y que luego el documento no knitee correctamente. Si al knitear te sale un error como “attempt to use zero-length variable name”, revisá bien que todos tus bloques de código estén correctamente definidos.

Los bloques pueden tener nombre, lo cual es útil para identificar donde ocurren los errores al momento de knitear pero también para tener una pista de lo que hace el código que incluye.

Si bien el código se corre cuando uno knitea, cuando estés escribiendo un informe es muy cómodo ir corriendo bloques individuales interactivamente como si fuera en la consola.

Para correr una línea de código, tendrás que pararte sobre esa línea y apretar:

Instrucciones

Ctrl+Enter

Pero también podés correr el código de todo el chunk con:

Instrucciones

Ctrl+Shift+Enter

Los resultados van a aparecer inmediatamente debajo del bloque.

Ejercicio

Tercer desafío: Sumá un chunk a tu archivo

Usando el archivo con el que venís trabajando insertá un nuevo chunk y:

Cargá el paquete readr.
Creá una variable que se llame variable_prueba y asignale un valor.
Mostrá ese valor.
Volvé a knitear el archivo para ver el resultado

Finalmente, es posible que te encuentres mencionando resultados en el texto, por ejemplo algo así como “el promedio de la variable estudiada es 3.45”. Y también es posible que ese valor cambie si utilizas una base de datos distinta o si luego generas un informe pero para un mes siguiente. Las chances de de que te olvides de actualizar ese “3.45” son super altas, por eso R Markdown también tiene la posibilidad de incorporar código en línea con el texto.

Si tenés una una variable promedio que vale “3.45”:

promedio <- "3.45"

Para mencionarla en el texto entonces escribirías:

el promedio de la variable estudiada es `r promedio`.

y el resultado en el documento kniteado sería

el promedio de la variable estudiada es 3.45.

prueba: 3.45

El texto propio del documento.

Este es el texto dirigido a las personas que van a leer el reporte. Incluirá una introducción, descripción de los datos y de los resultados; es lo que escribirías en el archivo de Word.

A diferencia de Word, el formato del texto se define usando markdown, que es un lenguaje simple que permite indicar si un texto va en negrita, cursiva, es un título, etc…usando símbolos especiales dentro del texto.

Markdown

Markdown permite escribir en texto plano pero definiendo el formato usando símbolos. Por ejemplo podés resaltar con negrita usando dos asteriscos así: **negrita** o italizada con un asterisco de cada lado: *itálicas*.

También podés hacer una lista de elementos utilizando asteriscos:

* la negrita se consigue con dos asteriscos
* la italizada con un asterisco
* y para resaltar código se usa el acento grave `

o guiones medios:

- la negrita se consigue con dos asteriscos
- la italizada con un asterisco
- y para resaltar código se usa el acento grave `

Ambas listas se van a ver de esta manera:

la negrita se consigue con dos asteriscos
la italizada con un asterisco
y para resaltar código se usa el acento grave `

Si en realidad querés una lista numerada, simplemente comenzá el renglón un número y un punto. Podrías usar siempre el mismo número, markdown se encarga del resto:

1. la negrita se consigue con dos asteriscos
1. la italizada con un asterisco
1. y para resaltar código se usa el acento grave `

Ahora la lista numerada se ve así:

la negrita se consigue con dos asteriscos
la italizada con un asterisco
y para resaltar código se usa el acento grave `

Podés agregar títulos con distinta jerarquía agregando # al comienzo. Esto además define secciones dentro del documento:

# Título
## El primer subtítulo
### Otro subtítulo de menor jerarquía
#### Otro más, y podría seguir!

Podés escribir estos símbolos a mano o usando el Editor Visual de RStudio y cambiar de la versión código fuente a la versión visual según prefieras ( icono del editor visual ) . El Editor Visual permite dar formato al texto usando markdown sin saber usar markdown.

Ejercicio

Cuarto desafío: Agregale texto a tu archivo

Borrá el contenido del archivo .Rmd que creaste (pero no el encabezado!) y probá escribir algo y darle formato. Luego volvé a apretar el botón knit para ver el resultado.

Markdown permite muchas otras cosas, por ejemplo:

Podés agregar un link a una página externa: [texto que se muestra con el link](http://google.com). Resultado: texto que se muestra con el link
Podés incluir una imagen: ![descripción de la figura](https://placekitten.com/200/100)

Resultado:

Y también podés agregar ecuaciones (usando LaTeX) en la misma línea (esto: $E = mc^2$ se ve así: $E = mc^2$) o en una línea propia. Esto:

$$
y = \mu + \sum_{i=1}^p \beta_i x_i + \epsilon
$$

se ve así:

\[ y = \mu + \sum_{i=1}^p \beta_i x_i + \epsilon \]

Información

Podés revisar la guía rápida de Markdown desde RStudio (en inglés):

Help → Markdown Quick Reference

Control de chunks

Previamente vimos que un chunk tiene una pinta como esta:

```{r nombre-del-chunk}

```

Ponerle nombre al chunk no es obligatorio pero está bueno para tener una idea de qué hace cada uno, lo cual se vuelve más importante a medida que un reporte se vuelve más largo y complejo. Pero lo que no dijimos es que además del nombre, se pueden agregar un montón de opciones que cambian el comportamiento y la apariencia del resultado del chunk.

RMarkdown
Quarto

Para cambiar las opciones de un chunk, lo único que hay que hacer es listarlas dentro de los corchetes. Por ejemplo:

```{r nombre-del-chunk, echo = FALSE, message = FALSE}

```

Para cambiar las opciones de un chunk, lo único que hay que hacer es listarlas como comentarios de quarto. Por ejemplo:

```{r nombre-del-chunk}
#| echo: false
#| message: false

```

Hay una serie de opciones particularmente importante es la que controla si el código se ejecuta y si el resultado del código se va a mostrar en el reporte o no:

eval = FALSE evita que se ejecute el código del chunk, de manera que tampoco va a mostrar resultados. Es útil para mostrar códigos de ejemplo si estás escribiendo, por ejemplo un documento para enseñar R.
echo = FALSE ejecuta el código del chunk y muestra los resultados, pero oculta el código en el reporte. Esto es útil para escribir reportes para personas que no necesitan ver el código de R que generó el gráfico o tabla que querés mostrar.
include = FALSE corre el código pero oculta tanto el código como los resultados. Es útil para usar en chunks de configuración general donde, por ejemplo, cargas las librerías.
message = FALSE el bloque de código no mostrará los posibles mensajes que genere.
warning = FALSE el bloque de código no mostrará los posibles warnings que genere.

Si estás escribiendo un informe en el que no querés que se muestre ningún código, agregarle echo = FALSE a cada chunk nuevo se vuelve tedioso. La solución es cambiar la opción de forma global de manera que aplique a todos los chunks. Esto se hace mediante la función knitr::opts_chunk$set(), que setea las opciones globales de los chunks que le siguen. Si querés que todos los chunks tengan echo = TRUE crearías un chunk así:

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

Generalmente tiene sentido poner esto en el primer chunk de un documento, que como suele ser cuestiones de configuración del reporte, también conviene ponerle include = FALSE.

Información

En quarto, las opciones globales se agregan en el YAML:

---
title: "Mi primer RMarkdown"
format:
  html:
    code-tools: true
toc: true
execute:
  echo: false
  message: false
  warning: false
---

Pero por supuesto, el documento puede tener un primer chunk setup que cargue las librerías y código útil para nuestro trabajo

Finalmente, una opción tan poderosa como peligrosa es cache = TRUE. Lo que hace es que en vez de correr el código de un chunk cada vez que kniteás el documento, guarda el resultado del chunk en el disco para reutilizar la próxima vez que crees el reporte. Esto es muy cómo si en chunk tiene un código que tarda mucho en correr. Por ejemplo el siguiente chunk va a tardar 10 minutos en correr la primera vez que knitees el reporte, pero luego va a ser mucho más rápido:

```{r cache = FALSE}
datos <- funcion_que_tarda_10_minutos(x)
```

knitr es bastante inteligente y va a invalidar la cache si cambiás el código del chunk. Pero, ¿qué pasa si cambiás algo del código previo que cambia el valor de x o incluso el funcionamiento de function_que_targa_10_minutos? Es posible que knitr no se de cuenta y use la cache, con el resultado de que datos va a tener un valor incorrecto. Hay formas de decirle a knitr de qué depende cada chunk y así obtener una cache más “inteligente” pero es algo que se vuelve complicado muy rápido.

En resumen, es bueno usar la cache pero sólo cuando es imprescindible.

--- title: "Sintaxis en un reporte" toc: true format: html: code-tools: true self-contained: true execute: message: false warning: false --- ```{r, include=FALSE} chunk <- "```" ``` Ahora vamos a ver como se trabaja en cada una de las secciones de un reporte. Cada una tiene una sintaxis distinta, parece mucho, pero veremos que no se aleja de lo que cada uno ya sabe. ## Encabezado El encabezado es una serie de instrucciones organizadas entre tres guiones (`---`) que determinan las propiedades globales del documento, como el título, el formato de salida, información de autoría, etc... También ahí se pueden cambiar opciones asociadas al formato de salida, como el estilo de la tabla de contenidos o índice. Éstas propiedades se definen en un formato llamado [YAML](https://es.wikipedia.org/wiki/YAML), el cual permite definir listas jerarquizadas de una forma humanamente legible. Por ejemplo: ::: panel-tabset ### RMarkdown ``` yaml --- title: "Mi primer RMarkdown" output: html_document: code_download: true toc: true toc_float: false --- ``` define dos variables principales, "title" y "output". "Output" a su vez contiene un elemento "htm_document", el cual contiene tres elementos: "code_download", "toc" y "toc_float". ### Quarto ``` yaml --- title: "Mi primer RMarkdown" format: html: code-tools: true toc: true --- ``` define dos variables principales, "title" y "format". "format" a su vez contiene un elemento "html" que define el formato de salida y contiene una nueva opción: "code-tools: true". Esto permite visualizar el código fuente que genera la web cuando ya está publicada. "toc : true" generará una tabla de contenidos. ::: ::: callout-important ## Importante Es muy importante mantener el escalonado, o *identación* de los elementos, ya que ésta define la jerarquía de cada elemento. Muchos de los errores a la hora de knitear ocurren porque el archivo tiene problemas en la identación del encabezado. ::: ## Bloques de código El código de R que va a leer datos, analizarlos y generar figuras, tablas o números se organiza en bloques (o `chunks`) delimitados por tres acentos graves (```` ``` ````) y se diferencia del resto de archivo con un fondo gris. Todo lo que incluyas entre estos delimitadores será interpretado por R como código e intentará ejecutarlo al *knitear* el archivo. Cualquier resultado del código (gráficos, tablas, texto, etc...) será insertado en el documento final en el mismo orden que están en el archivo R Markdown. ::: callout-note ## Instrucciones Para insertar un nuevo chunk podés: - Usar el botón **Insert** - El atajo de teclado Ctrl+Alt+I - Escribir a mano! ::: El código en cada bloque se ejecuta como si fuera ejecutado en la terminal y todo resultado se muestra en el documento (ya vamos a ver formas de controlar esto). Por ejemplo, este bloque de código ```{r sumar}`r ''` 1 + 1 ``` va a insertar esto en el documento de salida: [1] 2 ::: callout-important ## Importante Es muy importante no romper los límites de los bloques. Un problema común es accidentalmente eliminar un acento grave al final de un bloque de código y que luego el documento no knitee correctamente. Si al knitear te sale un error como "attempt to use zero-length variable name", revisá bien que todos tus bloques de código estén correctamente definidos. ::: Los bloques pueden tener nombre, lo cual es útil para identificar donde ocurren los errores al momento de *knitear* pero también para tener una pista de lo que hace el código que incluye. Si bien el código se corre cuando uno knitea, cuando estés escribiendo un informe es muy cómodo ir corriendo bloques individuales interactivamente como si fuera en la consola. Para correr una línea de código, tendrás que pararte sobre esa línea y apretar: ::: callout-note ## Instrucciones Ctrl+Enter ::: Pero también podés correr el código de todo el chunk con: ::: callout-note ## Instrucciones Ctrl+Shift+Enter ::: Los resultados van a aparecer inmediatamente debajo del bloque. ::: callout-tip ## Ejercicio **Tercer desafío: Sumá un chunk a tu archivo** Usando el archivo con el que venís trabajando insertá un nuevo chunk y: 1. Cargá el paquete readr. 2. Creá una variable que se llame `variable_prueba` y asignale un valor. 3. Mostrá ese valor. 4. Volvé a *knitear* el archivo para ver el resultado ::: Finalmente, es posible que te encuentres mencionando resultados en el texto, por ejemplo algo así como "el promedio de la variable estudiada es 3.45". Y también es posible que ese valor cambie si utilizas una base de datos distinta o si luego generas un informe pero para un mes siguiente. Las chances de de que te olvides de actualizar ese "3.45" son super altas, por eso R Markdown también tiene la posibilidad de incorporar código en línea con el texto. Si tenés una una variable `promedio` que vale "3.45": ```{r} promedio <- "3.45" ``` Para mencionarla en el texto entonces escribirías: > el promedio de la variable estudiada es \``r` `promedio`\`. y el resultado en el documento kniteado sería > el promedio de la variable estudiada es `r promedio`. prueba: `` `r promedio` `` ## El texto propio del documento. Este es el texto dirigido a las personas que van a leer el reporte. Incluirá una introducción, descripción de los datos y de los resultados; es lo que escribirías en el archivo de Word. A diferencia de Word, el formato del texto se define usando [markdown](https://es.wikipedia.org/wiki/Markdown), que es un lenguaje simple que permite indicar si un texto va en negrita, cursiva, es un título, etc...usando símbolos especiales dentro del texto. ### Markdown Markdown permite escribir en texto plano pero definiendo el formato usando símbolos. Por ejemplo podés resaltar con **negrita** usando dos asteriscos así: `**negrita**` o *italizada* con un asterisco de cada lado: `*itálicas*`. También podés hacer una lista de elementos utilizando asteriscos: * la negrita se consigue con dos asteriscos * la italizada con un asterisco * y para resaltar código se usa el acento grave ` o guiones medios: - la negrita se consigue con dos asteriscos - la italizada con un asterisco - y para resaltar código se usa el acento grave ` Ambas listas se van a ver de esta manera: - la negrita se consigue con dos asteriscos - la italizada con un asterisco - y para resaltar código se usa el acento grave \` Si en realidad querés una lista numerada, simplemente comenzá el renglón un número y un punto. Podrías usar siempre el mismo número, markdown se encarga del resto: 1. la negrita se consigue con dos asteriscos 1. la italizada con un asterisco 1. y para resaltar código se usa el acento grave ` Ahora la lista numerada se ve así: 1. la negrita se consigue con dos asteriscos 2. la italizada con un asterisco 3. y para resaltar código se usa el acento grave \` Podés agregar títulos con distinta jerarquía agregando `#` al comienzo. Esto además define secciones dentro del documento: # Título ## El primer subtítulo ### Otro subtítulo de menor jerarquía #### Otro más, y podría seguir! Podés escribir estos símbolos a mano o usando el Editor Visual de RStudio y cambiar de la versión código fuente a la versión visual según prefieras (![icono del editor visual](img/icono-editor-visual.png)) . El Editor Visual permite dar formato al texto usando markdown sin saber usar markdown. ::: callout-tip ## Ejercicio **Cuarto desafío: Agregale texto a tu archivo** Borrá el contenido del archivo `.Rmd` que creaste (pero no el encabezado!) y probá escribir algo y darle formato. Luego volvé a apretar el botón **knit** para ver el resultado. ::: Markdown permite muchas otras cosas, por ejemplo: - Podés agregar un link a una página externa: `[texto que se muestra con el link](http://google.com)`. Resultado: [texto que se muestra con el link](http://google.com) - Podés incluir una imagen: `![descripción de la figura](https://placekitten.com/200/100)` Resultado: ![descripción de la figura](https://placekitten.com/200/100) Y también podés agregar ecuaciones (usando [LaTeX](https://es.wikipedia.org/wiki/LaTeX)) en la misma línea (esto:`$E = mc^2$` se ve así: $E = mc^2$) o en una línea propia. Esto: $$ y = \mu + \sum_{i=1}^p \beta_i x_i + \epsilon $$ se ve así: $$ y = \mu + \sum_{i=1}^p \beta_i x_i + \epsilon $$ ::: callout-note ## Información Podés revisar la guía rápida de Markdown desde RStudio (en inglés): Help → Markdown Quick Reference ::: ## Control de chunks Previamente vimos que un chunk tiene una pinta como esta: `r chunk`{r nombre-del-chunk} `r chunk` Ponerle nombre al chunk no es obligatorio pero está bueno para tener una idea de qué hace cada uno, lo cual se vuelve más importante a medida que un reporte se vuelve más largo y complejo. Pero lo que no dijimos es que además del nombre, se pueden agregar un montón de opciones que cambian el comportamiento y la apariencia del resultado del chunk. ::: panel-tabset ### RMarkdown Para cambiar las opciones de un chunk, lo único que hay que hacer es listarlas dentro de los corchetes. Por ejemplo: `r chunk`{r nombre-del-chunk, echo = FALSE, message = FALSE} `r chunk` ### Quarto Para cambiar las opciones de un chunk, lo único que hay que hacer es listarlas como comentarios de quarto. Por ejemplo: `r chunk`{r nombre-del-chunk} #| echo: false #| message: false `r chunk` ::: Hay una serie de opciones particularmente importante es la que controla si el código se ejecuta y si el resultado del código se va a mostrar en el reporte o no: - `eval = FALSE` evita que se ejecute el código del chunk, de manera que tampoco va a mostrar resultados. Es útil para mostrar códigos de ejemplo si estás escribiendo, por ejemplo un documento para enseñar R. - `echo = FALSE` ejecuta el código del chunk y muestra los resultados, pero oculta el código en el reporte. Esto es útil para escribir reportes para personas que no necesitan ver el código de R que generó el gráfico o tabla que querés mostrar. - `include = FALSE` corre el código pero oculta tanto el código como los resultados. Es útil para usar en chunks de configuración general donde, por ejemplo, cargas las librerías. - `message = FALSE` el bloque de código no mostrará los posibles mensajes que genere. - `warning = FALSE` el bloque de código no mostrará los posibles warnings que genere. Si estás escribiendo un informe en el que no querés que se muestre ningún código, agregarle `echo = FALSE` a cada chunk nuevo se vuelve tedioso. La solución es cambiar la opción de forma global de manera que aplique a todos los chunks. Esto se hace mediante la función `knitr::opts_chunk$set()`, que setea las opciones globales de los chunks que le siguen. Si querés que todos los chunks tengan `echo = TRUE` crearías un chunk así: `r chunk`{r setup, include = FALSE} knitr::opts_chunk$set(echo = TRUE) `r chunk` Generalmente tiene sentido poner esto en el primer chunk de un documento, que como suele ser cuestiones de configuración del reporte, también conviene ponerle `include = FALSE`. ::: callout-note ## Información En quarto, las opciones globales se agregan en el YAML: ``` yaml --- title: "Mi primer RMarkdown" format: html: code-tools: true toc: true execute: echo: false message: false warning: false --- ``` Pero por supuesto, el documento puede tener un primer chunk setup que cargue las librerías y código útil para nuestro trabajo ::: Finalmente, una opción tan poderosa como peligrosa es `cache = TRUE`. Lo que hace es que en vez de correr el código de un chunk cada vez que *kniteás* el documento, guarda el resultado del chunk en el disco para reutilizar la próxima vez que crees el reporte. Esto es muy cómo si en chunk tiene un código que tarda mucho en correr. Por ejemplo el siguiente chunk va a tardar 10 minutos en correr la primera vez que knitees el reporte, pero luego va a ser mucho más rápido: `r chunk`{r cache = FALSE} datos <- funcion_que_tarda_10_minutos(x) `r chunk` knitr es bastante inteligente y va a invalidar la cache si cambiás el código del chunk. Pero, ¿qué pasa si cambiás algo del código previo que cambia el valor de `x` o incluso el funcionamiento de `function_que_targa_10_minutos`? Es posible que knitr no se de cuenta y use la cache, con el resultado de que `datos` va a tener un valor incorrecto. Hay formas de decirle a knitr de qué depende cada chunk y así obtener una cache más "inteligente" pero es algo que se vuelve complicado muy rápido. En resumen, es bueno usar la cache pero sólo cuando es imprescindible.