Package 'summarySCI'

Title: Produces Publication-Ready Summary Tables
Description: Produces tables with descriptive statistics for continuous, categorical and dichotomous variables. It is largely based on the package 'gtsummary'; Sjoberg DD et al. (2021) <doi:10.32614/RJ-2021-053>.
Authors: Sämi Schär [aut], Charlotte Micheloud [cre, aut]
Maintainer: Charlotte Micheloud <[email protected]>
License: LGPL-3
Version: 1.0.0
Built: 2026-10-15 11:57:37 UTC
Source: https://github.com/sakk-statistics/summarysci

Help Index

Boxplot over time

Description

Generates boxplots over time for one or multiple sub-groups.

Usage

boxplotSCI(
  data,
  var,
  order = NULL,
  visit = NULL,
  group = NULL,
  group_names = NULL,
  group_names_short = NULL,
  main = "",
  xlab = NULL,
  ylab = "Variable",
  ylim = NULL,
  y_ticks = NULL,
  col = NULL,
  cex_lab = 1,
  cex_axis = 1,
  cex_n_patients = 0.7,
  boxwex = NULL,
  shift = NULL,
  mar_custom = NULL,
  xlab_line = NULL,
  ylab_line = 3,
  xlab_position = NULL,
  lines = NULL,
  lty = NULL,
  col_lines = NULL,
  legend_position = "topright",
  legend_offset = c(0, 0),
  legend_cex = 1,
  legend_bty = "n",
  missing_nr = 0,
  color_time = FALSE
)

Arguments

data

A data frame or tibble containing the data to be plotted.
var

Name of the column in data indicating the measurement to be plotted. Supports bare or quoted column names.
order

Name of the column in data containing the time points of interest. The time points can be either numeric, character, or a factor. If the time points are factors, the factor levels must be in the correct chronological order for plotting. If left empty, the function will assume a single time point. If character, they need to be able to be ordered by numerical logic.
visit

Name of the column in data containing descriptive labels for the time points. Optional.
group

Name of the column in data containing the grouping variables (e.g., treatment arms). If left empty, the function will assume a single group.
group_names

A character vector containing the names of the groups to be displayed in the legend. The order must match levels(factor(data$group)). Default is NULL, which falls back to the group names found in the data.
group_names_short

A character vector containing short names or abbreviations for the groups, to be displayed below the x-axis near the patient counts. Optional. Defaults to group_names.
main

Title of the plot. Defaults to "" (no title).
xlab

A label for the x-axis. Default is "Time" if there are multiple time points, otherwise defaults to "Group".
ylab

A label for the y-axis. Default is "Variable".
ylim

The y-axis limits of the plot as a numeric vector of length 2. Default is NULL, which adds a 10% padding buffer above and below the data range.
y_ticks

A numeric vector specifying the explicit tick positions on the y-axis. Default is NULL, which calculates 5 evenly spaced ticks across the data range.
col

A character vector of hex colors or color names to use for the boxes. Default is NULL, which automatically applies the SCI color palette.
cex_lab

A numeric value specifying the font size of the main axis labels. Default is 1.
cex_axis

A numeric value specifying the font size of the axis tick marks. Default is 1.
cex_n_patients

A numeric value specifying the font size of the sample size labels and numbers displayed beneath the horizontal axis. Default is 0.7.
boxwex

Scale factor for the width of the boxes. Default is NULL, which scales the box flexibly to the size of total timepoints and groups.
shift

A numeric value indicating the distance between adjacent boxes within a timepoint cluster. Default is NULL, which dynamically sets spacing to boxwex * 1.15.
mar_custom

A numeric vector indicating the plot margins to be used in the form c(bottom, left, top, right). Default is NULL, which dynamically calculates spacing so that stacked sample-size rows are never clipped.
xlab_line

A numeric value indicating the margin line offset for the x-axis label. Default is NULL, which calculates an adaptive offset based on the number of groups.
ylab_line

A numeric value indicating the margin line offset for the y-axis label. Default is 3.0.
xlab_position

Horizontal position coordinate adjustment for the sample size group headers down the left-hand margin. Default is NULL, which auto-aligns them.
lines

A numeric vector indicating the vertical coordinates where horizontal reference lines will be plotted. Optional.
lty

A numeric vector of length 1 or of the same length as lines indicating the line type to be plotted. Default is 1 (solid).
col_lines

A character vector of length 1 or of the same length as lines indicating the color of the reference lines. Default is "grey".
legend_position

Position of the legend box. Options include standard base R keywords (e.g., "topright", "topleft", "bottom") or manual numeric coordinate pairs c(x, y). Default is "topright".
legend_offset

A numeric vector of length 2 specifying an inset to nudge the legend position away from plot elements. Default is c(0, 0).
legend_cex

A numeric value specifying the font and element scaling size inside the legend box. Default is 1.
legend_bty

