-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathfigures-tables-captions.qmd
259 lines (181 loc) · 8.82 KB
/
figures-tables-captions.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
# Figures, Tables, Captions.
You need figures and tables in your own writing, whether it be a journal paper, an internal document, or some documentation. In this section, we discuss how to add figures and tables into your Quarto document, and how to provide captions for them.
## Overview
* **Teaching** 10 minutes
* **Exercises** 10 minutes
## Questions
* How do I create a figure in Quarto?
* How do I create a table in Quarto?
* How do I add captions for figures and tables?
## Objectives
## Tables
To produce a table, I recommend you use the `kable` function from the `knitr` package.
::: {.callout-caution title="Other table R packages" collapse="true"}
There are many other table making pieces of R packages, such as [`gt`](https://gt.rstudio.com/), [`formattable`](https://renkun-ken.github.io/formattable/), [`reactable`](https://glin.github.io/reactable/index.html), and [`flextable`](https://davidgohel.github.io/flextable/index.html)). But I think you can get 90% of the way there with `kable` from `knitr`, and for the
:::
### Demonstrating using tables
`kable` takes a `data.frame` as input, and outputs the table into a `markdown table`, which will get rendered into the appropriate output format.
For example, let's say we wanted to share the first 6 rows of our gapminder data.
```{r}
#| label: read-gapminder
#| include: false
#| echo: false
gapminder <- readr::read_csv(here::here("data", "gapminder.csv"))
```
This gives us the following output
```{r}
#| label: show-gapminder
top_gap <- head(gapminder)
knitr::kable(top_gap)
```
So how does that work? `kable` prints out the following:
```
|country |continent | year| lifeExp| pop| gdpPercap|
|:-----------|:---------|----:|-------:|--------:|---------:|
|Afghanistan |Asia | 1952| 28.801| 8425333| 779.4453|
|Afghanistan |Asia | 1957| 30.332| 9240934| 820.8530|
|Afghanistan |Asia | 1962| 31.997| 10267083| 853.1007|
|Afghanistan |Asia | 1967| 34.020| 11537966| 836.1971|
|Afghanistan |Asia | 1972| 36.088| 13079460| 739.9811|
|Afghanistan |Asia | 1977| 38.438| 14880372| 786.1134|
```
And this then gets _rendered_ as a table. This works for HTML, PDF, and word!
#### Adding captions to a table
Now, say that we wanted to include a caption? We use the `caption` argument. This will also automatically number the table (woo! We'll cover this later).
```{r}
#| label: print-tab-gap-captions
knitr::kable(top_gap,
caption = "The first 6 rows of the dataset, gapminder")
```
Some other useful features of `kable` include setting the rounding number, with the `digits` option.
For example, we could present the first 2 digits of each number like so:
```{r}
#| label: print-tab-gap-digits
knitr::kable(top_gap,
caption = "The first 6 rows of the dataset, gapminder",
digits = 2)
```
There are other options that you can set in `kable`, but for these options will get you through a large majority of what you need. For more information on what `kable` can provide, see `?knitr::kable`.
There are many different ways to produce tables in R. We have chosen to show `kable` today because kable is minimal, but powerful. If you want to extend `kable` to do more, look at [kableExtra](https://cran.r-project.org/web/packages/kableExtra/index.html). For PDF/LaTeX output, I found the option `kableExtra::kable_styling(latex_options = c("hold_position"))` particularly nice to just __put the table where it should be, goshdarnit__.
::: {.callout-note title="Your Turn"}
1. Using the "02-qmd-figures-chunks.qmd"
1. Create a summary of your gapminder data, put it into a table.
1. Add a caption to this table.
1. Set the number of decimals to 2.
:::
## Figures
Printing figures is probably my favourite feature of Quarto. It is actually relatively straightforward in the case of plots. You provide the plot you want to show in a code chunk!
::: {.callout-tip title="Demo using gapminder"}
For example, I can print a plot of the gapminder data for Australia like so:
```{r}
#| label: gg-gapminder
options(tidyverse.quiet = TRUE)
library(tidyverse)
gapminder |>
filter(country == "Australia") |>
ggplot(aes(x = year,
y = lifeExp)) +
geom_point()
```
:::
:::{.callout-tip title="Demo: Captions for figures"}
Inserting a caption for a figure is a little bit different. The caption argument is controlled in the chunk option, under the option, `fig-cap`.
So to insert a figure, we do the following.
````{markdown}
```{r}
#| label: gg-oz-gapminder
#| fig-cap: "Life expectancy from 1952 - 2007 for Australia. Life expentancy increases steadily except from 1962 to 1969. We can safely say that our life expectancy is higher than it has ever been!"
library(ggplot2)
library(dplyr)
gapminder |>
filter(country == "Australia") |>
ggplot(aes(x = lifeExp,
y = year)) +
geom_point()
```
````
Which would produce the following output
```{r}
#| label: gg-oz-gapminder
#| fig-cap: Life expectancy from 1952 - 2007 for Australia. Life expentancy increases
#| steadily except from 1962 to 1969. We can safely say that our life expectancy is
#| higher than it has ever been!
library(ggplot2)
library(dplyr)
gapminder |>
filter(country == "Australia") |>
ggplot(aes(x = lifeExp,
y = year)) +
geom_point()
```
:::
::: {.callout-note title="Your Turn"}
1. Using 02-qmd-figures-chunks.qmd
1. Create a plot
1. Add a figure caption
:::
### Adding multiple (sub) figures and (sub) captions
Sometimes you want to add multiple figures that are linked, or slightly different views of similar data and then reference them as Figure 1A and Figure 1B. You can do this with `layout-ncol` and `fig-cap`, and reference the figures with `@fig-<chunk-name>-1` `@fig-<chunk-name>-2`. For example:
```{r}
#| label: fig-volcanos
#| layout-ncol: 2
#| echo: fenced
#| fig-cap:
#| - "An image plot of Auckland's Maunga Whau Volcano"
#| - "A contour plot of Auckland's Maunga Whau Volcano"
image(volcano)
contour(volcano)
```
We can see the image plot as (`@fig-volcanos-1`) @fig-volcanos-1 and the contour plot as `@fig-volcanos-2` @fig-volcanos-2.
For more information on this see <https://quarto.org/docs/authoring/figures.html#layout> and <https://quarto.org/docs/authoring/cross-references.html>
## Inserting images
We cannot always generate the graphics that we want - for example, we might have an image of something that we want to show, or perhaps a nice flowchart someone else made.
In our case, say we wanted to insert the Statistical Society of Australia logo into our document, there are two ways we can do this.
1. With `markdown` syntax
1. with `knitr::include_graphics()`
**Markdown syntax**
The markdown syntax to insert an image is: `{options}`
:::: {.callout-tip title="Demo: inserting a logo"}
So we could insert the new SSA vic logo by doing the following:
````{markdown}
```

```
````
Which would give us the following output:

But say that we want more control over the output, like we want to center the image, and we want to make it smaller? Then you can use `knitr::include_graphics()`, and control the figure alignment using the options fig-align, and add a caption with `fig-cap`.
````{markdown}
```{r}
#| label: ssa-logo
#| fig-align: center
#| fig-cap: "The new SSA logo, which is actually a scatterplot, which is super neat!"
knitr::include_graphics(here::here("figs", "ssa-logo.png"))
```
````
```{r}
#| label: ssa-logo
#| fig-align: center
#| out-width: 25%
#| fig-cap: The new SSA logo, which is actually a scatterplot, which is super neat!
knitr::include_graphics(here::here("figs", "ssa-logo.png"))
```
::: {.callout-caution title="Controlling image output with css" collapse="true"}
You can control more features of figures, e.g., sizing, alignment, alt text, etc., by using CSS type styling, which you can read more about here: <https://quarto.org/docs/authoring/figures.html#figure-sizing`>
:::
::::
::: {.callout-note title="Your Turn"}
1. Download [the gapminder logo](https://www.gapminder.org/wp-content/themes/gapminder2/images/gapminder-logo.svg)
1. Put it into a new directory called "figs" (at the top level)
1. Insert the image into your "02-qmd-figures-chunks.qmd" Quarto document around where you introduce gapminder.
1. Try using both markdown `![]()` syntax, and `knitr::include_graphics()`.
1. Hint: Remember to refer to the image in the right spot using `here`!
:::
## Summary
We've now learned how to insert tables, plots, and images into our documents!
<!-- - `pander` -->
<!-- - `xtable` -->
<!-- - `kableExtra` -->
<!-- - the list goes on! -->
<!-- - https://github.com/ropenscilabs/packagemetrics -->
<!-- - https://ropensci.org/blog/blog/2017/06/27/packagemetrics -->