---
title: "Tutorial: inline_text"
date: "Last Updated: January 16, 2020"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteEncoding{UTF-8}
  %\VignetteIndexEntry{Tutorial: inline_text}
  %\VignetteEngine{knitr::rmarkdown}
  chunk_output_type: console
---

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

## 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.

This vignette will walk a reader through the `inline_text()` function, and the various functions available to modify and make additions. The `inline.text()` function works with tables made using `tbl_summary()`, `tbl_regression()`, `tbl_uvregression()`, and `tbl_survival()`. 

## Setup

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

```{r}
library(gtsummary)
library(dplyr)
```

## 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), [`tbl_uvregression()`](http://www.danieldsjoberg.com/gtsummary/reference/tbl_uvregression.html), and [`tbl_survival()`](http://www.danieldsjoberg.com/gtsummary/reference/tbl_survival.survfit.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.

    {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

> 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).
