stable.qmd

---
title: stable
subtitle: Create a simple table from a data frame.
---


```{r, include = FALSE}
knitr::opts_chunk$set(comment = '.')
source("global.R")
```


## Syntax

Pass your data.frame into `stable()` 

```{r, eval = FALSE}
stable(data)
```

Other formal arguments include:

- **align** to set column alignment
- **panel** to create groups of rows under a "panel" header
- **span** to group columns under a "spanner" header
- **notes** to create table notes
- **sumrows** to insert summary rows 
- **units** that get placed below the corresponding column name
- **drop** to omit certain columns from the table
- **sizes** to set different table size attributes
- **escape_fun** a function to sanitize table items

You can also pass a bunch of other arguments through `...` to further format
the table (see `?stable` for details)



## Basics

`stable()` is the name of the workhorse function that is used to turn 
data.frames into `TeX` tables. This chapter will introduce the `stable()` 
function and how to us it to create basic tables. 

To illustrate usage and features of `stable()`, we will use the `stdata` data 
set that comes with pmtables


```{r}

data <- stdata()

head(data)
```

We can turn this data frame into a `TeX` table by passing it into `stable()`. 


```{r}
out <- stable(data)

head(out, n = 10)
```

Note that we have shown the raw latex code that is generated by `stable()`. That 
is to say: the output from `stable()` is a character vector of latex code 
for the table. Note also that this character vector has a special class 
associated with it: `stable`.  That means we can write functions that recognize
this character vector as output from `stable()` and we can have those functions
process the character vector in special ways.

We can render that table in `TeX` **in the current Rmarkdown document** by
passing the text to `st_asis()`. 

```{r}
out %>% st_as_image() 
```

Remember to only call `st_asis()` when you are rendering tables inline in an 
Rmd document.  If you are sending table code to a `TeX` report, then 
you will save them to a file and then include them into your report. 

The remaining sections of this chapter will show you how to modify and 
enhance this output in the more basic ways.  We will implement separate 
chapters for more complicated table manipulations. 


## Annotate with file names

