cite-fig-tab-sec.Rmd

# Citing Figures, Tables & Sections {#start}

When you're writing a report, you often refer to a table or figure in text. 

```{r no-show, include = FALSE, message = FALSE}
gapminder <- readr::read_csv(here::here("data", "gapminder.csv"))
```

> Australia's life expectancy has increased a great deal over the past 50 years (Figure 1)

```{r example-gg-oz-gap, echo = FALSE, message = FALSE}
library(ggplot2)
library(dplyr)
gapminder %>%
  filter(country == "Australia") %>%
  ggplot(aes(x = year,
             y = lifeExp)) + 
  geom_point()
```

_Figure 1. Life expectancy from 1952 - 2007 for Australia. Life expectancy increases steadily except from 1962 to 1969. We can safely say that our life expectancy is higher than it has ever been!_

And sure, this is figure 1.
But what happens if actually, that figure should be moved later in the paper?
You need to do the following:

1. Update the reference to figure 1 in the text. 
1. Update the figure 1 caption to not say figure 1.

This is fine. 

Once. 

But it is never once. After this, it is frustrating, and error prone.

There is a way to solve this, which this lesson discusses.

## Overview

* **Teaching** 10 minutes
* **Exercises** 15 minutes

## Questions

* How do I refer to the table or figure in text and link to it?

## Objectives

* Link to tables or figures in text.

## How to refer to tables and figures in text? {.demo}

In order to use this referencing style, you must use the following in the YAML

```
output:
  bookdown::pdf_document2
```

Or for HTML:

```
output:
  bookdown::html_document2
```

Or for word:

```
output:
  bookdown::word_document2
```

This is a new version of document that supports a better way to reference things in text.
This reads as:

> Make the output the HTML/PDF/Word document from the bookdown package.

That is, the special `::` after `bookdown`, `bookdown::html_document2` read as "The html_document2 function from the bookdown package".

## Your Turn {.exercise}

1. Convert your output to use `bookdown::html_document2` in your YAML.

## Referencing a figure

To refer to a figure, you write the following in your text:

`Figure \@ref(fig:chunk-name)`

### Demo {.demo}

````markdown
`r ''````{r gg-oz-plot, 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 = year,
             y = lifeExp)) + 
  geom_point()
```

Australia's life expectancy has increased a great deal over the past 50 years

(See Figure \@ref(fig:gg-oz-plot))

````

```{r gg-oz-plot, fig.cap = "Life expectancy from 1952 - 2007 for Australia. Life expectancy 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 = year,
             y = lifeExp)) + 
  geom_point()
```

Australia's life expectancy has increased a great deal over the past 50 years (See Figure \@ref(fig:gg-oz-plot))

### Your Turn {.exercise}

1. Add a new plot in your document and reference it

## Referencing a table

To cite a table, you write the following:

`Table \@ref(tab:chunk-name)`

````markdown
`r ''````{r gg-oz-tab}
gapminder %>%
  filter(country == "Australia") %>%
  knitr::kable(caption = "Raw gapminder data for Australia.")
```
````

We can see below in Table \@ref(tab:gg-oz-tab) the raw data used to create Figure \@ref(fig:gg-oz-plot)).

```{r gg-oz-tab}
gapminder %>%
  filter(country == "Australia") %>%
  knitr::kable(caption = "Raw gapminder data for Australia.")
```

### Your Turn {.exercise}

1. Create a table in your document and refer to it in text

## Referencing a section

You can even reference a section in your report:

`\@ref(slug)`

However, in order to write this, you need to include `slug` in your markdown header, like so:

```
## your amazing header {#slug}
```

For example, I can refer to the first section (Section \@ref(start)) in this document by referring to the section as 

`\@ref(start)`

because it was written as:

```
# Citing Figures, Tables & Sections {#start}
```

**One note here - your slug can not start with a number**. Otherwise, it will print out the slug. So the following would not work:

```
## 10 rules {#10-rules}
```

You should instead write:

```
## 10 rules {#ten-rules}
```

### Your Turn {.exercise}

1. Reference a section in the report.

## One small note

If you are using a template of some kind, such as those in `rticles`, and want the full featured citation features, then your YAML will need to include something like this:

```yaml
output:
  bookdown::pdf_book:
    base_format: rticles::plos_article
```