-
Notifications
You must be signed in to change notification settings - Fork 40
/
28-quarto.Rmd
366 lines (244 loc) · 14.7 KB
/
28-quarto.Rmd
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
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
# (PART\*) Communicate {-}
# Quarto
```{r fig, echo=FALSE, out.width="40%", fig.align="center"}
knitr::include_graphics("./images/quarto-dark-bg.jpeg")
```
**Learning objectives:**
- Understand the basic components of a Quarto document.
## Introduction {-}
- Quarto is a command line interface tool, not an R package.
- Quarto unifies the functionality of many packages from the R Markdown ecosystem: rmarkdown, bookdown, distill, xaringan, etc. into a single consistent system.
- Quarto -> native support for multiple programming languages like Python and Julia in addition to R
- [Documentation](https://quarto.org/)
- Quarto documents:
- reproducible
- support dozens of output formats: PDFs, Word files, presentations, and more.
- 3 main uses:
1. Communication: focus on conclusions not code.
2. Collaborating with other scientists (including future you!): conclusions and code.
3. Environment in which to do data science.
## Quarto basics {-}
- Quarto files have `.qmd` extension.
- Contains 3 types of contents:
- and optional YAML header surrounded by 3 dashes (---) at the beginning and end
- chunks of R code surrounded by 3 back ticks (```)
- text mixed with simple formatting like #heading or **italics**
- To get started with your own .qmd file, select File > New File > Quarto Document… in the menu bar.
```{r quarto, echo=FALSE, out.width="100%", fig.align="center"}
knitr::include_graphics("./images/28-fig28.png")
```
## Run code in quarto {-}
- Run each code chunk by clicking the Run icon (each chunk will have this green arrow) or by pressing Cmd/Ctrl + Shift + Enter.
- You can choose to have the plots and output displayed in the document or on RStudio's console and plot panes. Go to the gear icon next to "Render" and switch to "Chunk Output Console".
- To run the complete report, click "Render" or press Cmd/Ctrl + Shift + K. Or go to the console and type: `quarto::quarto_render("diamond-sizes.qmd")`. Your report will be displayed in the viewer pane as an HTML file (unless the YAML includes .pdf or other extension).
## Visual editor {-}
- Visual editor -> use the buttons on the menu bar to insert images, tables, cross-references, etc. or you can use the catch-all ⌘ + / or Ctrl + / shortcut to insert just about anything.
- The visual editor displays your content with formatting, but under the hood, it saves your content in plain Markdown and you can switch back and forth between the visual and source editors.
```{r vised, echo=FALSE, out.width="100%", fig.align="center"}
knitr::include_graphics("./images/28-quarto-visual-editor.png")
```
## Source editor {-}
- The Source editor will feel familiar to those with experience writing R scripts or R Markdown documents.
- Can also be useful for debugging any Quarto syntax errors since it’s often easier to catch these in plain text.
- If you forget, you can get to a handy reference sheet with Help > Markdown Quick Reference.
```{r}
#| echo: false
#| comment: ""
cat(readr::read_file("quarto/markdown.qmd"))
```
## Code chunks {-}
- To run code inside a Quarto document, you need to insert a chunk.
1. The keyboard shortcut Cmd + Option + I / Ctrl + Alt + I.
2. The “Insert” button icon in the editor toolbar.
3. By manually typing the chunk delimiters ```{r} and ```.
## Chunk label {-}
Chunks can be given an optional label, e.g.
```{r}
#| echo: false
#| out-width: "100%"
knitr::include_graphics("images/28-chunk-label.png")
```
This has three advantages:
1. Navigate to specific chunks using the drop-down code navigator in the bottom-left of the script editor:
```{r}
#| echo: false
#| out-width: "30%"
#| fig-alt: |
#| Snippet of RStudio IDE showing only the drop-down code navigator
#| which shows three chunks. Chunk 1 is setup. Chunk 2 is cars and
#| it is in a section called Quarto. Chunk 3 is pressure and it is in
#| a section called Including plots.
knitr::include_graphics("images/quarto-chunk-nav.png")
```
2. Graphics produced by the chunks will have useful names that make them easier to use elsewhere.
3. You can set up networks of cached chunks to avoid re-performing expensive computations on every run.
- Important!
- Your chunk labels should be short but evocative and should not contain spaces.
- We recommend using dashes (`-`) to separate words (instead of underscores, `_`) and no other special characters in chunk labels.
- Use whatever name, except: `setup`, which is used for a specific reason.
- Additionally, chunk labels cannot be duplicated.
- Each chunk label must be unique.
## Chunk options {-}
- Chunk output can be customized with **options**.
- You can see the full list at https://yihui.org/knitr/options.
- Each of these chunk options get added to the header of the chunk, following `#|`.
```{r}
#| echo: false
#| comment: ""
#| out-width: "100%"
knitr::include_graphics("images/28-chunk-options.png")
```
- The main options are:
- `eval: false` prevents code from being evaluated. And obviously if the code is not run, no results will be generated.
- `include: false` runs the code, but doesn't show the code or results in the final document.
- `echo: false` prevents code, but not the results from appearing in the finished file.
- `message: false` or `warning: false` prevents messages or warnings from appearing in the finished file.
- `results: hide` hides printed output; `fig-show: hide` hides plots.
- `error: true` causes the render to continue even if code returns an error.
This is rarely something you'll want to include in the final version of your report, but can be very useful if you need to debug exactly what is going on inside your `.qmd`.
It's also useful if you're teaching R and want to deliberately include an error.
The default, `error: false` causes rendering to fail if there is a single error in the document.
## Global options {-}
- You can set global options that control the entire document in the YAML under `execute`.
```{r}
#| echo: false
#| comment: ""
#| out-width: "100%"
knitr::include_graphics("images/28-execute-yaml.png")
```
- You can also set some global options under the `knitr` field. For example:
```{r}
#| echo: false
#| comment: ""
#| out-width: "100%"
knitr::include_graphics("images/28-knitr-options.png")
```
## Inline code {-}
- There is one other way to embed R code into a Quarto document: directly into the text, with r inside back ticks.
- For example, you can inline code include in between text and that will show a result.
> The data frame iris has `r nrow(iris)` rows.
## Figures {-}
- The figures in a Quarto document can be embedded (e.g., a PNG or JPEG file) or generated as a result of a code chunk.
- Five main options that control figure sizing: fig-width, fig-height, fig-asp, out-width and out-height. Image sizing is challenging because there are two sizes (the size of the figure created by R and the size at which it is inserted in the output document), and multiple ways of specifying the size (i.e. height, width, and aspect ratio: pick two of three).
- It's best if plots have consistent width. To enforce this, set fig-width: 6 (6”) and fig-asp: 0.618 (the golden ratio) in the defaults. Then in individual chunks, only adjust fig-asp.
- Control the output size with out-width and set it to a percentage of the body width of the output document. We suggest to out-width: "70%" and fig-align: center.
- To put multiple plots in a single row, set the layout-ncol to 2 for two plots, 3 for three plots, etc. This effectively sets out-width to “50%” for each of your plots if layout-ncol is 2,
- Great [blog post](https://www.tidyverse.org/blog/2020/08/taking-control-of-plot-scaling/) by Thomas Lin Pedersen about controling plot scaling.
## Tables {-}
- You can include two types of tables in a Quarto document:
- markdown tables that you create directly in your Quarto document, or
- tables generated as a result of a code chunk.
- Read the documentation for ?knitr::kable to see the other ways in which you can customize the table. For even deeper customization, consider the gt, huxtable, reactable, kableExtra, xtable, stargazer, pander, tables, and ascii packages. Each provides a set of tools for returning formatted tables from R code.
## Caching {-}
- Normally, each render of a document starts from a completely clean slate. However, it can be painful if you have some computations that take a long time. The solution is `cache: true` in the YAML under `execute`.
- You can also enable caching at the chunk level for caching the results of computation in a specific chunk using `#| cache: true`
- The caching system must be used with care, because by default it is based on the code only, not its dependencies. You can avoid that problem with the `dependson` chunk option. Here you include the object that it calls out to run the chunk. dependson should contain a character vector of every chunk that the cached chunk depends on.
- As your caching strategies get progressively more complicated, it’s a good idea to regularly clear out all your caches with `knitr::clean_cache()`.
## YAML header {-}
- You can control many other “whole document” settings by tweaking the parameters of the YAML header. You might wonder what YAML stands for: it’s “YAML Ain’t Markup Language"
### Self contained {-}
- HTML documents usually have external dependencies (e.g., images, CSS style sheets, etc.) so if you set in the YAML under `format:`, `html:` and then `embed-resources: true` the resulting document will be self-contained.
### Parameters {-}
## Bibliographies and citations {-}
- To add a citation using the visual editor, go to Insert > Citation. Under the hood, the visual mode uses the standard Pandoc markdown representation for citations (e.g., [@citation]). If you add a citation using the visual editor, it will automatically create a bibliography.bib file
- Your document bibliography (a .bib file in the directory of your document)
- To create a citation within your .qmd file in the source editor, use a key composed of ‘@’ + the citation identifier from the bibliography file. Then place the citation in square brackets. Here are some examples:
```{r}
#| echo: false
#| comment: ""
#| out-width: "100%"
knitr::include_graphics("images/28-bib.png")
```
## Meeting Videos {-}
### Cohort 5
`r knitr::include_url("https://www.youtube.com/embed/wAzYA01hojo")`
<details>
<summary> Meeting chat log </summary>
```
00:03:37 Njoki Njuki Lucy: I agree with Ryan.
00:15:27 Ryan Metcalf: https://pandoc.org/
00:20:48 Ryan Metcalf: Some extra reading material: https://www.w3.org/TR/WD-html40-970708/intro/sgmltut.html
00:28:14 Njoki Njuki Lucy: Qn, does anyone know why putting figure captions move figures to other positions?
00:33:58 Federica Gazzelloni: try with {r ….., fig.align =“center”}
00:35:01 Njoki Njuki Lucy: Thanks Federica, I'll give it a try :)
00:57:25 Ryan Metcalf: https://daringfireball.net/projects/markdown/
00:58:59 Ryan Metcalf: The comment I’m making, there are many forms of Markdown, not all created equally. John Gruber originated Markdown syntax to make authoring easier. GitHub versus GitLab, versus RMarkdonw, etc...
01:02:40 Federica Gazzelloni: you can set your path: opts_chunk$set(cache.path = " ")
01:04:42 Federica Gazzelloni: https://bookdown.org/yihui/rmarkdown-cookbook/cache.html
01:06:13 Ryan Metcalf: https://quarto.org/
01:07:57 Federica Gazzelloni: The most appropriate use case of caching is to save and reload R objects that take too long to compute in a code chunk
01:09:20 Njoki Njuki Lucy: no
01:09:26 Federica Gazzelloni: no
01:12:49 Njoki Njuki Lucy: I'll have to leave, thanks Becki! I look forward to the other part!!
01:12:53 Federica Gazzelloni: there is some more about the changing r session and the cache: https://www.r-bloggers.com/2021/07/caching-the-results-of-functions-of-your-r-package/
01:13:02 Becki R. (she/her): Bye Lucy!
```
</details>
`r knitr::include_url("https://www.youtube.com/embed/2MGp74nb2ig")`
<details>
<summary> Meeting chat log </summary>
```
00:10:00 Jon Harmon (jonthegeek): bestbook.cool
00:11:26 Jon Harmon (jonthegeek): https://podcast.bestbook.cool/
00:28:01 Jon Harmon (jonthegeek): happygitwithr.com
00:30:59 Jon Harmon (jonthegeek): Remind @Sandra Muroy to share the dlab GitHub stuff when this posts to our channel. There, I think that will tag you in the post!
00:32:44 Jon Harmon (jonthegeek): xaringan
00:36:45 Jon Harmon (jonthegeek): lol, it's just called {shinydashboard}
00:48:24 Becki R. (she/her): I definitely need help with that!
00:53:08 Jon Harmon (jonthegeek): It's been a while since we learned that!
2021-08-21: Chapter 6: Workflow: scripts: Ryan Metcalf
01:01:01 Jon Harmon (jonthegeek): {pak} = updated package tracker
01:01:48 Jon Harmon (jonthegeek): {targets}
01:03:00 Federica Gazzelloni: library(pkgsnap)
01:04:15 Jon Harmon (jonthegeek): devtools::install_version()
01:05:00 Jon Harmon (jonthegeek): ?remotes::install_version()
01:05:15 Jon Harmon (jonthegeek): install_version("devtools", ">= 1.12.0, < 1.14")
01:07:07 Jon Harmon (jonthegeek): https://github.com/MangoTheCat/pkgsnap
01:11:32 Jon Harmon (jonthegeek): https://docs.ropensci.org/targets/
01:11:46 Jon Harmon (jonthegeek): pkgdown
01:12:41 Jon Harmon (jonthegeek): https://rsample.tidymodels.org/
01:13:21 Jon Harmon (jonthegeek): https://pkgdown.r-lib.org/
01:13:32 Sandra Muroy: https://github.com/dlab-berkeley/Bash-Git
```
</details>
### Cohort 6
`r knitr::include_url("https://www.youtube.com/embed/dG5PcCDMDdI")`
<details>
<summary> Meeting chat log </summary>
```
00:18:56 Marielena Soilemezidi: https://rstudio.com/resources/cheatsheets/
00:19:07 Daniel: Thanks
00:59:42 Marielena Soilemezidi: http://rmarkdown.rstudio.com/developer_parameterized_reports.html#parameter_user_interfaces
```
</details>
### Cohort 7
`r knitr::include_url("https://www.youtube.com/embed/J9UTG7zxelw")`
<details>
<summary> Meeting chat log </summary>
```
00:08:43 Tim Newby: Hello Oluwafemi!
00:09:47 Oluwafemi Oyedele: start
00:19:45 Oluwafemi Oyedele: This is cool!!!
00:37:04 Oluwafemi Oyedele: https://rstudio-conf-2022.github.io/get-started-quarto/
01:01:50 Oluwafemi Oyedele: https://github.com/citation-style-language/styles
01:01:57 Oluwafemi Oyedele: stop
```
</details>
### Cohort 8
`r knitr::include_url("https://www.youtube.com/embed/7kW7DEWPVZ8")`
<details>
<summary> Meeting chat log </summary>
```
00:01:59 Shamsuddeen Muhammad: start
00:10:33 Ahmed Mamdouh: Im here
00:10:47 Ahmed Mamdouh: The internet is so bad sorry
00:12:18 Ahmed Mamdouh: Oh interesting
00:18:39 Ahmed Mamdouh: It like packaging all dependencies
00:25:58 Ahmed Mamdouh: Renv is like venv in python
00:29:57 Ahmed Mamdouh: Yup
00:31:32 Ahmed Mamdouh: Awesome
00:32:25 Shamsuddeen Muhammad: stop
00:32:27 Ahmed Mamdouh: Thanks alot man
00:32:50 Ahmed Mamdouh: Bye
```
</details>