pmtables can track and annotate your table with the filenames of the 
R code that generated the table (`r_file`) as well as the output file 
where you write the the table `.tex` code (`output_file)`. 

To have pmtables annotate your table with these file names, pass them 
in with the `r_file` and `output_file` arguments

```{r}
out <- stable(
  data, 
  r_file = "tables.R", 
  output_file = "tables.tex"
)
```

When we look at the rendered table, these names will show up as annotations
at the bottom of the table

```{r}
out %>% st_as_image()
```

## Saving your stable

Saving your stable **can** be as easy as sending it into `writeLines()`

```{r}
writeLines(
  out, 
  con = tempfile(tmpdir = '.', fileext = ".tex")
)
```

But remember that we passed in the `output_file` argument to `stable()` 
and we can use that data to save the table code to the file we named 
in that argument. 

Note that our `stable` object has another attribute now called `stable_file`

```{r}
attributes(out)
```

This has the value that we passed in as `output_file`. To save our table 
to `stable_file`, we call `stable_save()`

```{r}
stable_save(out)
```

There is a `dir` argument to `stable_save()` that we can use to to select
the directory where the file will be saved

```{r}
stable_save(out, dir = tempdir())
```

And if you look at the default value for `dir` in `?stable_save`, you'll 
see that this is associated with an option called `pmtables.dir`;  you 
can set that option to your default output directory and your tables 
will be saved there until you change that

```{r, eval=FALSE}
options(pmtables.dir = tempdir())

stable_save(out)
```

```{r, include = FALSE}
options(pmtables.dir = NULL)
```


## Align columns

Use the `align` argument to align column data to the left, center or right. Use
a `cols_*` function to specify the default alignment for all columns

```{r}
tmp <- tibble(AB = 1, CDEFGHIJ = 2, KL = 3)

stable(tmp, align = cols_center()) %>% st_as_image()
```

You can pass in exceptions to the default

```{r}
stable(tmp, align = cols_center(CDEFGHIJ = "r")) %>% 
  st_as_image()
```

Or you can pass an alignment directive and the columns that are bound by that 
directive

```{r}
stable(tmp, align = cols_center(.l = "AB,KL")) %>% 
  st_as_image()
```

A special directive called `.outer` lets you specify the alignment of the first
and last column in the table. For example, this code puts the first column to 
the left and the last column to the right.

```{r}
stable(tmp, align = cols_center(.outer = "lr")) %>% 
  st_as_image()
```

### Fixed column widths

Use `col_ragged(size)` to force a column to be a fixed size. 

```{r}
stable(tmp, align = cols_center(AB = col_ragged(2))) %>% 
  st_as_image()
```

By default, the unit is `cm` so that the first column (`AB`) has a width 
of 2 cm regardless of the contents. 

See `cols_align()` help topic for more information and argument descriptions.


## Manipulating columns and names

### Rename columns

You can change the name that appears in the rendered table with `cols_rename`

```{r}
data %>% 
  slice(1:3) %>% 
  stable(cols_rename = c(Age = "AGE", Weight = "WT")) %>%
  st_as_image()
```

Note that the rename syntax follows the tidyselect convention of putting the 
new name on the left and the old name on the right.

### Hide a column name 

You can also "erase" the name of a column in the output

```{r}
data %>% 
  slice(1:3) %>% 
  stable(cols_blank = "WT,ALB,SCR") %>% 
  st_as_image()
```

### Don't print any table header information

```{r}
data %>% 
  slice(1:3) %>% 
  stable(cols_omit = TRUE) %>% 
  st_as_image()
```


### Unmask column names

In tibbles, you can't have duplicate column names.  The `cols_split` argument
lets you unmask the names when duplicate names are prefixed with a tag and 
a delimiter

```{r}
tmp <- tibble(a.A = 1, b.A = 2, c.A = 3)
```

```{r}
stable(tmp, cols_split = '.') %>% 
  st_as_image()
```


### Make column names bold

```{r}
data %>% 
  slice(1:2) %>% 
  stable(cols_bold = TRUE) %>% 
  st_as_image()
```


### Drop a column from the table

If we want to prevent a column from appearing in the output table (e.g. 
`FORM`)

```{r}
head(data)
```

list the column name as `drop`

```{r}
stable(data, drop = "FORM") %>% st_as_image()
```

Of course some tidyverse could accomplish the same thing

```{r, eval = FALSE}
data %>% select(-FORM) %>% stable() 
```


## Other customizations

### Notes

Arbitrary notes can get added to any table using the `notes` argument. 

```{r}
data %>% 
  slice(1:3) %>% 
  stable(notes = "Showing just the first three rows") %>% 
  st_as_image()
```

The appearance of the notes can be controlled by calling `noteconf()` and 
passing the result as `note_config`. See `?tab_notes()` for more details.


### Units

pmtables can automatically place units underneath the appropriate column. To 
do this, generate a list with names that match the column names you want to 
label with units. 

```{r}
u <- list(
  WT = "kg", CRCL = "ml/min", AGE = "year", ALB = "g/dL", 
  SCR = "mg\\%"
) %>% map(~paste0("(", .x, ")"))
```

Then pass that list as `units` to `stable()`

```{r}
stable(data, units = u) %>% st_as_image()
```

### Multi-line column headers

If the column header is long, you can break it across multiple lines.  By 
default, use `...`  in the column name

```{r}
tibble(`First line ... Second line` = 123456789) %>% 
  stable() %>% 
  st_as_image()
```

The break can be introduced through the rename mechanism

```{r}
tibble(a = 1) %>% 
  stable(cols_rename =  c(`First ... Second` = "a")) %>% 
  st_as_image()
```

Look at the `?tab_cols` help topic for the `cols_break` argument; this 
lets you change the character sequence used for the break. 


### Insert horizontal lines

Pass `hlines_at` to insert horizontal lines above specific rows.  This can 
be either logical vector with the same length as the number of rows in the 
table or a vector of integers.

```{r}
stable(stdata(), hline_at = c(3,5)) %>% 
  st_as_image()
```

or 

```{r}
stable(stdata(), hline_at = data$FORM == "tablet") %>% st_as_image()
```


Pass `hlines_from` to derive hline locations based on non-repeating values 
in a table column. Notice how this behaves. 

```{r}
stable(stdata(), hline_from = "DOSE") %>% 
  st_as_image()
```


See the `?tab_hlines` help topic for more info. See also `st_hline()` for 
the pipe equivalent with additional feature.


### Clear replicate values

You can create groups in a table by "clearing" replicate values

```{r}
stable(stdata(), clear_reps = "STUDY") %>% 
  st_as_image()
```

This can be combined with an hline

```{r}
stable(
  stdata(), 
  clear_reps = "STUDY", 
  hline_from = "STUDY"
) %>% st_as_image()
```

See `?tab_clear_reps` for other options, including an option for clearing
based on several grouping variables.