Merge branch 'v2.0' into v2.0-TODO

DESCRIPTION

@@ -92,7 +92,7 @@ Remotes:
     github::insightsengineering/cards,
     github::insightsengineering/cardx@svy-ard_categorical_unit_tests
 Config/Needs/check: broom, broom.helpers, broom.mixed, lme4, effectsize,
-    emmeans, smd
+    emmeans, smd, forcats, scales
 Config/testthat/edition: 3
 Config/testthat/parallel: true
 Encoding: UTF-8

NEWS.md

@@ -46,6 +46,8 @@
 
 #### Internal Updates
 
+* The "FAQ+Gallery", `tbl_summary()` Tutorial, `tbl_regression()`, and Quarto+R Markdown vignettes have been converted to articles. The URLs on the website have not changed for these pages, but the vignettes are no longer is bundled in the package. This change allows us to provide better documentation utilizing more tools that don't need to be bundled with the package.  
+
 * Greater consistency has been put in place for all calculated statistics in gtsummary. Previously, each function handled its own calculations and transforming these statistics into data frames that would be printed. Now each function will first prepare an Analysis Result Dataset (ARD), and ARDs are converted to gtsummary structures using bridge functions (prefixed with `brdg_*()`). The bridge functions will be exported to allow anyone to more easily extend gtsummary functions.
 
 ### Bug Fixes 

R/add_overall.R

@@ -1,40 +1,26 @@
-#' Add overall column
-#'
-#' - [`add_overall.tbl_summary()`]
-#'
-#' @param x (`gtsummary`)\cr
-#'   Object with class 'gtsummary'
-#' @param ... Passed to other methods.
-#' @keywords internal
-#' @author Daniel D. Sjoberg
-#' @export
-#'
-#' @seealso [`add_overall.tbl_summary()`]
-add_overall <- function(x, ...) {
-  check_not_missing(x)
-  check_class(x, "gtsummary")
-  UseMethod("add_overall")
-}
-
 #' Add overall column
 #'
 #' Adds a column with overall summary statistics to tables
-#' created by `tbl_summary`, `tbl_svysummary`, `tbl_continuous` or
-#' `tbl_custom_summary`.
+#' created by `tbl_summary()`, `tbl_svysummary()`, `tbl_continuous()` or
+#' `tbl_custom_summary()`.
 #'
-#' @param x (`tbl_summary`/`tbl_svysummary`/`tbl_continuous`/`tbl_custom_summary`)\cr
+#' @param x (`tbl_summary`, `tbl_svysummary`, `tbl_continuous`, `tbl_custom_summary`)\cr
 #'   A stratified 'gtsummary' table
-#' @param last Logical indicator to display overall column last in table.
-#' Default is `FALSE`, which will display overall column first.
-#' @param col_label String indicating the column label. Default is `"**Overall**  \nN = {N}"`
-#' @param statistic Override the statistic argument in initial `tbl_*` function.
-#' call. Default is `NULL`.
-#' @param digits Override the digits argument in initial `tbl_*` function
-#' call. Default is `NULL`.
+#' @param last (scalar `logical`)\cr
+#'   Logical indicator to display overall column last in table.
+#'   Default is `FALSE`, which will display overall column first.
+#' @param col_label (`string`)\cr
+#'   String indicating the column label. Default is `"**Overall**  \nN = {style_number(N)}"`
+#' @param statistic ([`formula-list-selector`][syntax])\cr
+#'   Override the statistic argument in initial `tbl_*` function
+#'   call. Default is `NULL`.
+#' @param digits ([`formula-list-selector`][syntax])\cr
+#'   Override the digits argument in initial `tbl_*` function
+#'   call. Default is `NULL`.
 #' @inheritParams rlang::args_dots_empty
 #'
 #' @author Daniel D. Sjoberg
-#' @export
+#' @name add_overall
 #' @return A `gtsummary` of same class as `x`
 #' @examples
 #' # Example 1 ----------------------------------