The type of box border to be drawn around the legend. Allowed values are "n" (transparent/no border, the default) and "o" (standard box frame).
missing_nr

A numeric or character value indicating how zero-count patient sizes on the x-axis should be displayed. Default is 0. Can also be set to NA.
color_time

A logical toggle switch enabling legacy timepoint colorization. Supports legacy use, where, for a single timepoint, multiple groups were used as "timepoint" variable. If set to TRUE, it treats timepoints as individual categories,applying sequential coloring and rendering a matching tracking legend. Default is FALSE.

Examples

library(summarySCI)
data("hemoglobin_data")
boxplotSCI(data = hemoglobin_data,
                 var = hb,
                  order = visit_nr,
                  group = Arm,
                  group_names = c("Treatment (Arm A)", "Control (Arm B)"),
                  group_names_short = c("A", "B"),
                  # Title
                  main = "Hemoglobin over time",
                  # Col of boxes
                  col = c("lightblue", "orange"),
                  # X axis label
                  xlab = "Visits",
                  # X axis position
                  xlab_position = 0,
                  # Y axis label
                  ylab = "Score",
                  lines = c(90, 120, 160),
                  # Col of lines
                  col_lines = c("red", "grey", "red"),
                  # Type of lines
                  lty = c(2, 3, 2)
)

Hemoglobin data (to illustrate boxplot_over_time())

Description

A dataset containing the hemoglobin value of 169 patients over 9 visits. Adapted from SAKK 08/14.

Usage

data(hemoglobin_data)

Format

hemoglobin_data

A data frame with 1307 rows and 5 columns:

ID

Patient ID

Arm

Experimental arm

visit

Visit (factor)

visit_nr

Visit (numeric)

hb

Hemoglobin value (g/L)

Source

SAKK

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

Description

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 = 1,
  missing_percent = TRUE,
  missing = TRUE,
  missing_text = "Missing",
  add_n = FALSE,
  overall = FALSE,
  continuous_as_categorical = NULL,
  as_flex_table = TRUE,
  border = TRUE,
  word_output = FALSE,
  file_path = file_path
)

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.
labels

A list, containing the labels that should be used for the variables in the table. 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.
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 1.
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.
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".

Value

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

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

Description

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

Usage

