-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy path03_sintaxis.qmd
312 lines (204 loc) · 12.6 KB
/
03_sintaxis.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
---
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 () . 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: ``
Resultado:
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.