@@ -65,14 +51,26 @@ add_overall <- function(x, ...) {
 #'     include = grade
 #'   ) |>
 #'   add_overall(last = TRUE)
-add_overall.tbl_summary <- function(x, last = FALSE, col_label = "**Overall**  \nN = {N}",
+NULL
+
+#' @rdname add_overall
+#' @export
+add_overall <- function(x, ...) {
+  check_not_missing(x)
+  check_class(x, "gtsummary")
+  UseMethod("add_overall")
+}
+
+#' @rdname add_overall
+#' @export
+add_overall.tbl_summary <- function(x, last = FALSE, col_label = "**Overall**  \nN = {style_number(N)}",
                                     statistic = NULL, digits = NULL, ...) {
   set_cli_abort_call()
   check_dots_empty()
 
   # translating the col_label, if nothing passed by user
   if (missing(col_label)) {
-    paste0("**", translate_string("Overall"), "**  \nN = {N}")
+    paste0("**", translate_string("Overall"), "**  \nN = {style_number(N)}")
   }
 
   add_overall_generic(
@@ -191,10 +189,8 @@ add_overall_merge <- function(x, tbl_overall, last, col_label, calling_fun) {
         dplyr::filter(.data$column %in% "stat_0")
     )
 
-  # Add
+  # Add header to overall column
   x <- modify_header(x, stat_0 = col_label)
 
-
-
   x
 }

R/custom_tidiers.R

@@ -27,8 +27,7 @@
 #' The tidier uses the output from `parameters::model_parameters()`, and
 #' merely takes the result and puts it in `broom::tidy()` format. To use this
 #' function with `tbl_regression()`, pass a function with the arguments for
-#' `tidy_robust()` populated. This is easily done using `purrr::partial()` e.g.
-#' `tbl_regression(tidy_fun = partial(tidy_robust, vcov = "CL"))`
+#' `tidy_robust()` populated.
 #'
 #' - `pool_and_tidy_mice()` tidier to report models resulting from multiply imputed data
 #' using the mice package. Pass the mice model object *before* the model results

inst/CITATION

@@ -0,0 +1,20 @@
+citHeader("To cite gtsummary in publications use:")
+
+bibentry(
+  bibtype     = "Article",
+  key         = "gtsummary",
+  author      = c(person("Daniel D.", "Sjoberg"),
+                  person("Karissa", "Whiting"),
+                  person("Michael", "Curry"),
+                  person("Jessica A.", "Lavery"),
+                  person("Joseph", "Larmarange")),
+  title       = "Reproducible Summary Tables with the gtsummary Package",
+  journal     = "{The R Journal}",
+  year        = "2021",
+  url         = "https://doi.org/10.32614/RJ-2021-053",
+  doi         = "10.32614/RJ-2021-053",
+  volume      = "13",
+  issue       = "1",
+  pages       = "570-580",
+  textVersion = 'Sjoberg DD, Whiting K, Curry M, Lavery JA, Larmarange J. Reproducible summary tables with the gtsummary package. The R Journal 2021;13:570–80. https://doi.org/10.32614/RJ-2021-053.'
+)

inst/WORDLIST

@@ -0,0 +1,94 @@
+ANCOVA
+Biostatistics
+CMD
+Codecov
+DOI
+GGally
+GVIF
+Gehan
+Hmisc
+JAMA
+Kaplan
+MacOS
+McNemar
+McNemar's
+NEJM
+Ns
+ORCID
+Peto
+README
+RJ
+RStudio
+RTF
+Rao
+SHA
+Tarone
+Tidiers
+VIF
+Waerden's
+Wainberg
+YAML
+bstfun
+cli
+codebase
+coef
+conf
+coxph
+crosstab
+customizability
+customizable
+der
+df
+dichotomously
+dplyr
+effectsize
+emmeans
+exponentiate
+flextable
+forcats
+ftExtra
+ggplot
+ggstats
+glm
+huxtable
+kable
+kableExtra
+knitr
+labelled
+lifecycle
+lm
+lme
+logLik
+mL
+mira
+nevent
+ng
+nnet
+obejcts
+pre
+pvalue
+quosure
+quosures
+saddlepoint
+smd
+srvyr
+styler
+survfit
+svysummary
+tbl
+th
+tibble
+tibbles
+tidiers
+tidyr
+tidyselect
+tidyselect's
+tidyverse
+un
+unhide
+unicode
+univariable
+unstratified
+usethis
+uvregression
+yaml

inst/rmarkdown_example/.gitignore

@@ -0,0 +1,9 @@
+# ignoring Rmarkdown output
+*.html
+*.pdf
+*.docx
+*.doc
+*.rtf
+~*.docx
+~*.doc
+~*.rtf

inst/rmarkdown_example/gtsummary_rmarkdown_html.Rmd

@@ -0,0 +1,54 @@
+---
+title: "gtsummary + R Markdown"
+output: html_document
+---
+
+```{r setup, include=FALSE}
+knitr::opts_chunk$set(echo = TRUE, warning = FALSE)
+```
+
+```{r libraries, message=FALSE}
+library(gtsummary)
+library(tidyverse)
+library(survival)
+```
+
+## gtsummary tables
+
+Tables created with {gtsummary} can be integrated into R markdown documents.
+The {gtsummary} package was written to be a companion to the [{gt} package](https://gt.rstudio.com/) from Posit.
+
+```{r example}
+patient_characteristics <-
+  trial |> 
+  tbl_summary(by = trt, include = c(age, grade, response))  
+patient_characteristics
+```
+
+With HTML output, you can include complex tables with footnotes, indentation, and spanning table headers.
+
+```{r}
+# Side-by-side Regression Models
+# logistic regression model
+t1 <-
+  glm(response ~ trt + grade + age, trial, family = binomial) %>%
+  tbl_regression(exponentiate = TRUE)
+# time to death Cox model
+t2 <-
+  coxph(Surv(ttdeath, death) ~ trt + grade + age, trial) %>%
+  tbl_regression(exponentiate = TRUE)
+
+# printing merged table
+tbl_merge(
+  tbls = list(t1, t2),
+  tab_spanner = c("**Tumor Response**", "**Time to Death**")
+)
+```
+
+## inline reporting
+
+Any number/statistic from a {gtsummary} table can be reported inline in a R markdown document using the `inline_text()` function.  See example below:
+
+> Among patients who received Drug A, `r inline_text(patient_characteristics, variable = grade, level = "III", column = "Drug A")` had grade III tumors.
+
+For detailed examples using functions from {gtsummary}, visit the [{gtsummary} website](https://www.danieldsjoberg.com/gtsummary/).