gt-summary.Rmd

---
title: "Overview of using `gtsummary`"
output: html_document
---

### Example taken from [`gtsummary` vignette](http://www.danieldsjoberg.com/gtsummary/articles/inline_text.html)

## Introduction

**Reproducible reports** are an important part of good practices.  We often need to report the **results from a table** in the text of an R markdown report.
**Inline reporting** has been made simple with [`inline_text()`](http://www.danieldsjoberg.com/gtsummary/reference/inline_text.tbl_summary.html).
The `inline_text()` function reports statistics from {gtsummary} tables inline in an [R markdown](https://rmarkdown.rstudio.com/lesson-1.html) report.

## Setup

Before going through the tutorial, install and load {gtsummary}.

```{r message = FALSE, warning=FALSE}
# install.packages("gtsummary")
library(gtsummary)
```


## Example data set

We'll be using the [`trial`](http://www.danieldsjoberg.com/gtsummary/reference/trial.html) data set throughout this example.

* This set contains data from `r nrow(trial)` patients who received one of two types of chemotherapy (Drug A or Drug B).
The outcomes are tumor response and death.

For brevity in the tutorial, let's keep a subset of the variables from the trial data set.

```{r}
trial2 <-
  trial %>%
  select(trt, marker, stage)
```


## Inline results from tbl_summary() {#inline_text_tbl_summary}

First create a basic summary table using [`tbl_summary()`](http://www.danieldsjoberg.com/gtsummary/reference/tbl_summary.html) (review [`tbl_summary()` vignette](http://www.danieldsjoberg.com/gtsummary/articles/tbl_summary.html) for detailed overview of this function if needed).

```{r}
tab1 <- tbl_summary(trial2, by = trt)
tab1
```

To report the median (IQR) of the marker levels in each group, use the following commands inline.

> The median (IQR) marker level in the Drug A and Drug B groups are `` `r
inline_text(tab1, variable = marker, column = "Drug A")` `` and `` `r
inline_text(tab1, variable = marker, column = "Drug B")` ``, respectively.
Here's how the line will appear in your report.

> The median (IQR) marker level in the Drug A and Drug B groups are `r inline_text(tab1, variable = marker, column = "Drug A")` and `r inline_text(tab1, variable = marker, column = "Drug B")`, respectively.
If you display a statistic from a categorical variable, include the `level` argument.


> `` `r
inline_text(tab1, variable = stage, level = "T1", column = "Drug B")` `` resolves to "`r inline_text(tab1, variable = stage, level = "T1", column = "Drug B")`"



## Inline results from tbl_regression() {#inline_text_tbl_regression}

Similar syntax is used to report results from [`tbl_regression()`](http://www.danieldsjoberg.com/gtsummary/reference/tbl_regression.html) and [`tbl_uvregression()`](http://www.danieldsjoberg.com/gtsummary/reference/tbl_uvregression.html) tables.
Refer to the [`tbl_regression()` vignette](http://www.danieldsjoberg.com/gtsummary/articles/tbl_regression.html) if you need detailed guidance on using these functions. 

Let's first create a regression model.

```{r}
# build logistic regression model
m1 <- glm(response ~ age + stage, trial, family = binomial(link = "logit"))
```

Now summarize the results with `tbl_regression()`; exponentiate to get the odds ratios.
```{r}
tbl_m1 <- tbl_regression(m1, exponentiate = TRUE)
tbl_m1
```

To report the result for `age`, use the following commands inline.

> `` `r
inline_text(tbl_m1, variable = age)` `` 
Here's how the line will appear in your report.

> `r inline_text(tbl_m1, variable = age)`
It is reasonable that you'll need to modify the text.
To do this, use the `pattern` argument.
The `pattern` argument syntax follows `glue::glue()` format with referenced R objects being inserted between curly brackets.
The default is `pattern = "{estimate} ({conf.level*100}% CI {conf.low}, {conf.high}; {p.value})"`.  You have access the to following fields within the `pattern` argument.

```{r, echo = FALSE}
tibble::tribble(
  ~Parameter,       ~Description,
  "`{estimate}`",   "primary estimate (e.g. model coefficient, odds ratio)",
  "`{conf.low}`",   "lower limit of confidence interval",
  "`{conf.high}`",  "upper limit of confidence interval",
  "`{p.value}`",    "p-value",
  "`{conf.level}`", "confidence level of interval",
  "`{N}`",          "number of observations"  
) %>%
  gt::gt() %>%
  gt::fmt_markdown(columns = c(Parameter))
```

> Age was not significantly associated with tumor response `` `r
inline_text(tbl_m1, variable = age, pattern = "(OR {estimate}; 95% CI {conf.low}, {conf.high}; {p.value})")` ``.
> Age was not significantly associated with tumor response `r inline_text(tbl_m1, variable = age, pattern = "(OR {estimate}; 95% CI {conf.low}, {conf.high}; {p.value})")`.
If you're printing results from a categorical variable, include the `level` argument, e.g. `inline_text(tbl_m1, variable = stage, level = "T3")` resolves to "`r inline_text(tbl_m1, variable = stage, level = "T3")`".  

The `inline_text` function has arguments for rounding the p-value (`pvalue_fun`) and the coefficients and confidence interval (`estimate_fun`).
These default to the same rounding performed in the table, but can be modified when reporting inline.

For more details about inline code, review to the  [RStudio documentation page](https://rmarkdown.rstudio.com/lesson-4.html).