summaryByVisitCategorical(
  data,
  vars = NULL,
  group = NULL,
  labels = NULL,
  stat_cat = "n_percent",
  visit = "visit",
  order = NULL,
  visitgroup = NULL,
  digits_cat = 1,
  missing_percent = TRUE,
  missing = TRUE,
  missing_text = "Missing",
  add_n = FALSE,
  overall = FALSE,
  as_flex_table = FALSE,
  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

Continuous variables to include in the summary table. Need to be specified with quotes, e.g. "grade" or c("grade", "stage"). 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.
labels

A list containing the labels that should be used for the variables in the table. If NULL, labels are automatically taken from the dataset. If no label present, the variable name is taken.
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.
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_cat

Digits for summary statistics of categorical variables. Default to 1.
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.
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.
overall

Logical. If TRUE, an additional column with the total is added to the table. Ignored, if no groups are defined. Default to FALSE.
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".

Value

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

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

Description

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

Usage

summaryByVisitContinuous(
  data,
  vars = NULL,
  group = NULL,
  labels = NULL,
  stat_cont = "median_range",
  visit = "visit",
  order = NULL,
  visitgroup = NULL,
  digits_cont = 1,
  add_n = FALSE,
  overall = FALSE,
  as_flex_table = FALSE,
  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

Continuous 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.
labels

A list containing the labels that should be used for the variables in the table. 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".
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.
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.
add_n

Logical. If TRUE, an additional column with the total number of non-missing observations for each variable is added.
overall

Logical. If TRUE, an additional column with the total is added to the table. Ignored, if no groups are defined. Default to FALSE.
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".

Value

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

summaryLevels

Description

Collapses factor levels from multiple columns into one and creates summary table.

Usage

summaryLevels(
  data,
  vars = NULL,
  group = NULL,
  label = NULL,
  levels = NULL,
  stat_cat = "n_percent",
  test = FALSE,
  test_cat = "fisher.test",
  ci = FALSE,
  ci_cat = "wilson",
  conf_level = 0.95,
  digits_cat = 0,
  overall = FALSE,
  as_flex_table = TRUE,
  border = TRUE,
  word_output = FALSE,
  file_path = paste0("SummaryLevels_", 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. "score" or c("score", "age_cat"). 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.
label

A label for the new variable to be created. If no label present, the variable name is taken.
levels

= A vector containing the values indicating presence of the factor level. Included by default are "1", "yes", "Yes".
stat_cat

Summary statistic to display for categorical variables. Options include "n_percent" (default) and "n", and "n_N".
test

Logical. Indicates whether p-values are displayed (TRUE) or not (FALSE). Default to FALSE
test_cat

Test type used to calculated the p-value for categorical variables. Only used if test = TRUE. Options include "fisher.test" (default), "chisq.test", "chisq.test.no.correct". If NULL, the function decides itself: "chisq.test.no.correct" for categorical variables with all expected cell counts >=5, and "fisher.test" for categorical variables with any expected cell count <5.
ci

Logical. Indicates whether CI are displayed (TRUE) or not (FALSE). Default to FALSE.
ci_cat

Confidence interval method for categorical variables. Options include "wilson" (default), "wilson.no.correct", "clopper.pearson", "wald", "wald.no.correct", "agresti.coull" and "jeffreys". If NULL, no CI will be displayed.
conf_level

Numeric. Confidence level. Default to 0.95.
digits_cat

Numeric. Digits for summary statistics and CI of categorical variables. Default to 0.
overall

Logical. If TRUE, an additional column with the total is added to the table. Default to FALSE.
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".

Value

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

Creates publication-ready summary tables

Description

Creates publication-ready summary tables based on the gtsummary package.

Usage

summaryTable(
  data,
  vars = NULL,
  group = NULL,
  labels = NULL,
  stat_cont = "median_range",
  stat_cat = "n_percent",
  continuous_as = "continuous",
  dichotomous_as = "dichotomous",
  continuous_as_categorical = NULL,
  dichotomous_as_categorical = NULL,
  ref_level = NULL,
  test = FALSE,
  test_cont = NULL,
  test_cat = "fisher.test",
  ci = FALSE,
  ci_cont = "wilcox.test",
  ci_cat = "clopper.pearson",
  conf_level = 0.95,
  digits_cont = 1,
  digits_cat = 0,
  missing = TRUE,
  missing_percent = TRUE,
  missing_text = "Missing",
  overall = FALSE,
  add_n = TRUE,
  as_flex_table = TRUE,
  border = TRUE,
  word_output = FALSE,
  file_path = paste0("SummaryTable_", 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.
labels

A list containing the labels that should be used for the variables in the table. 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_percent" (default) and "n", and "n_N".
continuous_as

Type for all the continuous variables. Can either be "continuous" (default) or "categorical".
dichotomous_as

Type for the dichotomous variables. Can either be "categorical" (one row per level) or "dichotomous" (only one row with reference level (see argument ref_level), only works if the variable does not contain missing values, or if missing = "FALSE" or missing_percent = FALSE.
continuous_as_categorical

A subset (vector) of continuous vars to be treated as categorical. Default is NULL.
dichotomous_as_categorical

A subset (vector) of dichotomous vars to be treated as categorical. Default is NULL.
ref_level

Specifies the reference level of a variable to display on a single row. Default is the first appearing level. The syntax is as follows: ref_level = list(varname ~ "level to show").
test

Logical. Indicates whether p-values are displayed (TRUE) or not (FALSE). Default to FALSE
test_cont

Test type used to calculate the p-value for continuous variables. Only used if test = TRUE. Options include "t.test", "oneway.test", "kruskal.test" (default for more than two groups), "wilcox.test" (default for two groups).
test_cat

Test type used to calculated the p-value for categorical variables. Only used if test = TRUE. Options include "fisher.test" (default), "chisq.test", "chisq.test.no.correct". If NULL, the function decides itself: "chisq.test.no.correct" for categorical variables with all expected cell counts >=5, and "fisher.test" for categorical variables with any expected cell count <5.
ci

Logical. Indicates whether CI are displayed (TRUE) or not (FALSE). Default to FALSE.
ci_cont

Confidence interval method for continuous variables. Only used if ci = TRUE. Options include "t.test" and "wilcox.test" (default).
ci_cat

Confidence interval method for categorical variables. Options include "clopper.pearson" (default) "wilson", "wilson.no.correct", "wald", "wald.no.correct", "agresti.coull" and "jeffreys". If NULL, no CI will be displayed.
conf_level

Numeric. Confidence level. Default to 0.95.
digits_cont

Numeric. Digits for summary statistics and CI of continuous variables. Default to 1.
digits_cat

Numeric. Digits for summary statistics and CI of categorical variables. Default to 0.
missing

Logical. If TRUE (default), the missing values are shown.
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_text

String indicating text shown on missing row. Default to "Missing".
overall

Logical. If TRUE, an additional column with the total is added to the table. Default to FALSE.
add_n

Logical. If TRUE (default), an additional column with the total number of non-missing observations for each variable is added.
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".

Value

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

Examples

library(survival)
data("cancer")
summaryTable(data = cancer,vars = c("inst", "time","age", "ph.ecog"),
             labels = list(inst = "Institution code",
                           time = "Time",
                           age = "Age",
                           ph.ecog = "ECOG score"))