Creates publication-ready summary tables for data grouped, by visit

Usage

summaryByVisit(
  data,
  vars = NULL,
  group = NULL,
  labels = NULL,
  stat_cont = "median_range",
  stat_cat = "n_percent",
  visit = "visit",
  order = NULL,
  visitgroup = NULL,
  digits_cont = 1,
  digits_cat = 0,
  missing_percent = TRUE,
  missing = TRUE,
  missing_text = "Missing",
  add_n = TRUE,
  overall = FALSE,
  continuous_as_categorical = NULL,
  as_flex_table = TRUE,
  border = TRUE,
  word_output = FALSE,
  file_path = paste0("SummaryByVisit_", format(Sys.Date(), "%Y%m%d"), ".docx")
)

Arguments

data: A data frame or tibble containing the data to be summarized.
vars: Variables to include in the summary table. Need to be specified with quotes, e.g. "age" or c("age", "response"). Default to all variables present in the data except group.
group: A single column from data. Need to be specified with quotes, e.g. "treatment". Summary statistics will be stratified according to this variable. Default to NULL. A maximum of 3 groups are currently supported. Character variables and a character group are shown in natural order (e.g. "2" before "10"); factors keep their level order.
labels: A list containing the labels that should be used for the variables in the table, either named by variable (e.g. list(age = "Age (years)")) or unnamed in the order of vars. If NULL, labels are automatically taken from the dataset. If no label present, the variable name is taken.
stat_cont: Summary statistic to display for continuous variables. Options include "median_IQR", "median_range" (default), "mean_sd", "mean_se" and "geomMean_sd".
stat_cat: Summary statistic to display for categorical variables. Options include "n", "n_N" and "n_percent" (default).
visit: Name of the stratum for which summary statistics are displayed by line. Typically, this would be "visit".
order: A numerical variable defining the visit order. If NULL (default), visits are sorted naturally (e.g. "Visit 2" before "Visit 10"); if visit is a factor, its level order is used instead.
visitgroup: A grouping variable for the stratum for which summary statistics are displayed by line. Must be an ordered factor. Typically, this would be a visit group such as e.g., baseline, follow-up etc.
digits_cont: Digits for summary statistics and CI of continuous variables. Default to 1.
digits_cat: Digits for summary statistics and CI of categorical variables. Default to 0.
missing_percent: Indicates whether percentages for missings are shown (TRUE, default) or not (FALSE) for categorical variables. If "both", then both options are displayed next to each other.
missing: Logical. If TRUE (default), the missing values are shown (only for categorical variables).
missing_text: String indicating text shown on missing row. Default to "Missing".
add_n: Logical. If TRUE, an additional column with the total number of non-missing observations for each variable is added. Default to TRUE.
overall: Logical. If TRUE, an additional column with the total is added to the table. Ignored, if no groups are defined. Default to FALSE.
continuous_as_categorical: A subset (vector) of continuous vars to be treated as categrical. Default is NULL.
as_flex_table: Logical. If TRUE (default) the gtsummary object is converted to a flextable object. Useful when rendering to Word.
border: Logical. If TRUE, a border will be drawn around the table. Only available if flex_table = TRUE. Default is TRUE.
word_output: Logical. If TRUE, the table is also saved in a word document.
file_path: Character string. Specify the path of the Word document containing the table. Only used when word_output is TRUE. Needs to end with ".docx". Default to "SummaryByVisit_YYYYMMDD.docx" (today's date) in the working directory.

Value

A table of class "flextable" or c("tbl_strata_nested_stack", "tbl_stack", "gtsummary"). Optionally returns a .docx file in the specified folder.

Examples

data("hemoglobin_data")
hb <- subset(hemoglobin_data, visit_nr <= 3)   # first 3 cycles, to keep it short

# Hemoglobin by visit and arm, with an overall column
summaryByVisit(data = hb, vars = "hb", visit = "visit",
               group = "Arm", overall = TRUE,
               labels = list(hb = "Hemoglobin (g/L)"))
Visit N1 Arm A  
N = 842 N1 Arm B  
N = 852 N1 Overall  
N = 1692
Hemoglobin (g/L) 
Cycle 1 29 130.0 (94.0, 151.0) 23 132.0 (105.0, 157.0) 52 130.0 (94.0, 157.0)
Cycle 2 83 135.0 (102.0, 173.0) 84 133.0 (93.0, 150.0) 167 134.0 (93.0, 173.0)
Cycle 3 83 136.0 (93.0, 168.0) 80 131.5 (87.0, 155.0) 163 133.0 (87.0, 168.0)
1N without missing values
2Median (Min, Max)

Visit	N1	Arm A N = 842	N1	Arm B N = 852	N1	Overall N = 1692
Hemoglobin (g/L)
Cycle 1	29	130.0 (94.0, 151.0)	23	132.0 (105.0, 157.0)	52	130.0 (94.0, 157.0)
Cycle 2	83	135.0 (102.0, 173.0)	84	133.0 (93.0, 150.0)	167	134.0 (93.0, 173.0)
Cycle 3	83	136.0 (93.0, 168.0)	80	131.5 (87.0, 155.0)	163	133.0 (87.0, 168.0)
1N without missing values
2Median (Min, Max)