[Experimental] Add significance stars to estimates with small p-values

add_significance_stars(
  x,
  pattern = NULL,
  thresholds = c(0.001, 0.01, 0.05),
  hide_ci = TRUE,
  hide_p = inherits(x, c("tbl_regression", "tbl_uvregression")),
  hide_se = FALSE
)

Arguments

x

a 'gtsummary' object with a 'p.value' column

pattern

glue-syntax string indicating what to display in formatted column. Default is "{estimate}{stars}" for regression summaries and "{p.value}{stars}" otherwise. A footnote is placed on the first column listed in the pattern. Other common patterns are "{estimate}{stars} ({conf.low}, {conf.high})" and "{estimate} ({conf.low} to {conf.high}){stars}"

thresholds

thresholds for significance stars. Default is c(0.001, 0.01, 0.05)

hide_ci

logical whether to hide confidence interval. Default is TRUE

hide_p

logical whether to hide p-value. Default is TRUE for regression summaries, and FALSE otherwise.

hide_se

logical whether to hide standard error. Default is FALSE

Future Updates

There are planned updates to the implementation of this function with respect to the pattern= argument. Currently, this function replaces the numeric estimate column, with a formatted character column following pattern=. Once gt::cols_merge() gains the rows= argument the implementation will be updated to use it, which will keep numeric columns numeric. For the vast majority of users, the planned change will be go unnoticed.

Example Output

Example 1

image of rendered example table

Example 2

image of rendered example table

Example 3

image of rendered example table

Example 4

image of rendered example table

Examples

# \donttest{
tbl <-
  lm(time ~ ph.ecog + sex, survival::lung) %>%
  tbl_regression(label = list(ph.ecog = "ECOG Score", sex = "Sex"))

# Example 1 ----------------------------------
add_significance_stars_ex1 <-
  tbl %>%
  add_significance_stars(hide_ci = FALSE, hide_p = FALSE)

# Example 2 ----------------------------------
add_significance_stars_ex2 <-
  tbl %>%
  add_significance_stars(
    pattern = "{estimate} ({conf.low}, {conf.high}){stars}",
    hide_ci = TRUE, hide_se = TRUE
  ) %>%
  modify_header(estimate ~ "**Beta (95% CI)**") %>%
  modify_footnote(estimate ~ "CI = Confidence Interval", abbreviation = TRUE)

# Example 3 ----------------------------------
# Use '  \n' to put a line break between beta and SE
add_significance_stars_ex3 <-
  tbl %>%
  add_significance_stars(
    hide_se = TRUE,
    pattern = "{estimate}{stars}  \n({std.error})"
  ) %>%
  modify_header(estimate ~ "**Beta  \n(SE)**") %>%
  modify_footnote(estimate ~ "SE = Standard Error", abbreviation = TRUE) %>%
  as_gt() %>%
  gt::fmt_markdown(columns = everything()) %>%
  gt::tab_style(
    style = "vertical-align:top",
    locations = gt::cells_body(columns = label)
  )

# Example 4 ----------------------------------
add_significance_stars_ex4 <-
  lm(marker ~ stage + grade, data = trial) %>%
  tbl_regression() %>%
  add_global_p() %>%
  add_significance_stars(
    hide_p = FALSE,
    pattern = "{p.value}{stars}"
  ) %>%
  as_gt() %>%
  gt::tab_style(
    style = "vertical-align:top",
    locations = gt::cells_body(columns = label)
  )
# }