Report statistics from tables inline

Extracts and returns statistics from a tbl_summary(), tbl_continuous(), tbl_cross(), tbl_survfit(), tbl_regression() or tbl_uvregression() table for inline reporting in a Quarto or R Markdown document, so the sentence "The median age was `r inline_text(tbl, variable = age, column = "Drug A")` years" updates with the data. See the inline_text() tutorial for detailed examples.

Usage

inline_text(
  x,
  variable,
  column = NULL,
  level = NULL,
  pattern = NULL,
  pvalue_fun = label_style_pvalue(prepend_p = TRUE),
  estimate_fun = NULL,
  ...
)

Arguments

x: (ltsummary)
A table created with tbl_summary(), tbl_continuous(), tbl_cross(), tbl_survfit(), tbl_regression() or tbl_uvregression(). Combined tables (tbl_stack(), tbl_merge(), tbl_strata(), tbl_strata_nested_stack()) and tables built with as_ltsummary() are also accepted: the cell is addressed by variable, level and a column of x$table_body (e.g. stat_1_2 in a merged table), or pattern is glued over the columns of the row. Those tables return the cell as the table formatted it, so pvalue_fun and estimate_fun do not apply to them.
variable: (selector)
A single variable of the table.
column: (selector)
For tbl_summary tables, the column of x$table_body to return, e.g. stat_1 or p.value. The level of the by variable can be passed instead of the column name, e.g. "Drug A". Defaults to the overall column stat_0 when the table has one.
level: (string)
For categorical variables, the level to report.
pattern: (string)
A glue-style pattern with statistic names in curly braces. For tbl_summary tables with column, the statistics computed for that cell are available, e.g. "{median} ({p25}, {p75})" or "{n}/{N} ({p}%)". Without column, the columns of the table row are available instead, e.g. "{stat_1} vs. {stat_2} ({p.value})". For a tbl_regression() or tbl_uvregression() table the columns of the row are available, plus conf.level, and the default pattern is "{estimate} ({conf.level*100}% CI {conf.low}, {conf.high}; {p.value})"; combined tables have neither the default nor conf.level, so column or pattern must be given.
pvalue_fun: (function)
Function that formats p-values in summary, cross, survival and regression tables. Default is label_style_pvalue(prepend_p = TRUE), which gives "p=0.12" and "p<0.001".
estimate_fun: (function)
For regression tables, the function that formats the estimate and confidence limits. Default is the function the table was built with.
...: Arguments of the methods for cross tables and survival tables, described below.

Value

A string.

Survival tables

For a table created with tbl_survfit(), the column is selected by its time or probability: inline_text(x, variable = NULL, level = NULL, pattern = NULL, time = NULL, prob = NULL, column = NULL, estimate_fun = x$inputs$estimate_fun, pvalue_fun = label_style_pvalue(prepend_p = TRUE)). Exactly one of time, prob and column (e.g. column = p.value) is given; variable defaults to the first model of the table. The statistics available in pattern are estimate, conf.low, conf.high, and with times also n.risk and std.error, formatted by estimate_fun; p.value is available after add_p().

Cross tables

For a table created with tbl_cross(), cells are selected by the levels of the two variables instead of variable and column: inline_text(x, col_level, row_level = NULL, pvalue_fun = label_style_pvalue(prepend_p = TRUE)). col_level is a level of the col variable, "stat_0" for the total column, or "p.value" for the p-value added by add_p(); row_level is a level of the row variable or the margin text ("Total"), and defaults to the row of the p-value.

Examples

t1 <- trial |>
  tbl_summary(by = trt, include = c(age, grade)) |>
  add_p()

# Example 1 ----------------------------------
# a cell of the table, by level of `by` or by column name
inline_text(t1, variable = age, column = "Drug A")
#> [1] "59 (51, 66)"
inline_text(t1, variable = grade, level = "I", column = stat_2)
#> [1] "37 (35%)"
inline_text(t1, variable = grade, column = "p.value")
#> [1] "p=0.3"

# Example 2 ----------------------------------
# a pattern of the statistics behind a cell
inline_text(t1, variable = grade, level = "I", column = "Drug A", pattern = "{n}/{N} ({p}%)")
#> [1] "25/95 (26%)"
inline_text(t1, variable = age, column = "Drug B", pattern = "median {median} (IQR {p25} to {p75})")
#> [1] "median 62 (IQR 54 to 71)"

# Example 3 ----------------------------------
# a pattern of the columns of a row
inline_text(t1, variable = age, pattern = "{stat_1} vs. {stat_2} ({p.value})")
#> [1] "59 (51, 66) vs. 62 (54, 71) (p=0.043)"

# Example 4 ----------------------------------
# a regression table: the estimate, interval and p-value of a term
t2 <- glm(response ~ age + grade, trial, family = binomial) |>
  tbl_regression(exponentiate = TRUE)
inline_text(t2, variable = age)
#> [1] "1.00 (95% CI 0.97, 1.03; p=0.9)"
inline_text(t2, variable = grade, level = "III", pattern = "OR {estimate}; {p.value}")
#> [1] "OR 2.45; p=0.058"

# Example 5 ----------------------------------
# a cross table: cells by level, the total row, and the p-value
t3 <- trial |>
  tbl_cross(row = trt, col = response) |>
  add_p()
inline_text(t3, row_level = "Drug A", col_level = "1")
#> [1] "22"
inline_text(t3, row_level = "Total", col_level = "1")
#> [1] "46"
inline_text(t3, col_level = "p.value")
#> [1] "p=0.7"

# Example 6 ----------------------------------
# a survival table: the estimate at a time, and the p-value
if (requireNamespace("survival", quietly = TRUE)) {
  t4 <- survival::survfit(survival::Surv(ttdeath, death) ~ trt, trial) |>
    tbl_survfit(times = c(12, 24)) |>
    add_p()
  inline_text(t4, time = 24, level = "Drug B")
  inline_text(t4, time = 24, level = "Drug B", pattern = "{estimate} [{conf.low}, {conf.high}]")
  inline_text(t4, column = p.value)
}
#> [1] "p=0.007"