--- title: "inline_text() tutorial" date: "Last Updated: September 13, 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, warning = FALSE, comment = "#>" ) gt_compact_fun <- function(x) { gt::tab_options(x, table.font.size = "small", data_row.padding = gt::px(1), summary_row.padding = gt::px(1), grand_summary_row.padding = gt::px(1), footnotes.padding = gt::px(1), source_notes.padding = gt::px(1), row_group.padding = gt::px(1) ) } ``` ```{r, echo = FALSE, results = 'asis'} # we do NOT want the vignette to build on CRAN...it's taking too long if (!identical(Sys.getenv("IN_PKGDOWN"), "true") && !tolower(as.list(Sys.info())$user) %in% c("sjobergd", "currym", "whitingk", "whiting")) { msg <- paste( "View this vignette on the", "[package website](https://www.danieldsjoberg.com/gtsummary/articles/inline_text.html)." ) cat(msg) knitr::knit_exit() } ``` ## 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()`](https://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`](https://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()`](https://www.danieldsjoberg.com/gtsummary/reference/tbl_summary.html) (review [`tbl_summary()` vignette](https://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()`](https://www.danieldsjoberg.com/gtsummary/reference/tbl_regression.html) and [`tbl_uvregression()`](https://www.danieldsjoberg.com/gtsummary/reference/tbl_uvregression.html) tables. Refer to the [`tbl_regression()` vignette](https://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} dplyr::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)) %>% gt_compact_fun() ``` > 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).