---
title: "gtsummary themes"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{gtsummary themes}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  warning = FALSE,
  comment = "#>"
)
```

It's possible to set themes in {gtsummary}.
The themes control many aspects of how a table is printed.
Function defaults can be controlled with themes, as well as other aspects that are not modifiable with function arguments.

The {gtsummary} package comes with a few themes.
Our focus is tables that are ready for publication and encourage themes that assist in that process; for example, the `theme_gtsummary_journal(journal = "jama")` theme sets defaults that align with the [published guidelines](https://jamanetwork.com/journals/jama/pages/instructions-for-authors#SecTables) from the *Journal of the American Medical Association*---*JAMA*.
The defaults in {gtsummary} were written to align with the reporting guidelines for *European Urology*, *The Journal of Urology*, *Urology*, and the *British Journal of Urology International*.

## Setting Themes

To set a pre-defined theme, simply include the theme function in a script or the R console.

```r
theme_gtsummary_journal(journal = "jama")
```

Use the `set_gtsummary_theme()` function to set user-defined themes (more on that below).

```r
set_gtsummary_theme(my_custom_theme)
```

Themes must be set before you create the {gtsummary} tables.
Let's take a look at the default table, comparing data between treatment groups.

#### Default Theme

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

trial |> 
  tbl_summary(by = trt, include = c(age, grade)) |> 
  add_p()
```

#### JAMA Theme

Now, the same code with the JAMA theme.

```{r, message=TRUE}
theme_gtsummary_journal(journal = "jama")
```

```{r, message=FALSE, echo=FALSE}
trial |> 
  tbl_summary(by = trt, include = c(age, grade)) |> 
  add_p()
```

By setting the theme, we were able to change the default formatting for the p-value and add a dash between the 25th and 75th percentiles.

#### JAMA + Compact Theme

Themes can be stacked as well.
In the example below, the JAMA theme and the compact theme (reduces font size and cell padding) are both called and both themes are utilized.

```{r, message=TRUE}
theme_gtsummary_journal(journal = "jama")
theme_gtsummary_compact()
```

```{r, message=FALSE, echo=FALSE}
trial |> 
  tbl_summary(by = trt, include = c(age, grade)) |> 
  add_p()
```

#### JAMA + Compact + Language Theme

All {gtsummary} tables can be translated into another language using `theme_gtsummary_language()`!

```{r, message=FALSE, echo = FALSE}
set_gtsummary_theme(theme_gtsummary_journal(journal = "jama"))
set_gtsummary_theme(theme_gtsummary_compact())
set_gtsummary_theme(theme_gtsummary_language("es"))
```

```{r, message=FALSE, echo=FALSE}
trial |> 
  tbl_summary(by = trt, include = c(age, grade)) |> 
  add_p()
```

*Clear all previously set themes using* `reset_gtsummary_theme()`.

```{r}
reset_gtsummary_theme()
```

## Writing Themes

### Theme Structure

There are many parts of a {gtsummary} table that may be controlled with theme elements.
To construct a personalized theme, create a named list of at least one theme element.
Here's an example of a theme that modifies the function that styles p-values and updates the default statistics reported in `tbl_summary()`.

```{r}
my_theme <-
  list(
    # round large p-values to two places
    "pkgwide-fn:pvalue_fun" = label_style_pvalue(digits = 2),
    "pkgwide-fn:prependpvalue_fun" = label_style_pvalue(digits = 2, prepend_p = TRUE),
    # report median (Q1 - Q2) and n (percent) as default stats in `tbl_summary()`
    "tbl_summary-arg:statistic" = list(all_continuous() ~ "{median} ({p25} - {p75})",
                                       all_categorical() ~ "{n} ({p})")
  )
```

Once you create the theme, first check the structure using `check_gtsummary_theme()`.
Then apply or set the theme with `set_gtsummary_theme()`.

```{r, eval=FALSE}
set_gtsummary_theme(my_theme)
```

### Theme Elements

Each theme element follows a naming structure: `"<function name>-<input type>:<description>"`.
The function name is the function the change applies to, the input type specifies class or type of the theme element, and the description is brief text characterizing the theme element.

Theme elements fall into two categories. 
The first is modifying internal behavior of the functions that is not directly controllable by function arguments.

```{r, echo=FALSE}
gtsummary:::df_theme_elements %>%
  dplyr::filter(argument == FALSE, deprecated == FALSE) %>%
  dplyr::select(-argument, -deprecated) %>%
  dplyr::mutate(
    name = ifelse(!is.na(name), glue::glue("`{name}`"), NA_character_),
    example = ifelse(!is.na(example), glue::glue("`{example}`"), NA_character_)
  ) %>%
  dplyr::group_by(fn) %>%
  dplyr::arrange(dplyr::desc(fn == "Package-wide")) %>%
  gt::gt() %>%
  gt::cols_align(columns = everything(), align = "left") %>%
  gt::cols_label(
    name = "Theme Element", desc = "Description",
    example = "Example"
  ) %>%
  gt::fmt_markdown(columns = c(name, desc, example)) %>%
  gt::sub_missing(columns = everything(), missing_text = "") %>%
  gt::tab_options(
    table.font.size = "small",
    data_row.padding = gt::px(1),
    row_group.padding = gt::px(1)
  )
```

The second type of theme elements set function argument defaults.
The values of these theme elements must align with the functions' accepted input for the argument.

```{r, echo=FALSE}
gtsummary:::df_theme_elements %>%
  dplyr::filter(argument == TRUE, deprecated == FALSE) %>%
  dplyr::select(fn, name) %>%
  dplyr::group_by(fn) %>%
  dplyr::mutate(arg_list = paste0("`", name, "`", collapse = ", ")) %>%
  dplyr::select(fn, arg_list) %>%
  dplyr::distinct() %>%
  gt::gt() %>%
  gt::cols_label(arg_list = "Theme Element") %>%
  gt::fmt_markdown(columns = c(arg_list)) %>%
  gt::tab_options(
    table.font.size = "small",
    data_row.padding = gt::px(1),
    row_group.padding = gt::px(1)
  )
```