04-tables.Rmd

---
output:
  #bookdown::html_document2: default
  #bookdown::word_document2: default
  bookdown::pdf_document2:
    template: templates/template.tex
    keep_tex: true
documentclass: book
#bibliography: [bibliography/references.bib, bibliography/additional-references.bib]
---

# Tables {#tables} 
\minitoc <!-- this will include a mini table of contents-->

## Making LaTeX tables play nice
Dealing with tables in LaTeX can be painful.
This section explains the main tricks you need to make the pain go away.

(Note: if you are looking at the ebook version, you will not see much difference in this section, as it is only relevant for PDF output!)

### Making your table pretty
When you use `kable` to create tables, you will almost certainly want to set the option `booktabs = TRUE`.
This makes your table look a million times better:

```{r, message=FALSE}
library(knitr)
library(tidyverse)

head(mtcars) %>% 
  kable(booktabs = TRUE)
```

\vspace{4mm}

Compare this to the default style, which looks terrible:


```{r}
head(mtcars) %>% 
  kable()
```


### If your table is too wide
You might find that your table expands into the margins of the page, like the tables above.
Fix this with the `kable_styling` function from the [`kableExtra`](https://haozhu233.github.io/kableExtra/) package:

```{r, message=FALSE}
library(kableExtra)

head(mtcars) %>% 
  kable(booktabs = TRUE) %>% 
  kable_styling(latex_options = "scale_down")
```

This scales down the table to fit the page width.


### If your table is too long
If your table is too long to fit on a single page, set `longtable = TRUE` in the `kable` function to split the table across multiple pages.

```{r}
a_long_table <- rbind(mtcars, mtcars)

a_long_table %>% 
  select(1:8) %>% 
  kable(booktabs = TRUE, longtable = TRUE)
```

When you do this, you'll probably want to make the header repeat on new pages.
Do this with the `kable_styling` function from `kableExtra`:

```{r}
a_long_table %>% 
  kable(booktabs = TRUE, longtable = TRUE) %>% 
  kable_styling(latex_options = "repeat_header")
```

Unfortunately, we cannot use the `scale_down` option with a `longtable`. 
So if a `longtable` is too wide, you can either manually adjust the font size, or show the table in landscape layout. 
To adjust the font size, use kableExtra's `font_size` option:

```{r}
a_long_table %>% 
  kable(booktabs = TRUE, longtable = TRUE) %>% 
  kable_styling(font_size = 9, latex_options = "repeat_header")
```

To put the table in landscape mode, use kableExtra's `landscape` function:

```{r}
a_long_table %>% 
  kable(booktabs = TRUE, longtable = TRUE) %>% 
  kable_styling(latex_options = "repeat_header") %>% 
  landscape()
```

### Max power: manually adjust the raw LaTeX output {#max-power}
For total flexibility, you can adjust the raw LaTeX output from `kable`/`kableExtra` that generates the table.
Let us consider how we would do this for the example of adjusting the font size if our table is too wide:
Latex has a bunch of standard commands that set an approximate font size, as shown below in Figure \@ref(fig:latex-font-sizing).

```{r latex-font-sizing, echo=FALSE, out.width='50%', fig.cap="Font sizes in LaTeX", fig.pos="H", fig.align='center'}
knitr::include_graphics("figures/sample-content/latex_font_sizes.png")
```

You could use these to manually adjust the font size in your longtable in two steps:

1. Wrap the longtable environment in, e.g., a `scriptsize` environment, by doing a string replacement in the output from `kable`/`kableExtra`
2. Add the attributes that make R Markdown understand that the table is a table (it seems R drops these when we do the string replacement)

```{r}
our_adjusted_table <- a_long_table %>% 
  kable(booktabs = TRUE, longtable = TRUE) %>% 
  kable_styling(latex_options = "repeat_header") %>% 
  # wrap the longtable in a tiny environment
  str_replace('\\\\begin\\{longtable\\}', 
              '\\\\begin\\{scriptsize\\}\n\\\\begin\\{longtable\\}') %>%
  str_replace('\\\\end\\{longtable\\}', 
              '\\\\end\\{longtable\\}\n\\\\end\\{scriptsize\\}')

#add attributes to make R Markdown treat this as a kable LaTeX table again
our_adjusted_table %>% 
  structure(format = "latex", class = "knitr_kable")
```