Title:	Create Common TLGs Used in Clinical Trials
Version:	0.9.9
Date:	2025-06-18
Description:	Table, Listings, and Graphs (TLG) library for common outputs used in clinical trials.
License:	Apache License 2.0
URL:	https://insightsengineering.github.io/tern/, https://github.com/insightsengineering/tern/
BugReports:	https://github.com/insightsengineering/tern/issues
Depends:	R (≥ 4.4.0), rtables (≥ 0.6.13)
Imports:	broom (≥ 0.5.4), car (≥ 3.0-13), checkmate (≥ 2.1.0), cowplot (≥ 1.0.0), dplyr (≥ 1.0.0), emmeans (≥ 1.10.4), forcats (≥ 1.0.0), formatters (≥ 0.5.11), ggplot2 (≥ 3.5.0), grid, gridExtra (≥ 2.0.0), gtable (≥ 0.3.0), labeling, lifecycle (≥ 0.2.0), magrittr (≥ 1.5), MASS (≥ 7.3-60), methods, nestcolor (≥ 0.1.1), Rdpack (≥ 2.4), rlang (≥ 1.1.0), scales (≥ 1.2.0), stats, survival (≥ 3.8-3), tibble (≥ 2.0.0), tidyr (≥ 0.8.3), utils
Suggests:	knitr (≥ 1.42), lattice (≥ 0.18-4), lubridate (≥ 1.7.9), rmarkdown (≥ 2.23), stringr (≥ 1.4.1), svglite (≥ 2.1.2), testthat (≥ 3.1.9), withr (≥ 2.0.0)
VignetteBuilder:	knitr, rmarkdown
RdMacros:	lifecycle, Rdpack
Config/Needs/verdepcheck:	insightsengineering/rtables, tidymodels/broom, cran/car, mllg/checkmate, wilkelab/cowplot, tidyverse/dplyr, rvlenth/emmeans, tidyverse/forcats, insightsengineering/formatters, tidyverse/ggplot2, r-lib/gtable, r-lib/lifecycle, tidyverse/magrittr, GeoBosh/Rdpack, r-lib/rlang, r-lib/scales, therneau/survival, tidyverse/tibble, tidyverse/tidyr, yihui/knitr, deepayan/lattice, tidyverse/lubridate, insightsengineering/nestcolor, rstudio/rmarkdown, tidyverse/stringr, r-lib/svglite, r-lib/testthat, r-lib/withr
Config/Needs/website:	insightsengineering/nesttemplate
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-US
LazyData:	true
RoxygenNote:	7.3.2
Collate:	'formatting_functions.R' 'abnormal.R' 'abnormal_by_baseline.R' 'abnormal_by_marked.R' 'abnormal_by_worst_grade.R' 'abnormal_lab_worsen_by_baseline.R' 'analyze_colvars_functions.R' 'analyze_functions.R' 'analyze_variables.R' 'analyze_vars_in_cols.R' 'argument_convention.R' 'bland_altman.R' 'combination_function.R' 'compare_variables.R' 'control_incidence_rate.R' 'control_logistic.R' 'control_step.R' 'control_survival.R' 'count_cumulative.R' 'count_missed_doses.R' 'count_occurrences.R' 'count_occurrences_by_grade.R' 'count_patients_events_in_cols.R' 'count_patients_with_event.R' 'count_patients_with_flags.R' 'count_values.R' 'cox_regression.R' 'cox_regression_inter.R' 'coxph.R' 'd_pkparam.R' 'data.R' 'decorate_grob.R' 'desctools_binom_diff.R' 'df_explicit_na.R' 'estimate_multinomial_rsp.R' 'estimate_proportion.R' 'fit_rsp_step.R' 'fit_survival_step.R' 'g_forest.R' 'g_ipp.R' 'g_km.R' 'g_lineplot.R' 'g_step.R' 'g_waterfall.R' 'h_adsl_adlb_merge_using_worst_flag.R' 'h_biomarkers_subgroups.R' 'h_cox_regression.R' 'h_incidence_rate.R' 'h_km.R' 'h_logistic_regression.R' 'h_map_for_count_abnormal.R' 'h_pkparam_sort.R' 'h_response_biomarkers_subgroups.R' 'h_response_subgroups.R' 'h_stack_by_baskets.R' 'h_step.R' 'h_survival_biomarkers_subgroups.R' 'h_survival_duration_subgroups.R' 'imputation_rule.R' 'incidence_rate.R' 'logistic_regression.R' 'missing_data.R' 'odds_ratio.R' 'package.R' 'prop_diff.R' 'prop_diff_test.R' 'prune_occurrences.R' 'response_biomarkers_subgroups.R' 'response_subgroups.R' 'riskdiff.R' 'rtables_access.R' 'score_occurrences.R' 'split_cols_by_groups.R' 'stat.R' 'summarize_ancova.R' 'summarize_change.R' 'summarize_colvars.R' 'summarize_coxreg.R' 'summarize_functions.R' 'summarize_glm_count.R' 'summarize_num_patients.R' 'summarize_patients_exposure_in_cols.R' 'survival_biomarkers_subgroups.R' 'survival_coxph_pairwise.R' 'survival_duration_subgroups.R' 'survival_time.R' 'survival_timepoint.R' 'utils.R' 'utils_checkmate.R' 'utils_default_stats_formats_labels.R' 'utils_factor.R' 'utils_ggplot.R' 'utils_grid.R' 'utils_rtables.R' 'utils_split_funs.R'
NeedsCompilation:	no
Packaged:	2025-06-20 00:18:23 UTC; delaruae
Author:	Joe Zhu [aut, cre], Daniel Sabanés Bové [aut], Jana Stoilova [aut], Davide Garolini [aut], Emily de la Rua [aut], Abinaya Yogasekaram [aut], Heng Wang [aut], Francois Collin [aut], Adrian Waddell [aut], Pawel Rucki [aut], Chendi Liao [aut], Jennifer Li [aut], F. Hoffmann-La Roche AG [cph, fnd]
Maintainer:	Joe Zhu <joe.zhu@roche.com>
Repository:	CRAN
Date/Publication:	2025-06-20 08:50:05 UTC

tern Package

Description

Package to create tables, listings and graphs to analyze clinical trials data.

Author(s)

Maintainer: Joe Zhu joe.zhu@roche.com (ORCID)

Authors:

• Daniel Sabanés Bové daniel.sabanes_bove@roche.com

• Jana Stoilova jana.stoilova@roche.com

• Davide Garolini davide.garolini@roche.com (ORCID)

• Emily de la Rua emily.de_la_rua@contractors.roche.com (ORCID)

• Abinaya Yogasekaram abinaya.yogasekaram@contractors.roche.com (ORCID)

• Heng Wang wang.heng@gene.com

• Francois Collin

• Adrian Waddell adrian.waddell@gene.com

• Pawel Rucki pawel.rucki@roche.com

• Chendi Liao chendi.liao@roche.com

• Jennifer Li li.jing@gene.com

Other contributors:

• F. Hoffmann-La Roche AG [copyright holder, funder]

See Also

Useful links:

• https://insightsengineering.github.io/tern/

• https://github.com/insightsengineering/tern/

• Report bugs at https://github.com/insightsengineering/tern/issues

Utility function to check if a float value is equal to another float value

Description

Uses .Machine$double.eps as the tolerance for the comparison.

Usage

.is_equal_float(x, y)

Arguments

Value

TRUE if identical, otherwise FALSE.

Count patients with abnormal range values

Description

The analyze function count_abnormal() creates a layout element to count patients with abnormal analysis range values in each direction.

This function analyzes primary analysis variable var which indicates abnormal range results. Additional analysis variables that can be supplied as a list via the variables parameter are id (defaults to USUBJID), a variable to indicate unique subject identifiers, and baseline (defaults to BNRIND), a variable to indicate baseline reference ranges.

For each direction specified via the abnormal parameter (e.g. High or Low), a fraction of patient counts is returned, with numerator and denominator calculated as follows:

• num: The number of patients with this abnormality recorded while on treatment.

• denom: The total number of patients with at least one post-baseline assessment.

This function assumes that df has been filtered to only include post-baseline records.

Usage

count_abnormal(
  lyt,
  var,
  abnormal = list(Low = "LOW", High = "HIGH"),
  variables = list(id = "USUBJID", baseline = "BNRIND"),
  exclude_base_abn = FALSE,
  na_str = default_na_str(),
  nested = TRUE,
  ...,
  table_names = var,
  .stats = "fraction",
  .stat_names = NULL,
  .formats = list(fraction = format_fraction),
  .labels = NULL,
  .indent_mods = NULL
)

s_count_abnormal(
  df,
  .var,
  abnormal = list(Low = "LOW", High = "HIGH"),
  variables = list(id = "USUBJID", baseline = "BNRIND"),
  exclude_base_abn = FALSE,
  ...
)

a_count_abnormal(
  df,
  ...,
  .stats = NULL,
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Value

• count_abnormal() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing the statistics from s_count_abnormal() to the table layout.

• s_count_abnormal() returns the statistic fraction which is a vector with num and denom counts of patients.

• a_count_abnormal() returns the corresponding list with formatted rtables::CellValue().

Functions

• count_abnormal(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::analyze().

• s_count_abnormal(): Statistics function which counts patients with abnormal range values for a single abnormal level.

• a_count_abnormal(): Formatted analysis function which is used as afun in count_abnormal().

Note

• count_abnormal() only considers a single variable that contains multiple abnormal levels.

• df should be filtered to only include post-baseline records.

• The denominator includes patients that may have other abnormal levels at baseline, and patients missing baseline records. Patients with these abnormalities at baseline can be optionally excluded from numerator and denominator via the exclude_base_abn parameter.

Examples

library(dplyr)

df <- data.frame(
  USUBJID = as.character(c(1, 1, 2, 2)),
  ANRIND = factor(c("NORMAL", "LOW", "HIGH", "HIGH")),
  BNRIND = factor(c("NORMAL", "NORMAL", "HIGH", "HIGH")),
  ONTRTFL = c("", "Y", "", "Y"),
  stringsAsFactors = FALSE
)

# Select only post-baseline records.
df <- df %>%
  filter(ONTRTFL == "Y")

# Layout creating function.
basic_table() %>%
  count_abnormal(var = "ANRIND", abnormal = list(high = "HIGH", low = "LOW")) %>%
  build_table(df)

# Passing of statistics function and formatting arguments.
df2 <- data.frame(
  ID = as.character(c(1, 1, 2, 2)),
  RANGE = factor(c("NORMAL", "LOW", "HIGH", "HIGH")),
  BL_RANGE = factor(c("NORMAL", "NORMAL", "HIGH", "HIGH")),
  ONTRTFL = c("", "Y", "", "Y"),
  stringsAsFactors = FALSE
)

# Select only post-baseline records.
df2 <- df2 %>%
  filter(ONTRTFL == "Y")

basic_table() %>%
  count_abnormal(
    var = "RANGE",
    abnormal = list(low = "LOW", high = "HIGH"),
    variables = list(id = "ID", baseline = "BL_RANGE")
  ) %>%
  build_table(df2)

Count patients with abnormal analysis range values by baseline status

Description

The analyze function count_abnormal_by_baseline() creates a layout element to count patients with abnormal analysis range values, categorized by baseline status.

This function analyzes primary analysis variable var which indicates abnormal range results. Additional analysis variables that can be supplied as a list via the variables parameter are id (defaults to USUBJID), a variable to indicate unique subject identifiers, and baseline (defaults to BNRIND), a variable to indicate baseline reference ranges.

For each direction specified via the abnormal parameter (e.g. High or Low), we condition on baseline range result and count patients in the numerator and denominator as follows for each of the following categories:

• ⁠Not <abnormality>⁠

  • num: The number of patients without abnormality at baseline (excluding those with missing baseline) and with at least one abnormality post-baseline.

  • denom: The number of patients without abnormality at baseline (excluding those with missing baseline).

• ⁠<Abnormality>⁠

  • num: The number of patients with abnormality as baseline and at least one abnormality post-baseline.

  • denom: The number of patients with abnormality at baseline.

• Total

  • num: The number of patients with at least one post-baseline record and at least one abnormality post-baseline.

  • denom: The number of patients with at least one post-baseline record.

This function assumes that df has been filtered to only include post-baseline records.

Usage

count_abnormal_by_baseline(
  lyt,
  var,
  abnormal,
  variables = list(id = "USUBJID", baseline = "BNRIND"),
  na_str = "<Missing>",
  nested = TRUE,
  ...,
  table_names = abnormal,
  .stats = "fraction",
  .stat_names = NULL,
  .formats = list(fraction = format_fraction),
  .labels = NULL,
  .indent_mods = NULL
)

s_count_abnormal_by_baseline(
  df,
  .var,
  abnormal,
  na_str = "<Missing>",
  variables = list(id = "USUBJID", baseline = "BNRIND"),
  ...
)

a_count_abnormal_by_baseline(
  df,
  ...,
  .stats = NULL,
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Value

• count_abnormal_by_baseline() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing the statistics from s_count_abnormal_by_baseline() to the table layout.

• s_count_abnormal_by_baseline() returns statistic fraction which is a named list with 3 labeled elements: not_abnormal, abnormal, and total. Each element contains a vector with num and denom patient counts.

• a_count_abnormal_by_baseline() returns the corresponding list with formatted rtables::CellValue().

Functions

• count_abnormal_by_baseline(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::analyze().

• s_count_abnormal_by_baseline(): Statistics function for a single abnormal level.

• a_count_abnormal_by_baseline(): Formatted analysis function which is used as afun in count_abnormal_by_baseline().

Note

• df should be filtered to include only post-baseline records.

• If the baseline variable or analysis variable contains NA records, it is expected that df has been pre-processed using df_explicit_na() or explicit_na().

See Also

Relevant description function d_count_abnormal_by_baseline().

Examples

df <- data.frame(
  USUBJID = as.character(c(1:6)),
  ANRIND = factor(c(rep("LOW", 4), "NORMAL", "HIGH")),
  BNRIND = factor(c("LOW", "NORMAL", "HIGH", NA, "LOW", "NORMAL"))
)
df <- df_explicit_na(df)

# Layout creating function.
basic_table() %>%
  count_abnormal_by_baseline(var = "ANRIND", abnormal = c(High = "HIGH")) %>%
  build_table(df)

# Passing of statistics function and formatting arguments.
df2 <- data.frame(
  ID = as.character(c(1, 2, 3, 4)),
  RANGE = factor(c("NORMAL", "LOW", "HIGH", "HIGH")),
  BLRANGE = factor(c("LOW", "HIGH", "HIGH", "NORMAL"))
)

basic_table() %>%
  count_abnormal_by_baseline(
    var = "RANGE",
    abnormal = c(Low = "LOW"),
    variables = list(id = "ID", baseline = "BLRANGE"),
    .formats = c(fraction = "xx / xx"),
    .indent_mods = c(fraction = 2L)
  ) %>%
  build_table(df2)

Count patients with marked laboratory abnormalities

Description

The analyze function count_abnormal_by_marked() creates a layout element to count patients with marked laboratory abnormalities for each direction of abnormality, categorized by parameter value.

This function analyzes primary analysis variable var which indicates whether a single, replicated, or last marked laboratory abnormality was observed. Levels of var to include for each marked lab abnormality (single and last_replicated) can be supplied via the category parameter. Additional analysis variables that can be supplied as a list via the variables parameter are id (defaults to USUBJID), a variable to indicate unique subject identifiers, param (defaults to PARAM), a variable to indicate parameter values, and direction (defaults to abn_dir), a variable to indicate abnormality directions.

For each combination of param and direction levels, marked lab abnormality counts are calculated as follows:

• ⁠Single, not last⁠ & ⁠Last or replicated⁠: The number of patients with ⁠Single, not last⁠ and ⁠Last or replicated⁠ values, respectively.

• Any: The number of patients with either single or replicated marked abnormalities.

Fractions are calculated by dividing the above counts by the number of patients with at least one valid measurement recorded during the analysis.

Prior to using this function in your table layout you must use rtables::split_rows_by() to create two row splits, one on variable param and one on variable direction.

Usage

count_abnormal_by_marked(
  lyt,
  var,
  category = list(single = "SINGLE", last_replicated = c("LAST", "REPLICATED")),
  variables = list(id = "USUBJID", param = "PARAM", direction = "abn_dir"),
  na_str = default_na_str(),
  nested = TRUE,
  ...,
  .stats = "count_fraction",
  .stat_names = NULL,
  .formats = list(count_fraction = format_count_fraction),
  .labels = NULL,
  .indent_mods = NULL
)

s_count_abnormal_by_marked(
  df,
  .var = "AVALCAT1",
  .spl_context,
  category = list(single = "SINGLE", last_replicated = c("LAST", "REPLICATED")),
  variables = list(id = "USUBJID", param = "PARAM", direction = "abn_dir"),
  ...
)

a_count_abnormal_by_marked(
  df,
  ...,
  .stats = NULL,
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Value

• count_abnormal_by_marked() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing the statistics from s_count_abnormal_by_marked() to the table layout.

• s_count_abnormal_by_marked() returns statistic count_fraction with ⁠Single, not last⁠, ⁠Last or replicated⁠, and Any results.

• a_count_abnormal_by_marked() returns the corresponding list with formatted rtables::CellValue().

Functions

• count_abnormal_by_marked(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::analyze().

• s_count_abnormal_by_marked(): Statistics function for patients with marked lab abnormalities.

• a_count_abnormal_by_marked(): Formatted analysis function which is used as afun in count_abnormal_by_marked().

Note

⁠Single, not last⁠ and ⁠Last or replicated⁠ levels are mutually exclusive. If a patient has abnormalities that meet both the ⁠Single, not last⁠ and ⁠Last or replicated⁠ criteria, then the patient will be counted only under the ⁠Last or replicated⁠ category.

Examples

library(dplyr)

df <- data.frame(
  USUBJID = as.character(c(rep(1, 5), rep(2, 5), rep(1, 5), rep(2, 5))),
  ARMCD = factor(c(rep("ARM A", 5), rep("ARM B", 5), rep("ARM A", 5), rep("ARM B", 5))),
  ANRIND = factor(c(
    "NORMAL", "HIGH", "HIGH", "HIGH HIGH", "HIGH",
    "HIGH", "HIGH", "HIGH HIGH", "NORMAL", "HIGH HIGH", "NORMAL", "LOW", "LOW", "LOW LOW", "LOW",
    "LOW", "LOW", "LOW LOW", "NORMAL", "LOW LOW"
  )),
  ONTRTFL = rep(c("", "Y", "Y", "Y", "Y", "Y", "Y", "Y", "Y", "Y"), 2),
  PARAMCD = factor(c(rep("CRP", 10), rep("ALT", 10))),
  AVALCAT1 = factor(rep(c("", "", "", "SINGLE", "REPLICATED", "", "", "LAST", "", "SINGLE"), 2)),
  stringsAsFactors = FALSE
)

df <- df %>%
  mutate(abn_dir = factor(
    case_when(
      ANRIND == "LOW LOW" ~ "Low",
      ANRIND == "HIGH HIGH" ~ "High",
      TRUE ~ ""
    ),
    levels = c("Low", "High")
  ))

# Select only post-baseline records.
df <- df %>% filter(ONTRTFL == "Y")
df_crp <- df %>%
  filter(PARAMCD == "CRP") %>%
  droplevels()
full_parent_df <- list(df_crp, "not_needed")
cur_col_subset <- list(rep(TRUE, nrow(df_crp)), "not_needed")
spl_context <- data.frame(
  split = c("PARAMCD", "GRADE_DIR"),
  full_parent_df = I(full_parent_df),
  cur_col_subset = I(cur_col_subset)
)

map <- unique(
  df[df$abn_dir %in% c("Low", "High") & df$AVALCAT1 != "", c("PARAMCD", "abn_dir")]
) %>%
  lapply(as.character) %>%
  as.data.frame() %>%
  arrange(PARAMCD, abn_dir)

basic_table() %>%
  split_cols_by("ARMCD") %>%
  split_rows_by("PARAMCD") %>%
  summarize_num_patients(
    var = "USUBJID",
    .stats = "unique_count"
  ) %>%
  split_rows_by(
    "abn_dir",
    split_fun = trim_levels_to_map(map)
  ) %>%
  count_abnormal_by_marked(
    var = "AVALCAT1",
    variables = list(
      id = "USUBJID",
      param = "PARAMCD",
      direction = "abn_dir"
    )
  ) %>%
  build_table(df = df)

basic_table() %>%
  split_cols_by("ARMCD") %>%
  split_rows_by("PARAMCD") %>%
  summarize_num_patients(
    var = "USUBJID",
    .stats = "unique_count"
  ) %>%
  split_rows_by(
    "abn_dir",
    split_fun = trim_levels_in_group("abn_dir")
  ) %>%
  count_abnormal_by_marked(
    var = "AVALCAT1",
    variables = list(
      id = "USUBJID",
      param = "PARAMCD",
      direction = "abn_dir"
    )
  ) %>%
  build_table(df = df)

Count patients by most extreme post-baseline toxicity grade per direction of abnormality

Description

The analyze function count_abnormal_by_worst_grade() creates a layout element to count patients by highest (worst) analysis toxicity grade post-baseline for each direction, categorized by parameter value.

This function analyzes primary analysis variable var which indicates toxicity grades. Additional analysis variables that can be supplied as a list via the variables parameter are id (defaults to USUBJID), a variable to indicate unique subject identifiers, param (defaults to PARAM), a variable to indicate parameter values, and grade_dir (defaults to GRADE_DIR), a variable to indicate directions (e.g. High or Low) for each toxicity grade supplied in var.

For each combination of param and grade_dir levels, patient counts by worst grade are calculated as follows:

• 1 to 4: The number of patients with worst grades 1-4, respectively.

• Any: The number of patients with at least one abnormality (i.e. grade is not 0).

Fractions are calculated by dividing the above counts by the number of patients with at least one valid measurement recorded during treatment.

Pre-processing is crucial when using this function and can be done automatically using the h_adlb_abnormal_by_worst_grade() helper function. See the description of this function for details on the necessary pre-processing steps.

Prior to using this function in your table layout you must use rtables::split_rows_by() to create two row splits, one on variable param and one on variable grade_dir.

Usage

count_abnormal_by_worst_grade(
  lyt,
  var,
  variables = list(id = "USUBJID", param = "PARAM", grade_dir = "GRADE_DIR"),
  na_str = default_na_str(),
  nested = TRUE,
  ...,
  .stats = "count_fraction",
  .stat_names = NULL,
  .formats = list(count_fraction = format_count_fraction),
  .labels = NULL,
  .indent_mods = NULL
)

s_count_abnormal_by_worst_grade(
  df,
  .var = "GRADE_ANL",
  .spl_context,
  variables = list(id = "USUBJID", param = "PARAM", grade_dir = "GRADE_DIR"),
  ...
)

a_count_abnormal_by_worst_grade(
  df,
  ...,
  .stats = NULL,
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Value

• count_abnormal_by_worst_grade() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing the statistics from s_count_abnormal_by_worst_grade() to the table layout.

• s_count_abnormal_by_worst_grade() returns the single statistic count_fraction with grades 1 to 4 and "Any" results.

• a_count_abnormal_by_worst_grade() returns the corresponding list with formatted rtables::CellValue().

Functions

• count_abnormal_by_worst_grade(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::analyze().

• s_count_abnormal_by_worst_grade(): Statistics function which counts patients by worst grade.

• a_count_abnormal_by_worst_grade(): Formatted analysis function which is used as afun in count_abnormal_by_worst_grade().

See Also

h_adlb_abnormal_by_worst_grade() which pre-processes ADLB data frames to be used in count_abnormal_by_worst_grade().

Examples

library(dplyr)
library(forcats)
adlb <- tern_ex_adlb

# Data is modified in order to have some parameters with grades only in one direction
# and simulate the real data.
adlb$ATOXGR[adlb$PARAMCD == "ALT" & adlb$ATOXGR %in% c("1", "2", "3", "4")] <- "-1"
adlb$ANRIND[adlb$PARAMCD == "ALT" & adlb$ANRIND == "HIGH"] <- "LOW"
adlb$WGRHIFL[adlb$PARAMCD == "ALT"] <- ""

adlb$ATOXGR[adlb$PARAMCD == "IGA" & adlb$ATOXGR %in% c("-1", "-2", "-3", "-4")] <- "1"
adlb$ANRIND[adlb$PARAMCD == "IGA" & adlb$ANRIND == "LOW"] <- "HIGH"
adlb$WGRLOFL[adlb$PARAMCD == "IGA"] <- ""

# Pre-processing
adlb_f <- adlb %>% h_adlb_abnormal_by_worst_grade()

# Map excludes records without abnormal grade since they should not be displayed
# in the table.
map <- unique(adlb_f[adlb_f$GRADE_DIR != "ZERO", c("PARAM", "GRADE_DIR", "GRADE_ANL")]) %>%
  lapply(as.character) %>%
  as.data.frame() %>%
  arrange(PARAM, desc(GRADE_DIR), GRADE_ANL)

basic_table() %>%
  split_cols_by("ARMCD") %>%
  split_rows_by("PARAM") %>%
  split_rows_by("GRADE_DIR", split_fun = trim_levels_to_map(map)) %>%
  count_abnormal_by_worst_grade(
    var = "GRADE_ANL",
    variables = list(id = "USUBJID", param = "PARAM", grade_dir = "GRADE_DIR")
  ) %>%
  build_table(df = adlb_f)

Count patients with toxicity grades that have worsened from baseline by highest grade post-baseline

Description

The analyze function count_abnormal_lab_worsen_by_baseline() creates a layout element to count patients with analysis toxicity grades which have worsened from baseline, categorized by highest (worst) grade post-baseline.

This function analyzes primary analysis variable var which indicates analysis toxicity grades. Additional analysis variables that can be supplied as a list via the variables parameter are id (defaults to USUBJID), a variable to indicate unique subject identifiers, baseline_var (defaults to BTOXGR), a variable to indicate baseline toxicity grades, and direction_var (defaults to GRADDIR), a variable to indicate toxicity grade directions of interest to include (e.g. "H" (high), "L" (low), or "B" (both)).

For the direction(s) specified in direction_var, patient counts by worst grade for patients who have worsened from baseline are calculated as follows:

• 1 to 4: The number of patients who have worsened from their baseline grades with worst grades 1-4, respectively.

• Any: The total number of patients who have worsened from their baseline grades.

Fractions are calculated by dividing the above counts by the number of patients who's analysis toxicity grades have worsened from baseline toxicity grades during treatment.

Prior to using this function in your table layout you must use rtables::split_rows_by() to create a row split on variable direction_var.

Usage

count_abnormal_lab_worsen_by_baseline(
  lyt,
  var,
  variables = list(id = "USUBJID", baseline_var = "BTOXGR", direction_var = "GRADDR"),
  na_str = default_na_str(),
  nested = TRUE,
  ...,
  table_names = lifecycle::deprecated(),
  .stats = "fraction",
  .stat_names = NULL,
  .formats = list(fraction = format_fraction),
  .labels = NULL,
  .indent_mods = NULL
)

s_count_abnormal_lab_worsen_by_baseline(
  df,
  .var = "ATOXGR",
  variables = list(id = "USUBJID", baseline_var = "BTOXGR", direction_var = "GRADDR"),
  ...
)

a_count_abnormal_lab_worsen_by_baseline(
  df,
  ...,
  .stats = NULL,
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Value

• count_abnormal_lab_worsen_by_baseline() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing the statistics from s_count_abnormal_lab_worsen_by_baseline() to the table layout.

• s_count_abnormal_lab_worsen_by_baseline() returns the counts and fraction of patients whose worst post-baseline lab grades are worse than their baseline grades, for post-baseline worst grades "1", "2", "3", "4" and "Any".

• a_count_abnormal_lab_worsen_by_baseline() returns the corresponding list with formatted rtables::CellValue().

Functions

• count_abnormal_lab_worsen_by_baseline(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::analyze().

• s_count_abnormal_lab_worsen_by_baseline(): Statistics function for patients whose worst post-baseline lab grades are worse than their baseline grades.

• a_count_abnormal_lab_worsen_by_baseline(): Formatted analysis function which is used as afun in count_abnormal_lab_worsen_by_baseline().

See Also

Relevant helper functions h_adlb_worsen() and h_worsen_counter() which are used within s_count_abnormal_lab_worsen_by_baseline() to process input data.

Examples

library(dplyr)

# The direction variable, GRADDR, is based on metadata
adlb <- tern_ex_adlb %>%
  mutate(
    GRADDR = case_when(
      PARAMCD == "ALT" ~ "B",
      PARAMCD == "CRP" ~ "L",
      PARAMCD == "IGA" ~ "H"
    )
  ) %>%
  filter(SAFFL == "Y" & ONTRTFL == "Y" & GRADDR != "")

df <- h_adlb_worsen(
  adlb,
  worst_flag_low = c("WGRLOFL" = "Y"),
  worst_flag_high = c("WGRHIFL" = "Y"),
  direction_var = "GRADDR"
)

basic_table() %>%
  split_cols_by("ARMCD") %>%
  add_colcounts() %>%
  split_rows_by("PARAMCD") %>%
  split_rows_by("GRADDR") %>%
  count_abnormal_lab_worsen_by_baseline(
    var = "ATOXGR",
    variables = list(
      id = "USUBJID",
      baseline_var = "BTOXGR",
      direction_var = "GRADDR"
    )
  ) %>%
  append_topleft("Direction of Abnormality") %>%
  build_table(df = df, alt_counts_df = tern_ex_adsl)

Split function to configure risk difference column

Description

Wrapper function for rtables::add_combo_levels() which configures settings for the risk difference column to be added to an rtables object. To add a risk difference column to a table, this function should be used as split_fun in calls to rtables::split_cols_by(), followed by setting argument riskdiff to TRUE in all following analyze function calls.

Usage

add_riskdiff(
  arm_x,
  arm_y,
  col_label = paste0("Risk Difference (%) (95% CI)", if (length(arm_y) > 1)
    paste0("\n", arm_x, " vs. ", arm_y)),
  pct = TRUE
)

Arguments

Value

A closure suitable for use as a split function (split_fun) within rtables::split_cols_by() when creating a table layout.

See Also

stat_propdiff_ci() for details on risk difference calculation.

Examples

adae <- tern_ex_adae
adae$AESEV <- factor(adae$AESEV)

lyt <- basic_table() %>%
  split_cols_by("ARMCD", split_fun = add_riskdiff(arm_x = "ARM A", arm_y = c("ARM B", "ARM C"))) %>%
  count_occurrences_by_grade(
    var = "AESEV",
    riskdiff = TRUE
  )

tbl <- build_table(lyt, df = adae)
tbl

Layout-creating function to add row total counts

Description

This works analogously to rtables::add_colcounts() but on the rows. This function is a wrapper for rtables::summarize_row_groups().

Usage

add_rowcounts(lyt, alt_counts = FALSE)

Arguments

Value

A modified layout where the latest row split labels now have the row-wise total counts (i.e. without column-based subsetting) attached in parentheses.

Note

Row count values are contained in these row count rows but are not displayed so that they are not considered zero rows by default when pruning.

Examples

basic_table() %>%
  split_cols_by("ARM") %>%
  add_colcounts() %>%
  split_rows_by("RACE", split_fun = drop_split_levels) %>%
  add_rowcounts() %>%
  analyze("AGE", afun = list_wrap_x(summary), format = "xx.xx") %>%
  build_table(DM)

Labels for adverse event baskets

Description

Usage

aesi_label(aesi, scope = NULL)

Arguments

Value

A string with the standard label for the AE basket.

Examples

adae <- tern_ex_adae

# Standardized query label includes scope.
aesi_label(adae$SMQ01NAM, scope = adae$SMQ01SC)

# Customized query label.
aesi_label(adae$CQ01NAM)

Analysis function to calculate risk difference column values

Description

In the risk difference column, this function uses the statistics function associated with afun to calculates risk difference values from arm X (reference group) and arm Y. These arms are specified when configuring the risk difference column which is done using the add_riskdiff() split function in the previous call to rtables::split_cols_by(). For all other columns, applies afun as usual. This function utilizes the stat_propdiff_ci() function to perform risk difference calculations.

Usage

afun_riskdiff(
  df,
  labelstr = "",
  afun,
  ...,
  .stats = NULL,
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Value

A list of formatted rtables::CellValue().

See Also

• stat_propdiff_ci() for details on risk difference calculation.

• Split function add_riskdiff() which, when used as split_fun within rtables::split_cols_by() with riskdiff argument set to TRUE in subsequent analyze functions calls, adds a risk difference column to a table layout.

Get selected statistics names

Description

Helper function to be used for creating afun.

Usage

afun_selected_stats(.stats, all_stats)

Arguments

Value

A character vector with the selected statistics.

Analyze functions in columns

Description

These functions are wrappers of rtables::analyze_colvars() which apply corresponding tern statistics functions to add an analysis to a given table layout. In particular, these functions where designed to have the analysis methods split into different columns.

• analyze_vars_in_cols(): fundamental tabulation of analysis methods onto columns. In other words, the analysis methods are defined in the column space, i.e. they become column labels. By changing the variable vector, the list of functions can be applied on different variables, with the caveat of having the same number of statistical functions.

• tabulate_rsp_subgroups(): similarly to analyze_vars_in_cols, this function combines analyze_colvars and summarize_row_groups in a compact way to produce standard tables that show analysis methods as columns.

• tabulate_survival_subgroups(): this function is very similar to the above, but it is used for other tables.

• analyze_patients_exposure_in_cols(): based only on analyze_colvars. It needs summarize_patients_exposure_in_cols() to leverage nesting of label rows analysis with rtables::summarize_row_groups().

• summarize_coxreg(): generally based on rtables::summarize_row_groups(), it behaves similarly to ⁠tabulate_*⁠ functions described above as it is designed to provide specific standard tables that may contain nested structure with a combination of summarize_row_groups() and rtables::analyze_colvars().

See Also

• summarize_functions for functions which are wrappers for rtables::summarize_row_groups().

• analyze_functions for functions which are wrappers for rtables::analyze().

Analyze functions

Description

These functions are wrappers of rtables::analyze() which apply corresponding tern statistics functions to add an analysis to a given table layout:

• analyze_num_patients()

• analyze_vars()

• compare_vars()

• count_abnormal()

• count_abnormal_by_baseline()

• count_abnormal_by_marked()

• count_abnormal_by_worst_grade()

• count_cumulative()

• count_missed_doses()

• count_occurrences()

• count_occurrences_by_grade()

• count_patients_events_in_cols()

• count_patients_with_event()

• count_patients_with_flags()

• count_values()

• coxph_pairwise()

• estimate_incidence_rate()

• estimate_multinomial_rsp()

• estimate_odds_ratio()

• estimate_proportion()

• estimate_proportion_diff()

• summarize_ancova()

• summarize_colvars(): even if this function uses rtables::analyze_colvars(), it applies the analysis methods as different rows for one or more variables that are split into different columns. In comparison, analyze_colvars_functions leverage analyze_colvars to have the context split in rows and the analysis methods in columns.

• summarize_change()

• surv_time()

• surv_timepoint()

• test_proportion_diff()

See Also

• analyze_colvars_functions for functions that are wrappers for rtables::analyze_colvars().

• summarize_functions for functions which are wrappers for rtables::summarize_row_groups().

Analyze variables

Description

The analyze function analyze_vars() creates a layout element to summarize one or more variables, using the S3 generic function s_summary() to calculate a list of summary statistics. A list of all available statistics for numeric variables can be viewed by running get_stats("analyze_vars_numeric") and for non-numeric variables by running get_stats("analyze_vars_counts"). Use the .stats parameter to specify the statistics to include in your output summary table. Use compare_with_ref_group = TRUE to compare the variable with reference groups.

Usage

analyze_vars(
  lyt,
  vars,
  var_labels = vars,
  na_str = default_na_str(),
  nested = TRUE,
  show_labels = "default",
  table_names = vars,
  section_div = NA_character_,
  ...,
  na_rm = TRUE,
  compare_with_ref_group = FALSE,
  .stats = c("n", "mean_sd", "median", "range", "count_fraction"),
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

s_summary(x, ...)

## S3 method for class 'numeric'
s_summary(x, control = control_analyze_vars(), ...)

## S3 method for class 'factor'
s_summary(x, denom = c("n", "N_col", "N_row"), ...)

## S3 method for class 'character'
s_summary(x, denom = c("n", "N_col", "N_row"), ...)

## S3 method for class 'logical'
s_summary(x, denom = c("n", "N_col", "N_row"), ...)

a_summary(
  x,
  ...,
  .stats = NULL,
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Details

Automatic digit formatting: The number of digits to display can be automatically determined from the analyzed variable(s) (vars) for certain statistics by setting the statistic format to "auto" in .formats. This utilizes the format_auto() formatting function. Note that only data for the current row & variable (for all columns) will be considered (.df_row[[.var]], see rtables::additional_fun_params) and not the whole dataset.

Value

• analyze_vars() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing the statistics from s_summary() to the table layout.

• s_summary() returns different statistics depending on the class of x.

• If x is of class numeric, returns a list with the following named numeric items:

  • n: The length() of x.

  • sum: The sum() of x.

  • mean: The mean() of x.

  • sd: The stats::sd() of x.

  • se: The standard error of x mean, i.e.: (sd(x) / sqrt(length(x))).

  • mean_sd: The mean() and stats::sd() of x.

  • mean_se: The mean() of x and its standard error (see above).

  • mean_ci: The CI for the mean of x (from stat_mean_ci()).

  • mean_sei: The SE interval for the mean of x, i.e.: (mean() -/+ stats::sd() / sqrt()).

  • mean_sdi: The SD interval for the mean of x, i.e.: (mean() -/+ stats::sd()).

  • mean_pval: The two-sided p-value of the mean of x (from stat_mean_pval()).

  • median: The stats::median() of x.

  • mad: The median absolute deviation of x, i.e.: (stats::median() of xc, where xc = x - stats::median()).

  • median_ci: The CI for the median of x (from stat_median_ci()).

  • quantiles: Two sample quantiles of x (from stats::quantile()).

  • iqr: The stats::IQR() of x.

  • range: The range_noinf() of x.

  • min: The max() of x.

  • max: The min() of x.

  • median_range: The median() and range_noinf() of x.

  • cv: The coefficient of variation of x, i.e.: (stats::sd() / mean() * 100).

  • geom_mean: The geometric mean of x, i.e.: (exp(mean(log(x)))).

  • geom_cv: The geometric coefficient of variation of x, i.e.: (sqrt(exp(sd(log(x)) ^ 2) - 1) * 100).

• If x is of class factor or converted from character, returns a list with named numeric items:

  • n: The length() of x.

  • count: A list with the number of cases for each level of the factor x.

  • count_fraction: Similar to count but also includes the proportion of cases for each level of the factor x relative to the denominator, or NA if the denominator is zero.

• If x is of class logical, returns a list with named numeric items:

  • n: The length() of x (possibly after removing NAs).

  • count: Count of TRUE in x.

  • count_fraction: Count and proportion of TRUE in x relative to the denominator, or NA if the denominator is zero. Note that NAs in x are never counted or leading to NA here.

• a_summary() returns the corresponding list with formatted rtables::CellValue().

Functions

• analyze_vars(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::analyze().

• s_summary(): S3 generic function to produces a variable summary.

• s_summary(numeric): Method for numeric class.

• s_summary(factor): Method for factor class.

• s_summary(character): Method for character class. This makes an automatic conversion to factor (with a warning) and then forwards to the method for factors.

• s_summary(logical): Method for logical class.

• a_summary(): Formatted analysis function which is used as afun in analyze_vars() and compare_vars() and as cfun in summarize_colvars().

Note

• If x is an empty vector, NA is returned. This is the expected feature so as to return rcell content in rtables when the intersection of a column and a row delimits an empty data selection.

• When the mean function is applied to an empty vector, NA will be returned instead of NaN, the latter being standard behavior in R.

• If x is an empty factor, a list is still returned for counts with one element per factor level. If there are no levels in x, the function fails.

• If factor variables contain NA, these NA values are excluded by default. To include NA values set na_rm = FALSE and missing values will be displayed as an NA level. Alternatively, an explicit factor level can be defined for NA values during pre-processing via df_explicit_na() - the default na_level ("<Missing>") will also be excluded when na_rm is set to TRUE.

• Automatic conversion of character to factor does not guarantee that the table can be generated correctly. In particular for sparse tables this very likely can fail. It is therefore better to always pre-process the dataset such that factors are manually created from character variables before passing the dataset to rtables::build_table().

• To use for comparison (with additional p-value statistic), parameter compare_with_ref_group must be set to TRUE.

• Ensure that either all NA values are converted to an explicit NA level or all NA values are left as is.

Examples

## Fabricated dataset.
dta_test <- data.frame(
  USUBJID = rep(1:6, each = 3),
  PARAMCD = rep("lab", 6 * 3),
  AVISIT  = rep(paste0("V", 1:3), 6),
  ARM     = rep(LETTERS[1:3], rep(6, 3)),
  AVAL    = c(9:1, rep(NA, 9))
)

# `analyze_vars()` in `rtables` pipelines
## Default output within a `rtables` pipeline.
l <- basic_table() %>%
  split_cols_by(var = "ARM") %>%
  split_rows_by(var = "AVISIT") %>%
  analyze_vars(vars = "AVAL")

build_table(l, df = dta_test)

## Select and format statistics output.
l <- basic_table() %>%
  split_cols_by(var = "ARM") %>%
  split_rows_by(var = "AVISIT") %>%
  analyze_vars(
    vars = "AVAL",
    .stats = c("n", "mean_sd", "quantiles"),
    .formats = c("mean_sd" = "xx.x, xx.x"),
    .labels = c(n = "n", mean_sd = "Mean, SD", quantiles = c("Q1 - Q3"))
  )

build_table(l, df = dta_test)

## Use arguments interpreted by `s_summary`.
l <- basic_table() %>%
  split_cols_by(var = "ARM") %>%
  split_rows_by(var = "AVISIT") %>%
  analyze_vars(vars = "AVAL", na_rm = FALSE)

build_table(l, df = dta_test)

## Handle `NA` levels first when summarizing factors.
dta_test$AVISIT <- NA_character_
dta_test <- df_explicit_na(dta_test)
l <- basic_table() %>%
  split_cols_by(var = "ARM") %>%
  analyze_vars(vars = "AVISIT", na_rm = FALSE)

build_table(l, df = dta_test)

# auto format
dt <- data.frame("VAR" = c(0.001, 0.2, 0.0011000, 3, 4))
basic_table() %>%
  analyze_vars(
    vars = "VAR",
    .stats = c("n", "mean", "mean_sd", "range"),
    .formats = c("mean_sd" = "auto", "range" = "auto")
  ) %>%
  build_table(dt)

# `s_summary.numeric`

## Basic usage: empty numeric returns NA-filled items.
s_summary(numeric())

## Management of NA values.
x <- c(NA_real_, 1)
s_summary(x, na_rm = TRUE)
s_summary(x, na_rm = FALSE)

x <- c(NA_real_, 1, 2)
s_summary(x)

## Benefits in `rtables` contructions:
dta_test <- data.frame(
  Group = rep(LETTERS[seq(3)], each = 2),
  sub_group = rep(letters[seq(2)], each = 3),
  x = seq(6)
)

## The summary obtained in with `rtables`:
basic_table() %>%
  split_cols_by(var = "Group") %>%
  split_rows_by(var = "sub_group") %>%
  analyze(vars = "x", afun = s_summary) %>%
  build_table(df = dta_test)

## By comparison with `lapply`:
X <- split(dta_test, f = with(dta_test, interaction(Group, sub_group)))
lapply(X, function(x) s_summary(x$x))

# `s_summary.factor`

## Basic usage:
s_summary(factor(c("a", "a", "b", "c", "a")))

# Empty factor returns zero-filled items.
s_summary(factor(levels = c("a", "b", "c")))

## Management of NA values.
x <- factor(c(NA, "Female"))
x <- explicit_na(x)
s_summary(x, na_rm = TRUE)
s_summary(x, na_rm = FALSE)

## Different denominators.
x <- factor(c("a", "a", "b", "c", "a"))
s_summary(x, denom = "N_row", .N_row = 10L)
s_summary(x, denom = "N_col", .N_col = 20L)

# `s_summary.character`

## Basic usage:
s_summary(c("a", "a", "b", "c", "a"), verbose = FALSE)
s_summary(c("a", "a", "b", "c", "a", ""), .var = "x", na_rm = FALSE, verbose = FALSE)

# `s_summary.logical`

## Basic usage:
s_summary(c(TRUE, FALSE, TRUE, TRUE))

# Empty factor returns zero-filled items.
s_summary(as.logical(c()))

## Management of NA values.
x <- c(NA, TRUE, FALSE)
s_summary(x, na_rm = TRUE)
s_summary(x, na_rm = FALSE)

## Different denominators.
x <- c(TRUE, FALSE, TRUE, TRUE)
s_summary(x, denom = "N_row", .N_row = 10L)
s_summary(x, denom = "N_col", .N_col = 20L)

a_summary(factor(c("a", "a", "b", "c", "a")), .N_row = 10, .N_col = 10)
a_summary(
  factor(c("a", "a", "b", "c", "a")),
  .ref_group = factor(c("a", "a", "b", "c")), compare_with_ref_group = TRUE, .in_ref_col = TRUE
)

a_summary(c("A", "B", "A", "C"), .var = "x", .N_col = 10, .N_row = 10, verbose = FALSE)
a_summary(
  c("A", "B", "A", "C"),
  .ref_group = c("B", "A", "C"), .var = "x", compare_with_ref_group = TRUE, verbose = FALSE,
  .in_ref_col = FALSE
)

a_summary(c(TRUE, FALSE, FALSE, TRUE, TRUE), .N_row = 10, .N_col = 10)
a_summary(
  c(TRUE, FALSE, FALSE, TRUE, TRUE),
  .ref_group = c(TRUE, FALSE), .in_ref_col = TRUE, compare_with_ref_group = TRUE,
  .in_ref_col = FALSE
)

a_summary(rnorm(10), .N_col = 10, .N_row = 20, .var = "bla")
a_summary(rnorm(10, 5, 1),
  .ref_group = rnorm(20, -5, 1), .var = "bla", compare_with_ref_group = TRUE,
  .in_ref_col = FALSE
)

Analyze numeric variables in columns

Description

The layout-creating function analyze_vars_in_cols() creates a layout element to generate a column-wise analysis table.

This function sets the analysis methods as column labels and is a wrapper for rtables::analyze_colvars(). It was designed principally for PK tables.

Usage

analyze_vars_in_cols(
  lyt,
  vars,
  ...,
  .stats = c("n", "mean", "sd", "se", "cv", "geom_cv"),
  .labels = c(n = "n", mean = "Mean", sd = "SD", se = "SE", cv = "CV (%)", geom_cv =
    "CV % Geometric Mean"),
  row_labels = NULL,
  do_summarize_row_groups = FALSE,
  split_col_vars = TRUE,
  imp_rule = NULL,
  avalcat_var = "AVALCAT1",
  cache = FALSE,
  .indent_mods = NULL,
  na_str = default_na_str(),
  nested = TRUE,
  .formats = NULL,
  .aligns = NULL
)

Arguments

Value

A layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will summarize the given variables, arrange the output in columns, and add it to the table layout.

Note

• This is an experimental implementation of rtables::summarize_row_groups() and rtables::analyze_colvars() that may be subjected to changes as rtables extends its support to more complex analysis pipelines in the column space. We encourage users to read the examples carefully and file issues for different use cases.

• In this function, labelstr behaves atypically. If labelstr = NULL (the default), row labels are assigned automatically as the split values if do_summarize_row_groups = FALSE (the default), and as the group label if do_summarize_row_groups = TRUE.

See Also

analyze_vars(), rtables::analyze_colvars().

Examples

library(dplyr)

# Data preparation
adpp <- tern_ex_adpp %>% h_pkparam_sort()

lyt <- basic_table() %>%
  split_rows_by(var = "STRATA1", label_pos = "topleft") %>%
  split_rows_by(
    var = "SEX",
    label_pos = "topleft",
    child_labels = "hidden"
  ) %>% # Removes duplicated labels
  analyze_vars_in_cols(vars = "AGE")
result <- build_table(lyt = lyt, df = adpp)
result

# By selecting just some statistics and ad-hoc labels
lyt <- basic_table() %>%
  split_rows_by(var = "ARM", label_pos = "topleft") %>%
  split_rows_by(
    var = "SEX",
    label_pos = "topleft",
    child_labels = "hidden",
    split_fun = drop_split_levels
  ) %>%
  analyze_vars_in_cols(
    vars = "AGE",
    .stats = c("n", "cv", "geom_mean"),
    .labels = c(
      n = "aN",
      cv = "aCV",
      geom_mean = "aGeomMean"
    )
  )
result <- build_table(lyt = lyt, df = adpp)
result

# Changing row labels
lyt <- basic_table() %>%
  analyze_vars_in_cols(
    vars = "AGE",
    row_labels = "some custom label"
  )
result <- build_table(lyt, df = adpp)
result

# Pharmacokinetic parameters
lyt <- basic_table() %>%
  split_rows_by(
    var = "TLG_DISPLAY",
    split_label = "PK Parameter",
    label_pos = "topleft",
    child_labels = "hidden"
  ) %>%
  analyze_vars_in_cols(
    vars = "AVAL"
  )
result <- build_table(lyt, df = adpp)
result

# Multiple calls (summarize label and analyze underneath)
lyt <- basic_table() %>%
  split_rows_by(
    var = "TLG_DISPLAY",
    split_label = "PK Parameter",
    label_pos = "topleft"
  ) %>%
  analyze_vars_in_cols(
    vars = "AVAL",
    do_summarize_row_groups = TRUE # does a summarize level
  ) %>%
  split_rows_by("SEX",
    child_labels = "hidden",
    label_pos = "topleft"
  ) %>%
  analyze_vars_in_cols(
    vars = "AVAL",
    split_col_vars = FALSE # avoids re-splitting the columns
  )
result <- build_table(lyt, df = adpp)
result

Add variable labels to top left corner in table

Description

Helper layout-creating function to append the variable labels of a given variables vector from a given dataset in the top left corner. If a variable label is not found then the variable name itself is used instead. Multiple variable labels are concatenated with slashes.

Usage

append_varlabels(lyt, df, vars, indent = 0L)

Arguments

Value

A modified layout with the new variable label(s) added to the top-left material.

Note

This is not an optimal implementation of course, since we are using here the data set itself during the layout creation. When we have a more mature rtables implementation then this will also be improved or not necessary anymore.

Examples

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  add_colcounts() %>%
  split_rows_by("SEX") %>%
  append_varlabels(DM, "SEX") %>%
  analyze("AGE", afun = mean) %>%
  append_varlabels(DM, "AGE", indent = 1)
build_table(lyt, DM)

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  split_rows_by("SEX") %>%
  analyze("AGE", afun = mean) %>%
  append_varlabels(DM, c("SEX", "AGE"))
build_table(lyt, DM)

Apply automatic formatting

Description

Checks if any of the listed formats in .formats are "auto", and replaces "auto" with the correct implementation of format_auto for the given statistics, data, and variable.

Usage

apply_auto_formatting(.formats, x_stats, .df_row, .var)

Arguments

Standard arguments

Description

The documentation to this function lists all the arguments in tern that are used repeatedly to express an analysis.

Arguments

Details

Although this function just returns NULL it has two uses, for the tern users it provides a documentation of arguments that are commonly and consistently used in the framework. For the developer it adds a single reference point to import the roxygen argument description with: ⁠@inheritParams argument_convention⁠

Arrange multiple grobs

Description

Arrange grobs as a new grob with n * m (rows * cols) layout.

Usage

arrange_grobs(
  ...,
  grobs = list(...),
  ncol = NULL,
  nrow = NULL,
  padding_ht = grid::unit(2, "line"),
  padding_wt = grid::unit(2, "line"),
  vp = NULL,
  gp = NULL,
  name = NULL
)

Arguments

Value

A grob.

Examples

library(grid)


num <- lapply(1:9, textGrob)
grid::grid.newpage()
grid.draw(arrange_grobs(grobs = num, ncol = 2))

showViewport()

g1 <- circleGrob(gp = gpar(col = "blue"))
g2 <- circleGrob(gp = gpar(col = "red"))
g3 <- textGrob("TEST TEXT")
grid::grid.newpage()
grid.draw(arrange_grobs(g1, g2, g3, nrow = 2))

showViewport()

grid::grid.newpage()
grid.draw(arrange_grobs(g1, g2, g3, ncol = 3))

grid::grid.newpage()
grid::pushViewport(grid::viewport(layout = grid::grid.layout(1, 2)))
vp1 <- grid::viewport(layout.pos.row = 1, layout.pos.col = 2)
grid.draw(arrange_grobs(g1, g2, g3, ncol = 2, vp = vp1))

showViewport()

Convert to rtable

Description

This is a new generic function to convert objects to rtable tables.

Usage

as.rtable(x, ...)

## S3 method for class 'data.frame'
as.rtable(x, format = "xx.xx", ...)

Arguments

Value

An rtables table object. Note that the concrete class will depend on the method used.

Methods (by class)

• as.rtable(data.frame): Method for converting a data.frame that contains numeric columns to rtable.

Examples

x <- data.frame(
  a = 1:10,
  b = rnorm(10)
)
as.rtable(x)

Additional assertions to use with checkmate

Description

Additional assertion functions which can be used together with the checkmate package.

Usage

assert_list_of_variables(x, .var.name = checkmate::vname(x), add = NULL)

assert_df_with_variables(
  df,
  variables,
  na_level = NULL,
  .var.name = checkmate::vname(df),
  add = NULL
)

assert_valid_factor(
  x,
  min.levels = 1,
  max.levels = NULL,
  null.ok = TRUE,
  any.missing = TRUE,
  n.levels = NULL,
  len = NULL,
  .var.name = checkmate::vname(x),
  add = NULL
)

assert_df_with_factors(
  df,
  variables,
  min.levels = 1,
  max.levels = NULL,
  any.missing = TRUE,
  na_level = NULL,
  .var.name = checkmate::vname(df),
  add = NULL
)

assert_proportion_value(x, include_boundaries = FALSE)

Arguments

Value

Nothing if assertion passes, otherwise prints the error message.

Functions

• assert_list_of_variables(): Checks whether x is a valid list of variable names. NULL elements of the list x are dropped with Filter(Negate(is.null), x).

• assert_df_with_variables(): Check whether df is a data frame with the analysis variables. Please notice how this produces an error when not all variables are present in the data.frame while the opposite is not required.

• assert_valid_factor(): Check whether x is a valid factor (i.e. has levels and no empty string levels). Note that NULL and NA elements are allowed.

• assert_df_with_factors(): Check whether df is a data frame where the analysis variables are all factors. Note that the creation of NA by direct call of factor() will trim NA levels out of the vector list itself.

• assert_proportion_value(): Check whether x is a proportion: number between 0 and 1.

Examples

x <- data.frame(
  a = 1:10,
  b = rnorm(10)
)
assert_df_with_variables(x, variables = list(a = "a", b = "b"))

x <- ex_adsl
assert_df_with_variables(x, list(a = "ARM", b = "USUBJID"))

x <- ex_adsl
assert_df_with_factors(x, list(a = "ARM"))

assert_proportion_value(0.95)
assert_proportion_value(1.0, include_boundaries = TRUE)

Labels for bins in percent

Description

This creates labels for quantile based bins in percent. This assumes the right-closed intervals as produced by cut_quantile_bins().

Usage

bins_percent_labels(probs, digits = 0)

Arguments

Value

A character vector with labels in the format ⁠[0%,20%]⁠, ⁠(20%,50%]⁠, etc.

Content row function to add row total to labels

Description

This takes the label of the latest row split level and adds the row total from df in parentheses. This function differs from c_label_n_alt() by taking row counts from df rather than alt_counts_df, and is used by add_rowcounts() when alt_counts is set to FALSE.

Usage

c_label_n(df, labelstr, .N_row)

Arguments

Value

A list with formatted rtables::CellValue() with the row count value and the correct label.

Note

It is important here to not use df but rather .N_row in the implementation, because the former is already split by columns and will refer to the first column of the data only.

See Also

c_label_n_alt() which performs the same function but retrieves row counts from alt_counts_df instead of df.

Content row function to add alt_counts_df row total to labels

Description

This takes the label of the latest row split level and adds the row total from alt_counts_df in parentheses. This function differs from c_label_n() by taking row counts from alt_counts_df rather than df, and is used by add_rowcounts() when alt_counts is set to TRUE.

Usage

c_label_n_alt(df, labelstr, .alt_df_row)

Arguments

Value

A list with formatted rtables::CellValue() with the row count value and the correct label.

See Also

c_label_n() which performs the same function but retrieves row counts from df instead of alt_counts_df.

Constructor for content functions given a data frame with flag input

Description

This can be useful for tabulating model results.

Usage

cfun_by_flag(analysis_var, flag_var, format = "xx", .indent_mods = NULL)

Arguments

Value

A content function which gives df$analysis_var at the row identified by .df_row$flag in the given format.

Check proportion difference arguments

Description

Verifies that and/or convert arguments into valid values to be used in the estimation of difference in responder proportions.

Usage

check_diff_prop_ci(rsp, grp, strata = NULL, conf_level, correct = NULL)

Arguments

Examples

# example code
## "Mid" case: 4/4 respond in group A, 1/2 respond in group B.
nex <- 100 # Number of example rows
dta <- data.frame(
  "rsp" = sample(c(TRUE, FALSE), nex, TRUE),
  "grp" = sample(c("A", "B"), nex, TRUE),
  "f1" = sample(c("a1", "a2"), nex, TRUE),
  "f2" = sample(c("x", "y", "z"), nex, TRUE),
  stringsAsFactors = TRUE
)
check_diff_prop_ci(rsp = dta[["rsp"]], grp = dta[["grp"]], conf_level = 0.95)

Check element dimension

Description

Checks if the elements in ... have the same dimension.

Usage

check_same_n(..., omit_null = TRUE)

Arguments

Value

A logical value.

Wrapper function of survival::clogit

Description

When model fitting failed, a more useful message would show.

Usage

clogit_with_tryCatch(formula, data, ...)

Arguments

Value

When model fitting is successful, an object of class "clogit".
When model fitting failed, an error message is shown.

Examples

## Not run: 
library(dplyr)
adrs_local <- tern_ex_adrs %>%
  dplyr::filter(ARMCD %in% c("ARM A", "ARM B")) %>%
  dplyr::mutate(
    RSP = dplyr::case_when(AVALC %in% c("PR", "CR") ~ 1, TRUE ~ 0),
    ARMBIN = droplevels(ARMCD)
  )
dta <- adrs_local
dta <- dta[sample(nrow(dta)), ]
mod <- clogit_with_tryCatch(formula = RSP ~ ARMBIN * AGE + strata(STRATA1), data = dta)

## End(Not run)

Class for CombinationFunction

Description

CombinationFunction is an S4 class which extends standard functions. These are special functions that can be combined and negated with the logical operators.

Usage

## S4 method for signature 'CombinationFunction,CombinationFunction'
e1 & e2

## S4 method for signature 'CombinationFunction,CombinationFunction'
e1 | e2

## S4 method for signature 'CombinationFunction'
!x

Arguments

Value

A logical value indicating whether the left hand side of the equation equals the right hand side.

Functions

• e1 & e2: Logical "AND" combination of CombinationFunction functions. The resulting object is of the same class, and evaluates the two argument functions. The result is then the "AND" of the two individual results.

• e1 | e2: Logical "OR" combination of CombinationFunction functions. The resulting object is of the same class, and evaluates the two argument functions. The result is then the "OR" of the two individual results.

• `!`(CombinationFunction): Logical negation of CombinationFunction functions. The resulting object is of the same class, and evaluates the original function. The result is then the opposite of this results.

Examples

higher <- function(a) {
  force(a)
  CombinationFunction(
    function(x) {
      x > a
    }
  )
}

lower <- function(b) {
  force(b)
  CombinationFunction(
    function(x) {
      x < b
    }
  )
}

c1 <- higher(5)
c2 <- lower(10)
c3 <- higher(5) & lower(10)
c3(7)

Combine counts

Description

Simplifies the estimation of column counts, especially when group combination is required.

Usage

combine_counts(fct, groups_list = NULL)

Arguments

Value

A vector of column counts.

See Also

combine_groups()

Examples

ref <- c("A: Drug X", "B: Placebo")
groups <- combine_groups(fct = DM$ARM, ref = ref)

col_counts <- combine_counts(
  fct = DM$ARM,
  groups_list = groups
)

basic_table() %>%
  split_cols_by_groups("ARM", groups) %>%
  add_colcounts() %>%
  analyze_vars("AGE") %>%
  build_table(DM, col_counts = col_counts)

ref <- "A: Drug X"
groups <- combine_groups(fct = DM$ARM, ref = ref)
col_counts <- combine_counts(
  fct = DM$ARM,
  groups_list = groups
)

basic_table() %>%
  split_cols_by_groups("ARM", groups) %>%
  add_colcounts() %>%
  analyze_vars("AGE") %>%
  build_table(DM, col_counts = col_counts)

Reference and treatment group combination

Description

Facilitate the re-combination of groups divided as reference and treatment groups; it helps in arranging groups of columns in the rtables framework and teal modules.

Usage

combine_groups(fct, ref = NULL, collapse = "/")

Arguments

Value

A list with first item ref (reference) and second item trt (treatment).

Examples

groups <- combine_groups(
  fct = DM$ARM,
  ref = c("B: Placebo")
)

basic_table() %>%
  split_cols_by_groups("ARM", groups) %>%
  add_colcounts() %>%
  analyze_vars("AGE") %>%
  build_table(DM)

Element-wise combination of two vectors

Description

Element-wise combination of two vectors

Usage

combine_vectors(x, y)

Arguments

Value

A list where each element combines corresponding elements of x and y.

Examples

combine_vectors(1:3, 4:6)

Compare variables between groups

Description

The analyze function compare_vars() creates a layout element to summarize and compare one or more variables, using the S3 generic function s_summary() to calculate a list of summary statistics. A list of all available statistics for numeric variables can be viewed by running get_stats("analyze_vars_numeric", add_pval = TRUE) and for non-numeric variables by running get_stats("analyze_vars_counts", add_pval = TRUE). Use the .stats parameter to specify the statistics to include in your output summary table.

Prior to using this function in your table layout you must use rtables::split_cols_by() to create a column split on the variable to be used in comparisons, and specify a reference group via the ref_group parameter. Comparisons can be performed for each group (column) against the specified reference group by including the p-value statistic.

Usage

compare_vars(
  lyt,
  vars,
  var_labels = vars,
  na_str = default_na_str(),
  nested = TRUE,
  ...,
  na_rm = TRUE,
  show_labels = "default",
  table_names = vars,
  section_div = NA_character_,
  .stats = c("n", "mean_sd", "count_fraction", "pval"),
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

s_compare(x, ...)

## S3 method for class 'numeric'
s_compare(x, ...)

## S3 method for class 'factor'
s_compare(x, ...)

## S3 method for class 'character'
s_compare(x, ...)

## S3 method for class 'logical'
s_compare(x, ...)

Arguments

Value

• compare_vars() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing the statistics from s_compare() to the table layout.

• s_compare() returns output of s_summary() and comparisons versus the reference group in the form of p-values.

Functions

• compare_vars(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::analyze().

• s_compare(): S3 generic function to produce a comparison summary.

• s_compare(numeric): Method for numeric class. This uses the standard t-test to calculate the p-value.

• s_compare(factor): Method for factor class. This uses the chi-squared test to calculate the p-value.

• s_compare(character): Method for character class. This makes an automatic conversion to factor (with a warning) and then forwards to the method for factors.

• s_compare(logical): Method for logical class. A chi-squared test is used. If missing values are not removed, then they are counted as FALSE.

Note

• For factor variables, denom for factor proportions can only be n since the purpose is to compare proportions between columns, therefore a row-based proportion would not make sense. Proportion based on N_col would be difficult since we use counts for the chi-squared test statistic, therefore missing values should be accounted for as explicit factor levels.

• If factor variables contain NA, these NA values are excluded by default. To include NA values set na.rm = FALSE and missing values will be displayed as an NA level. Alternatively, an explicit factor level can be defined for NA values during pre-processing via df_explicit_na() - the default na_level ("<Missing>") will also be excluded when na.rm is set to TRUE.

• For character variables, automatic conversion to factor does not guarantee that the table will be generated correctly. In particular for sparse tables this very likely can fail. Therefore it is always better to manually convert character variables to factors during pre-processing.

• For compare_vars(), the column split must define a reference group via ref_group so that the comparison is well defined.

See Also

s_summary() which is used internally to compute a summary within s_compare(), and a_summary() which is used (with compare = TRUE) as the analysis function for compare_vars().

Examples

# `compare_vars()` in `rtables` pipelines

## Default output within a `rtables` pipeline.
lyt <- basic_table() %>%
  split_cols_by("ARMCD", ref_group = "ARM B") %>%
  compare_vars(c("AGE", "SEX"))
build_table(lyt, tern_ex_adsl)

## Select and format statistics output.
lyt <- basic_table() %>%
  split_cols_by("ARMCD", ref_group = "ARM C") %>%
  compare_vars(
    vars = "AGE",
    .stats = c("mean_sd", "pval"),
    .formats = c(mean_sd = "xx.x, xx.x"),
    .labels = c(mean_sd = "Mean, SD")
  )
build_table(lyt, df = tern_ex_adsl)

# `s_compare.numeric`

## Usual case where both this and the reference group vector have more than 1 value.
s_compare(rnorm(10, 5, 1), .ref_group = rnorm(5, -5, 1), .in_ref_col = FALSE)

## If one group has not more than 1 value, then p-value is not calculated.
s_compare(rnorm(10, 5, 1), .ref_group = 1, .in_ref_col = FALSE)

## Empty numeric does not fail, it returns NA-filled items and no p-value.
s_compare(numeric(), .ref_group = numeric(), .in_ref_col = FALSE)

# `s_compare.factor`

## Basic usage:
x <- factor(c("a", "a", "b", "c", "a"))
y <- factor(c("a", "b", "c"))
s_compare(x = x, .ref_group = y, .in_ref_col = FALSE)

## Management of NA values.
x <- explicit_na(factor(c("a", "a", "b", "c", "a", NA, NA)))
y <- explicit_na(factor(c("a", "b", "c", NA)))
s_compare(x = x, .ref_group = y, .in_ref_col = FALSE, na_rm = TRUE)
s_compare(x = x, .ref_group = y, .in_ref_col = FALSE, na_rm = FALSE)

# `s_compare.character`

## Basic usage:
x <- c("a", "a", "b", "c", "a")
y <- c("a", "b", "c")
s_compare(x, .ref_group = y, .in_ref_col = FALSE, .var = "x", verbose = FALSE)

## Note that missing values handling can make a large difference:
x <- c("a", "a", "b", "c", "a", NA)
y <- c("a", "b", "c", rep(NA, 20))
s_compare(x,
  .ref_group = y, .in_ref_col = FALSE,
  .var = "x", verbose = FALSE
)
s_compare(x,
  .ref_group = y, .in_ref_col = FALSE, .var = "x",
  na.rm = FALSE, verbose = FALSE
)

# `s_compare.logical`

## Basic usage:
x <- c(TRUE, FALSE, TRUE, TRUE)
y <- c(FALSE, FALSE, TRUE)
s_compare(x, .ref_group = y, .in_ref_col = FALSE)

## Management of NA values.
x <- c(NA, TRUE, FALSE)
y <- c(NA, NA, NA, NA, FALSE)
s_compare(x, .ref_group = y, .in_ref_col = FALSE, na_rm = TRUE)
s_compare(x, .ref_group = y, .in_ref_col = FALSE, na_rm = FALSE)

Control function for descriptive statistics

Description

Sets a list of parameters for summaries of descriptive statistics. Typically used internally to specify details for s_summary(). This function family is mainly used by analyze_vars().

Usage

control_analyze_vars(
  conf_level = 0.95,
  quantiles = c(0.25, 0.75),
  quantile_type = 2,
  test_mean = 0
)

Arguments

Value

A list of components with the same names as the arguments.

Control functions for Kaplan-Meier plot annotation tables

Description

Auxiliary functions for controlling arguments for formatting the annotation tables that can be added to plots generated via g_km().

Usage

control_surv_med_annot(x = 0.8, y = 0.85, w = 0.32, h = 0.16, fill = TRUE)

control_coxph_annot(
  x = 0.29,
  y = 0.51,
  w = 0.4,
  h = 0.125,
  fill = TRUE,
  ref_lbls = FALSE
)

Arguments

Value

A list of components with the same names as the arguments.

Functions

• control_surv_med_annot(): Control function for formatting the median survival time annotation table. This annotation table can be added in g_km() by setting annot_surv_med=TRUE, and can be configured using the control_surv_med_annot() function by setting it as the control_annot_surv_med argument.

• control_coxph_annot(): Control function for formatting the Cox-PH annotation table. This annotation table can be added in g_km() by setting annot_coxph=TRUE, and can be configured using the control_coxph_annot() function by setting it as the control_annot_coxph argument.

See Also

g_km()

Examples

control_surv_med_annot()

control_coxph_annot()

Control function for Cox-PH model

Description

This is an auxiliary function for controlling arguments for Cox-PH model, typically used internally to specify details of Cox-PH model for s_coxph_pairwise(). conf_level refers to Hazard Ratio estimation.

Usage

control_coxph(
  pval_method = c("log-rank", "wald", "likelihood"),
  ties = c("efron", "breslow", "exact"),
  conf_level = 0.95
)

Arguments

Value

A list of components with the same names as the arguments.

Control function for Cox regression

Description

Sets a list of parameters for Cox regression fit. Used internally.

Usage

control_coxreg(
  pval_method = c("wald", "likelihood"),
  ties = c("exact", "efron", "breslow"),
  conf_level = 0.95,
  interaction = FALSE
)

Arguments

Value

A list of items with names corresponding to the arguments.

See Also

fit_coxreg_univar() and fit_coxreg_multivar().

Examples

control_coxreg()

Control function for incidence rate

Description

This is an auxiliary function for controlling arguments for the incidence rate, used internally to specify details in s_incidence_rate().

Usage

control_incidence_rate(
  conf_level = 0.95,
  conf_type = c("normal", "normal_log", "exact", "byar"),
  input_time_unit = c("year", "day", "week", "month"),
  num_pt_year = 100
)

Arguments

Value

A list of components with the same names as the arguments.

See Also

incidence_rate

Examples

control_incidence_rate(0.9, "exact", "month", 100)

Control function for g_lineplot()

Description

Default values for variables parameter in g_lineplot function. A variable's default value can be overwritten for any variable.

Usage

control_lineplot_vars(
  x = "AVISIT",
  y = "AVAL",
  group_var = "ARM",
  facet_var = NA,
  paramcd = "PARAMCD",
  y_unit = "AVALU",
  subject_var = "USUBJID"
)

Arguments

Value

A named character vector of variable names.

Examples

control_lineplot_vars()
control_lineplot_vars(group_var = NA)

Control function for logistic regression model fitting

Description

This is an auxiliary function for controlling arguments for logistic regression models. conf_level refers to the confidence level used for the Odds Ratio CIs.

Usage

control_logistic(response_definition = "response", conf_level = 0.95)

Arguments

Value

A list of components with the same names as the arguments.

Examples

# Standard options.
control_logistic()

# Modify confidence level.
control_logistic(conf_level = 0.9)

# Use a different response definition.
control_logistic(response_definition = "I(response %in% c('CR', 'PR'))")

Control function for risk difference column

Description

Sets a list of parameters to use when generating a risk (proportion) difference column. Used as input to the riskdiff parameter of tabulate_rsp_subgroups() and tabulate_survival_subgroups().

Usage

control_riskdiff(
  arm_x = NULL,
  arm_y = NULL,
  format = "xx.x (xx.x - xx.x)",
  col_label = "Risk Difference (%) (95% CI)",
  pct = TRUE
)

Arguments

Value

A list of items with names corresponding to the arguments.

See Also

add_riskdiff(), tabulate_rsp_subgroups(), and tabulate_survival_subgroups().

Examples

control_riskdiff()
control_riskdiff(arm_x = "ARM A", arm_y = "ARM B")

Control function for subgroup treatment effect pattern (STEP) calculations

Description

This is an auxiliary function for controlling arguments for STEP calculations.

Usage

control_step(
  biomarker = NULL,
  use_percentile = TRUE,
  bandwidth,
  degree = 0L,
  num_points = 39L
)

Arguments

Value

A list of components with the same names as the arguments, except biomarker which is just used to calculate the bandwidth in case that actual biomarker windows are requested.

Examples

# Provide biomarker values and request actual values to be used,
# so that bandwidth is chosen from range.
control_step(biomarker = 1:10, use_percentile = FALSE)

# Use a global model with quadratic biomarker interaction term.
control_step(bandwidth = NULL, degree = 2)

# Reduce number of points to be used.
control_step(num_points = 10)

Control function for survfit models for survival time

Description

This is an auxiliary function for controlling arguments for survfit model, typically used internally to specify details of survfit model for s_surv_time(). conf_level refers to survival time estimation.

Usage

control_surv_time(
  conf_level = 0.95,
  conf_type = c("plain", "log", "log-log"),
  quantiles = c(0.25, 0.75)
)

Arguments

Value

A list of components with the same names as the arguments.

Control function for survfit models for patients' survival rate at time points

Description

This is an auxiliary function for controlling arguments for survfit model, typically used internally to specify details of survfit model for s_surv_timepoint(). conf_level refers to patient risk estimation at a time point.

Usage

control_surv_timepoint(
  conf_level = 0.95,
  conf_type = c("plain", "log", "log-log")
)

Arguments

Value

A list of components with the same names as the arguments.

Cumulative counts of numeric variable by thresholds

Description

The analyze function count_cumulative() creates a layout element to calculate cumulative counts of values in a numeric variable that are less than, less or equal to, greater than, or greater or equal to user-specified threshold values.

This function analyzes numeric variable vars against the threshold values supplied to the thresholds argument as a numeric vector. Whether counts should include the threshold values, and whether to count values lower or higher than the threshold values can be set via the include_eq and lower_tail parameters, respectively.

Usage

count_cumulative(
  lyt,
  vars,
  thresholds,
  lower_tail = TRUE,
  include_eq = TRUE,
  var_labels = vars,
  show_labels = "visible",
  na_str = default_na_str(),
  nested = TRUE,
  table_names = vars,
  ...,
  na_rm = TRUE,
  .stats = c("count_fraction"),
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

s_count_cumulative(
  x,
  thresholds,
  lower_tail = TRUE,
  include_eq = TRUE,
  denom = c("N_col", "n", "N_row"),
  .N_col,
  .N_row,
  na_rm = TRUE,
  ...
)

a_count_cumulative(
  x,
  ...,
  .stats = NULL,
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Value

• count_cumulative() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing the statistics from s_count_cumulative() to the table layout.

• s_count_cumulative() returns a named list of count_fractions: a list with each thresholds value as a component, each component containing a vector for the count and fraction.

• a_count_cumulative() returns the corresponding list with formatted rtables::CellValue().

Functions

• count_cumulative(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::analyze().

• s_count_cumulative(): Statistics function that produces a named list given a numeric vector of thresholds.

• a_count_cumulative(): Formatted analysis function which is used as afun in count_cumulative().

See Also

Relevant helper function h_count_cumulative(), and descriptive function d_count_cumulative().

Examples

basic_table() %>%
  split_cols_by("ARM") %>%
  add_colcounts() %>%
  count_cumulative(
    vars = "AGE",
    thresholds = c(40, 60)
  ) %>%
  build_table(tern_ex_adsl)

Count number of patients with missed doses by thresholds

Description

The analyze function creates a layout element to calculate cumulative counts of patients with number of missed doses at least equal to user-specified threshold values.

This function analyzes numeric variable vars, a variable with numbers of missed doses, against the threshold values supplied to the thresholds argument as a numeric vector. This function assumes that every row of the given data frame corresponds to a unique patient.

Usage

count_missed_doses(
  lyt,
  vars,
  thresholds,
  var_labels = vars,
  show_labels = "visible",
  na_str = default_na_str(),
  nested = TRUE,
  table_names = vars,
  ...,
  na_rm = TRUE,
  .stats = c("n", "count_fraction"),
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

s_count_missed_doses(
  x,
  thresholds,
  .N_col,
  .N_row,
  denom = c("N_col", "n", "N_row"),
  ...
)

a_count_missed_doses(
  x,
  ...,
  .stats = NULL,
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Value

• count_missed_doses() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing the statistics from s_count_missed_doses() to the table layout.

• s_count_missed_doses() returns the statistics n and count_fraction with one element for each threshold.

• a_count_missed_doses() returns the corresponding list with formatted rtables::CellValue().

Functions

• count_missed_doses(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::analyze().

• s_count_missed_doses(): Statistics function to count patients with missed doses.

• a_count_missed_doses(): Formatted analysis function which is used as afun in count_missed_doses().

See Also

• Relevant description function d_count_missed_doses() which generates labels for count_missed_doses().

• Similar analyze function count_cumulative() which more generally counts cumulative values and has more options for threshold handling, but uses different labels.

Examples

library(dplyr)

anl <- tern_ex_adsl %>%
  distinct(STUDYID, USUBJID, ARM) %>%
  mutate(
    PARAMCD = "TNDOSMIS",
    PARAM = "Total number of missed doses during study",
    AVAL = sample(0:20, size = nrow(tern_ex_adsl), replace = TRUE),
    AVALC = ""
  )

basic_table() %>%
  split_cols_by("ARM") %>%
  add_colcounts() %>%
  count_missed_doses("AVAL", thresholds = c(1, 5, 10, 15), var_labels = "Missed Doses") %>%
  build_table(anl, alt_counts_df = tern_ex_adsl)

Count occurrences

Description

The analyze function count_occurrences() creates a layout element to calculate occurrence counts for patients.

This function analyzes the variable(s) supplied to vars and returns a table of occurrence counts for each unique value (or level) of the variable(s). This variable (or variables) must be non-numeric. The id variable is used to indicate unique subject identifiers (defaults to USUBJID).

If there are multiple occurrences of the same value recorded for a patient, the value is only counted once.

The summarize function summarize_occurrences() performs the same function as count_occurrences() except it creates content rows, not data rows, to summarize the current table row/column context and operates on the level of the latest row split or the root of the table if no row splits have occurred.

Usage

count_occurrences(
  lyt,
  vars,
  id = "USUBJID",
  drop = TRUE,
  var_labels = vars,
  show_labels = "hidden",
  riskdiff = FALSE,
  na_str = default_na_str(),
  nested = TRUE,
  ...,
  table_names = vars,
  .stats = "count_fraction_fixed_dp",
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

summarize_occurrences(
  lyt,
  var,
  id = "USUBJID",
  drop = TRUE,
  riskdiff = FALSE,
  na_str = default_na_str(),
  ...,
  .stats = "count_fraction_fixed_dp",
  .stat_names = NULL,
  .formats = NULL,
  .indent_mods = 0L,
  .labels = NULL
)

s_count_occurrences(
  df,
  .var = "MHDECOD",
  .N_col,
  .N_row,
  .df_row,
  ...,
  drop = TRUE,
  id = "USUBJID",
  denom = c("N_col", "n", "N_row")
)

a_count_occurrences(
  df,
  labelstr = "",
  ...,
  .stats = NULL,
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Value

• count_occurrences() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing the statistics from s_count_occurrences() to the table layout.

• summarize_occurrences() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted content rows containing the statistics from s_count_occurrences() to the table layout.

• s_count_occurrences() returns a list with:

  • count: list of counts with one element per occurrence.

  • count_fraction: list of counts and fractions with one element per occurrence.

  • fraction: list of numerators and denominators with one element per occurrence.

• a_count_occurrences() returns the corresponding list with formatted rtables::CellValue().

Functions

• count_occurrences(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::analyze().

• summarize_occurrences(): Layout-creating function which can take content function arguments and additional format arguments. This function is a wrapper for rtables::summarize_row_groups().

• s_count_occurrences(): Statistics function which counts number of patients that report an occurrence.

• a_count_occurrences(): Formatted analysis function which is used as afun in count_occurrences().

Note

By default, occurrences which don't appear in a given row split are dropped from the table and the occurrences in the table are sorted alphabetically per row split. Therefore, the corresponding layout needs to use split_fun = drop_split_levels in the split_rows_by calls. Use drop = FALSE if you would like to show all occurrences.

Examples

library(dplyr)
df <- data.frame(
  USUBJID = as.character(c(
    1, 1, 2, 4, 4, 4,
    6, 6, 6, 7, 7, 8
  )),
  MHDECOD = c(
    "MH1", "MH2", "MH1", "MH1", "MH1", "MH3",
    "MH2", "MH2", "MH3", "MH1", "MH2", "MH4"
  ),
  ARM = rep(c("A", "B"), each = 6),
  SEX = c("F", "F", "M", "M", "M", "M", "F", "F", "F", "M", "M", "F")
)
df_adsl <- df %>%
  select(USUBJID, ARM) %>%
  unique()

# Create table layout
lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  add_colcounts() %>%
  count_occurrences(vars = "MHDECOD", .stats = c("count_fraction"))

# Apply table layout to data and produce `rtable` object
tbl <- lyt %>%
  build_table(df, alt_counts_df = df_adsl) %>%
  prune_table()

tbl

# Layout creating function with custom format.
basic_table() %>%
  add_colcounts() %>%
  split_rows_by("SEX", child_labels = "visible") %>%
  summarize_occurrences(
    var = "MHDECOD",
    .formats = c("count_fraction" = "xx.xx (xx.xx%)")
  ) %>%
  build_table(df, alt_counts_df = df_adsl)

# Count unique occurrences per subject.
s_count_occurrences(
  df,
  .N_col = 4L,
  .N_row = 4L,
  .df_row = df,
  .var = "MHDECOD",
  id = "USUBJID"
)

a_count_occurrences(
  df,
  .N_col = 4L,
  .df_row = df,
  .var = "MHDECOD",
  id = "USUBJID"
)

Count occurrences by grade

Description

The analyze function count_occurrences_by_grade() creates a layout element to calculate occurrence counts by grade.

This function analyzes primary analysis variable var which indicates toxicity grades. The id variable is used to indicate unique subject identifiers (defaults to USUBJID). The user can also supply a list of custom groups of grades to analyze via the grade_groups parameter. The remove_single argument will remove single grades from the analysis so that only grade groups are analyzed.

If there are multiple grades recorded for one patient only the highest grade level is counted.

The summarize function summarize_occurrences_by_grade() performs the same function as count_occurrences_by_grade() except it creates content rows, not data rows, to summarize the current table row/column context and operates on the level of the latest row split or the root of the table if no row splits have occurred.

Usage

count_occurrences_by_grade(
  lyt,
  var,
  id = "USUBJID",
  grade_groups = list(),
  remove_single = TRUE,
  only_grade_groups = FALSE,
  var_labels = var,
  show_labels = "default",
  riskdiff = FALSE,
  na_str = default_na_str(),
  nested = TRUE,
  ...,
  table_names = var,
  .stats = "count_fraction",
  .stat_names = NULL,
  .formats = list(count_fraction = format_count_fraction_fixed_dp),
  .labels = NULL,
  .indent_mods = NULL
)

summarize_occurrences_by_grade(
  lyt,
  var,
  id = "USUBJID",
  grade_groups = list(),
  remove_single = TRUE,
  only_grade_groups = FALSE,
  riskdiff = FALSE,
  na_str = default_na_str(),
  ...,
  .stats = "count_fraction",
  .stat_names = NULL,
  .formats = list(count_fraction = format_count_fraction_fixed_dp),
  .labels = NULL,
  .indent_mods = 0L
)

s_count_occurrences_by_grade(
  df,
  labelstr = "",
  .var,
  .N_row,
  .N_col,
  ...,
  id = "USUBJID",
  grade_groups = list(),
  remove_single = TRUE,
  only_grade_groups = FALSE,
  denom = c("N_col", "n", "N_row")
)

a_count_occurrences_by_grade(
  df,
  labelstr = "",
  ...,
  .stats = NULL,
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Value

• count_occurrences_by_grade() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing the statistics from s_count_occurrences_by_grade() to the table layout.

• summarize_occurrences_by_grade() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted content rows containing the statistics from s_count_occurrences_by_grade() to the table layout.

• s_count_occurrences_by_grade() returns a list of counts and fractions with one element per grade level or grade level grouping.

• a_count_occurrences_by_grade() returns the corresponding list with formatted rtables::CellValue().

Functions

• count_occurrences_by_grade(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::analyze().

• summarize_occurrences_by_grade(): Layout-creating function which can take content function arguments and additional format arguments. This function is a wrapper for rtables::summarize_row_groups().

• s_count_occurrences_by_grade(): Statistics function which counts the number of patients by highest grade.

• a_count_occurrences_by_grade(): Formatted analysis function which is used as afun in count_occurrences_by_grade().

See Also

Relevant helper function h_append_grade_groups().

Examples

library(dplyr)

df <- data.frame(
  USUBJID = as.character(c(1:6, 1)),
  ARM = factor(c("A", "A", "A", "B", "B", "B", "A"), levels = c("A", "B")),
  AETOXGR = factor(c(1, 2, 3, 4, 1, 2, 3), levels = c(1:5)),
  AESEV = factor(
    x = c("MILD", "MODERATE", "SEVERE", "MILD", "MILD", "MODERATE", "SEVERE"),
    levels = c("MILD", "MODERATE", "SEVERE")
  ),
  stringsAsFactors = FALSE
)

df_adsl <- df %>%
  select(USUBJID, ARM) %>%
  unique()

# Layout creating function with custom format.
basic_table() %>%
  split_cols_by("ARM") %>%
  add_colcounts() %>%
  count_occurrences_by_grade(
    var = "AESEV",
    .formats = c("count_fraction" = "xx.xx (xx.xx%)")
  ) %>%
  build_table(df, alt_counts_df = df_adsl)

# Define additional grade groupings.
grade_groups <- list(
  "-Any-" = c("1", "2", "3", "4", "5"),
  "Grade 1-2" = c("1", "2"),
  "Grade 3-5" = c("3", "4", "5")
)

basic_table() %>%
  split_cols_by("ARM") %>%
  add_colcounts() %>%
  count_occurrences_by_grade(
    var = "AETOXGR",
    grade_groups = grade_groups,
    only_grade_groups = TRUE
  ) %>%
  build_table(df, alt_counts_df = df_adsl)

# Layout creating function with custom format.
basic_table() %>%
  add_colcounts() %>%
  split_rows_by("ARM", child_labels = "visible", nested = TRUE) %>%
  summarize_occurrences_by_grade(
    var = "AESEV",
    .formats = c("count_fraction" = "xx.xx (xx.xx%)")
  ) %>%
  build_table(df, alt_counts_df = df_adsl)

basic_table() %>%
  add_colcounts() %>%
  split_rows_by("ARM", child_labels = "visible", nested = TRUE) %>%
  summarize_occurrences_by_grade(
    var = "AETOXGR",
    grade_groups = grade_groups
  ) %>%
  build_table(df, alt_counts_df = df_adsl)

s_count_occurrences_by_grade(
  df,
  .N_col = 10L,
  .var = "AETOXGR",
  id = "USUBJID",
  grade_groups = list("ANY" = levels(df$AETOXGR))
)

a_count_occurrences_by_grade(
  df,
  .N_col = 10L,
  .N_row = 10L,
  .var = "AETOXGR",
  id = "USUBJID",
  grade_groups = list("ANY" = levels(df$AETOXGR))
)

Count patient events in columns

Description

The summarize function summarize_patients_events_in_cols() creates a layout element to summarize patient event counts in columns.

This function analyzes the elements (events) supplied via the filters_list parameter and returns a row with counts of number of patients for each event as well as the total numbers of patients and events. The id variable is used to indicate unique subject identifiers (defaults to USUBJID).

If there are multiple occurrences of the same event recorded for a patient, the event is only counted once.

Usage

summarize_patients_events_in_cols(
  lyt,
  id = "USUBJID",
  filters_list = list(),
  empty_stats = character(),
  na_str = default_na_str(),
  ...,
  .stats = c("unique", "all", names(filters_list)),
  .labels = c(unique = "Patients (All)", all = "Events (All)",
    labels_or_names(filters_list)),
  col_split = TRUE
)

s_count_patients_and_multiple_events(
  df,
  id,
  filters_list,
  empty_stats = character(),
  labelstr = "",
  custom_label = NULL
)

Arguments

Value

• summarize_patients_events_in_cols() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted content rows containing the statistics from s_count_patients_and_multiple_events() to the table layout.

• s_count_patients_and_multiple_events() returns a list with the statistics:

  • unique: number of unique patients in df.

  • all: number of rows in df.

  • one element with the same name as in filters_list: number of rows in df, i.e. events, fulfilling the filter condition.

Functions

• summarize_patients_events_in_cols(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::summarize_row_groups().

• s_count_patients_and_multiple_events(): Statistics function which counts numbers of patients and multiple events defined by filters. Used as analysis function afun in summarize_patients_events_in_cols().

Examples

df <- data.frame(
  USUBJID = rep(c("id1", "id2", "id3", "id4"), c(2, 3, 1, 1)),
  ARM = c("A", "A", "B", "B", "B", "B", "A"),
  AESER = rep("Y", 7),
  AESDTH = c("Y", "Y", "N", "Y", "Y", "N", "N"),
  AEREL = c("Y", "Y", "N", "Y", "Y", "N", "Y"),
  AEDECOD = c("A", "A", "A", "B", "B", "C", "D"),
  AEBODSYS = rep(c("SOC1", "SOC2", "SOC3"), c(3, 3, 1))
)

# `summarize_patients_events_in_cols()`
basic_table() %>%
  summarize_patients_events_in_cols(
    filters_list = list(
      related = formatters::with_label(c(AEREL = "Y"), "Events (Related)"),
      fatal = c(AESDTH = "Y"),
      fatal_related = c(AEREL = "Y", AESDTH = "Y")
    ),
    custom_label = "%s Total number of patients and events"
  ) %>%
  build_table(df)

Count the number of patients with a particular event

Description

The analyze function count_patients_with_event() creates a layout element to calculate patient counts for a user-specified set of events.

This function analyzes primary analysis variable vars which indicates unique subject identifiers. Events are defined by the user as a named vector via the filters argument, where each name corresponds to a variable and each value is the value(s) that that variable takes for the event.

If there are multiple records with the same event recorded for a patient, only one occurrence is counted.

Usage

count_patients_with_event(
  lyt,
  vars,
  filters,
  riskdiff = FALSE,
  na_str = default_na_str(),
  nested = TRUE,
  show_labels = ifelse(length(vars) > 1, "visible", "hidden"),
  ...,
  table_names = vars,
  .stats = "count_fraction",
  .stat_names = NULL,
  .formats = list(count_fraction = format_count_fraction_fixed_dp),
  .labels = NULL,
  .indent_mods = NULL
)

s_count_patients_with_event(
  df,
  .var,
  .N_col = ncol(df),
  .N_row = nrow(df),
  ...,
  filters,
  denom = c("n", "N_col", "N_row")
)

a_count_patients_with_event(
  df,
  labelstr = "",
  ...,
  .stats = NULL,
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Value

• count_patients_with_event() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing the statistics from s_count_patients_with_event() to the table layout.

• s_count_patients_with_event() returns the count and fraction of unique identifiers with the defined event.

• a_count_patients_with_event() returns the corresponding list with formatted rtables::CellValue().

Functions

• count_patients_with_event(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::analyze().

• s_count_patients_with_event(): Statistics function which counts the number of patients for which the defined event has occurred.

• a_count_patients_with_event(): Formatted analysis function which is used as afun in count_patients_with_event().

See Also

count_patients_with_flags()

Examples

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  add_colcounts() %>%
  count_values(
    "STUDYID",
    values = "AB12345",
    .stats = "count",
    .labels = c(count = "Total AEs")
  ) %>%
  count_patients_with_event(
    "SUBJID",
    filters = c("TRTEMFL" = "Y"),
    .labels = c(count_fraction = "Total number of patients with at least one adverse event"),
    table_names = "tbl_all"
  ) %>%
  count_patients_with_event(
    "SUBJID",
    filters = c("TRTEMFL" = "Y", "AEOUT" = "FATAL"),
    .labels = c(count_fraction = "Total number of patients with fatal AEs"),
    table_names = "tbl_fatal"
  ) %>%
  count_patients_with_event(
    "SUBJID",
    filters = c("TRTEMFL" = "Y", "AEOUT" = "FATAL", "AEREL" = "Y"),
    .labels = c(count_fraction = "Total number of patients with related fatal AEs"),
    .indent_mods = c(count_fraction = 2L),
    table_names = "tbl_rel_fatal"
  )

build_table(lyt, tern_ex_adae, alt_counts_df = tern_ex_adsl)

s_count_patients_with_event(
  tern_ex_adae,
  .var = "SUBJID",
  filters = c("TRTEMFL" = "Y"),
)

s_count_patients_with_event(
  tern_ex_adae,
  .var = "SUBJID",
  filters = c("TRTEMFL" = "Y", "AEOUT" = "FATAL")
)

s_count_patients_with_event(
  tern_ex_adae,
  .var = "SUBJID",
  filters = c("TRTEMFL" = "Y", "AEOUT" = "FATAL"),
  denom = "N_col",
  .N_col = 456
)

a_count_patients_with_event(
  tern_ex_adae,
  .var = "SUBJID",
  filters = c("TRTEMFL" = "Y"),
  .N_col = 100,
  .N_row = 100
)

Count the number of patients with particular flags

Description

The analyze function count_patients_with_flags() creates a layout element to calculate counts of patients for which user-specified flags are present.

This function analyzes primary analysis variable var which indicates unique subject identifiers. Flags variables to analyze are specified by the user via the flag_variables argument, and must either take value TRUE (flag present) or FALSE (flag absent) for each record.

If there are multiple records with the same flag present for a patient, only one occurrence is counted.

Usage

count_patients_with_flags(
  lyt,
  var,
  flag_variables,
  flag_labels = NULL,
  var_labels = var,
  show_labels = "hidden",
  riskdiff = FALSE,
  na_str = default_na_str(),
  nested = TRUE,
  ...,
  table_names = paste0("tbl_flags_", var),
  .stats = "count_fraction",
  .stat_names = NULL,
  .formats = list(count_fraction = format_count_fraction_fixed_dp),
  .indent_mods = NULL,
  .labels = NULL
)

s_count_patients_with_flags(
  df,
  .var,
  .N_col = ncol(df),
  .N_row = nrow(df),
  ...,
  flag_variables,
  flag_labels = NULL,
  denom = c("n", "N_col", "N_row")
)

a_count_patients_with_flags(
  df,
  labelstr = "",
  ...,
  .stats = NULL,
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Value

• count_patients_with_flags() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing the statistics from s_count_patients_with_flags() to the table layout.

• s_count_patients_with_flags() returns the count and the fraction of unique identifiers with each particular flag as a list of statistics n, count, count_fraction, and n_blq, with one element per flag.

• a_count_patients_with_flags() returns the corresponding list with formatted rtables::CellValue().

Functions

• count_patients_with_flags(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::analyze().

• s_count_patients_with_flags(): Statistics function which counts the number of patients for which a particular flag variable is TRUE.

• a_count_patients_with_flags(): Formatted analysis function which is used as afun in count_patients_with_flags().

Note

If flag_labels is not specified, variables labels will be extracted from df. If variables are not labeled, variable names will be used instead. Alternatively, a named vector can be supplied to flag_variables such that within each name-value pair the name corresponds to the variable name and the value is the label to use for this variable.

See Also

count_patients_with_event

Examples

# Add labelled flag variables to analysis dataset.
adae <- tern_ex_adae %>%
  dplyr::mutate(
    fl1 = TRUE %>% with_label("Total AEs"),
    fl2 = (TRTEMFL == "Y") %>%
      with_label("Total number of patients with at least one adverse event"),
    fl3 = (TRTEMFL == "Y" & AEOUT == "FATAL") %>%
      with_label("Total number of patients with fatal AEs"),
    fl4 = (TRTEMFL == "Y" & AEOUT == "FATAL" & AEREL == "Y") %>%
      with_label("Total number of patients with related fatal AEs")
  )

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  add_colcounts() %>%
  count_patients_with_flags(
    "SUBJID",
    flag_variables = c("fl1", "fl2", "fl3", "fl4"),
    denom = "N_col"
  )

build_table(lyt, adae, alt_counts_df = tern_ex_adsl)

# `s_count_patients_with_flags()`

s_count_patients_with_flags(
  adae,
  "SUBJID",
  flag_variables = c("fl1", "fl2", "fl3", "fl4"),
  denom = "N_col",
  .N_col = 1000
)

a_count_patients_with_flags(
  adae,
  .N_col = 10L,
  .N_row = 10L,
  .var = "USUBJID",
  flag_variables = c("fl1", "fl2", "fl3", "fl4")
)

Count specific values

Description

The analyze function count_values() creates a layout element to calculate counts of specific values within a variable of interest.

This function analyzes one or more variables of interest supplied as a vector to vars. Values to count for variable(s) in vars can be given as a vector via the values argument. One row of counts will be generated for each variable.

Usage

count_values(
  lyt,
  vars,
  values,
  na_str = default_na_str(),
  na_rm = TRUE,
  nested = TRUE,
  ...,
  table_names = vars,
  .stats = "count_fraction",
  .stat_names = NULL,
  .formats = c(count_fraction = "xx (xx.xx%)", count = "xx"),
  .labels = c(count_fraction = paste(values, collapse = ", ")),
  .indent_mods = NULL
)

s_count_values(x, values, na.rm = TRUE, denom = c("n", "N_col", "N_row"), ...)

## S3 method for class 'character'
s_count_values(x, values = "Y", na.rm = TRUE, ...)

## S3 method for class 'factor'
s_count_values(x, values = "Y", ...)

## S3 method for class 'logical'
s_count_values(x, values = TRUE, ...)

a_count_values(
  x,
  ...,
  .stats = NULL,
  .stat_names = NULL,
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

Arguments

Value

• count_values() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add formatted rows containing the statistics from s_count_values() to the table layout.

• s_count_values() returns output of s_summary() for specified values of a non-numeric variable.

• a_count_values() returns the corresponding list with formatted rtables::CellValue().

Functions

• count_values(): Layout-creating function which can take statistics function arguments and additional format arguments. This function is a wrapper for rtables::analyze().

• s_count_values(): S3 generic function to count values.

• s_count_values(character): Method for character class.

• s_count_values(factor): Method for factor class. This makes an automatic conversion to character and then forwards to the method for characters.

• s_count_values(logical): Method for logical class.

• a_count_values(): Formatted analysis function which is used as afun in count_values().

Note

• For factor variables, s_count_values checks whether values are all included in the levels of x and fails otherwise.

• For count_values(), variable labels are shown when there is more than one element in vars, otherwise they are hidden.

Examples

# `count_values`
basic_table() %>%
  count_values("Species", values = "setosa") %>%
  build_table(iris)

# `s_count_values.character`
s_count_values(x = c("a", "b", "a"), values = "a")
s_count_values(x = c("a", "b", "a", NA, NA), values = "b", na.rm = FALSE)

# `s_count_values.factor`
s_count_values(x = factor(c("a", "b", "a")), values = "a")

# `s_count_values.logical`
s_count_values(x = c(TRUE, FALSE, TRUE))

# `a_count_values`
a_count_values(x = factor(c("a", "b", "a")), values = "a", .N_col = 10, .N_row = 10)

Cox proportional hazards regression

Description

Fits a Cox regression model and estimates hazard ratio to describe the effect size in a survival analysis.

Usage

summarize_coxreg(
  lyt,
  variables,
  control = control_coxreg(),
  at = list(),
  multivar = FALSE,
  common_var = "STUDYID",
  .stats = c("n", "hr", "ci", "pval", "pval_inter"),
  .formats = c(n = "xx", hr = "xx.xx", ci = "(xx.xx, xx.xx)", pval =
    "x.xxxx | (<0.0001)", pval_inter = "x.xxxx | (<0.0001)"),
  varlabels = NULL,
  .indent_mods = NULL,
  na_str = "",
  .section_div = NA_character_
)

s_coxreg(model_df, .stats, .which_vars = "all", .var_nms = NULL)

a_coxreg(
  df,
  labelstr,
  eff = FALSE,
  var_main = FALSE,
  multivar = FALSE,
  variables,
  at = list(),
  control = control_coxreg(),
  .spl_context,
  .stats,
  .formats,
  .indent_mods = NULL,
  na_str = "",
  cache_env = NULL
)

Arguments

Details

Cox models are the most commonly used methods to estimate the magnitude of the effect in survival analysis. It assumes proportional hazards: the ratio of the hazards between groups (e.g., two arms) is constant over time. This ratio is referred to as the "hazard ratio" (HR) and is one of the most commonly reported metrics to describe the effect size in survival analysis (NEST Team, 2020).

Value

• summarize_coxreg() returns a layout object suitable for passing to further layouting functions, or to rtables::build_table(). Adding this function to an rtable layout will add a Cox regression table containing the chosen statistics to the table layout.

• s_coxreg() returns the selected statistic for from the Cox regression model for the selected variable(s).

• a_coxreg() returns formatted rtables::CellValue().

Functions

• summarize_coxreg(): Layout-creating function which creates a Cox regression summary table layout. This function is a wrapper for several rtables layouting functions. This function is a wrapper for rtables::analyze_colvars() and rtables::summarize_row_groups().

• s_coxreg(): Statistics function that transforms results tabulated from fit_coxreg_univar() or fit_coxreg_multivar() into a list.

• a_coxreg(): Analysis function which is used as afun in rtables::analyze() and cfun in rtables::summarize_row_groups() within summarize_coxreg().

See Also

fit_coxreg for relevant fitting functions, h_cox_regression for relevant helper functions, and tidy_coxreg for custom tidy methods.

fit_coxreg_univar() and fit_coxreg_multivar() which also take the variables, data, at (univariate only), and control arguments but return unformatted univariate and multivariate Cox regression models, respectively.

Examples

library(survival)

# Testing dataset [survival::bladder].
set.seed(1, kind = "Mersenne-Twister")
dta_bladder <- with(
  data = bladder[bladder$enum < 5, ],
  tibble::tibble(
    TIME = stop,
    STATUS = event,
    ARM = as.factor(rx),
    COVAR1 = as.factor(enum) %>% formatters::with_label("A Covariate Label"),
    COVAR2 = factor(
      sample(as.factor(enum)),
      levels = 1:4, labels = c("F", "F", "M", "M")
    ) %>% formatters::with_label("Sex (F/M)")
  )
)
dta_bladder$AGE <- sample(20:60, size = nrow(dta_bladder), replace = TRUE)
dta_bladder$STUDYID <- factor("X")

u1_variables <- list(
  time = "TIME", event = "STATUS", arm = "ARM", covariates = c("COVAR1", "COVAR2")
)

u2_variables <- list(time = "TIME", event = "STATUS", covariates = c("COVAR1", "COVAR2"))

m1_variables <- list(
  time = "TIME", event = "STATUS", arm = "ARM", covariates = c("COVAR1", "COVAR2")
)

m2_variables <- list(time = "TIME", event = "STATUS", covariates = c("COVAR1", "COVAR2"))

# summarize_coxreg

result_univar <- basic_table() %>%
  summarize_coxreg(variables = u1_variables) %>%
  build_table(dta_bladder)
result_univar

result_univar_covs <- basic_table() %>%
  summarize_coxreg(
    variables = u2_variables,
  ) %>%
  build_table(dta_bladder)
result_univar_covs

result_multivar <- basic_table() %>%
  summarize_coxreg(
    variables = m1_variables,
    multivar = TRUE,
  ) %>%
  build_table(dta_bladder)
result_multivar

result_multivar_covs <- basic_table() %>%
  summarize_coxreg(
    variables = m2_variables,
    multivar = TRUE,
    varlabels = c("Covariate 1", "Covariate 2") # custom labels
  ) %>%
  build_table(dta_bladder)
result_multivar_covs

# s_coxreg

# Univariate
univar_model <- fit_coxreg_univar(variables = u1_variables, data = dta_bladder)
df1 <- broom::tidy(univar_model)

s_coxreg(model_df = df1, .stats = "hr")

# Univariate with interactions
univar_model_inter <- fit_coxreg_univar(
  variables = u1_variables, control = control_coxreg(interaction = TRUE), data = dta_bladder
)
df1_inter <- broom::tidy(univar_model_inter)

s_coxreg(model_df = df1_inter, .stats = "hr", .which_vars = "inter", .var_nms = "COVAR1")

# Univariate without treatment arm - only "COVAR2" covariate effects
univar_covs_model <- fit_coxreg_univar(variables = u2_variables, data = dta_bladder)
df1_covs <- broom::tidy(univar_covs_model)

s_coxreg(model_df = df1_covs, .stats = "hr", .var_nms = c("COVAR2", "Sex (F/M)"))

# Multivariate.
multivar_model <- fit_coxreg_multivar(variables = m1_variables, data = dta_bladder)
df2 <- broom::tidy(multivar_model)

s_coxreg(model_df = df2, .stats = "pval", .which_vars = "var_main", .var_nms = "COVAR1")
s_coxreg(
  model_df = df2, .stats = "pval", .which_vars = "multi_lvl",
  .var_nms = c("COVAR1", "A Covariate Label")
)

# Multivariate without treatment arm - only "COVAR1" main effect
multivar_covs_model <- fit_coxreg_multivar(variables = m2_variables, data = dta_bladder)
df2_covs <- broom::tidy(multivar_covs_model)

s_coxreg(model_df = df2_covs, .stats = "hr")

a_coxreg(
  df = dta_bladder,
  labelstr = "Label 1",
  variables = u1_variables,
  .spl_context = list(value = "COVAR1"),
  .stats = "n",
  .formats = "xx"
)

a_coxreg(
  df = dta_bladder,
  labelstr = "",
  variables = u1_variables,
  .spl_context = list(value = "COVAR2"),
  .stats = "pval",
  .formats = "xx.xxxx"
)

Cox regression helper function for interactions

Description

Test and estimate the effect of a treatment in interaction with a covariate. The effect is estimated as the HR of the tested treatment for a given level of the covariate, in comparison to the treatment control.

Usage

h_coxreg_inter_effect(x, effect, covar, mod, label, control, ...)

## S3 method for class 'numeric'
h_coxreg_inter_effect(x, effect, covar, mod, label, control, at, ...)

## S3 method for class 'factor'
h_coxreg_inter_effect(x, effect, covar, mod, label, control, data, ...)

## S3 method for class 'character'
h_coxreg_inter_effect(x, effect, covar, mod, label, control, data, ...)

h_coxreg_extract_interaction(effect, covar, mod, data, at, control)

h_coxreg_inter_estimations(
  variable,
  given,
  lvl_var,
  lvl_given,
  mod,
  conf_level = 0.95
)

Arguments

Details

Given the cox regression investigating the effect of Arm (A, B, C; reference A) and Sex (F, M; reference Female) and the model being abbreviated: y ~ Arm + Sex + Arm:Sex. The cox regression estimates the coefficients along with a variance-covariance matrix for:

• b1 (arm b), b2 (arm c)

• b3 (sex m)

• b4 (arm b: sex m), b5 (arm c: sex m)

The estimation of the Hazard Ratio for arm C/sex M is given in reference to arm A/Sex M by exp(b2 + b3 + b5)/ exp(b3) = exp(b2 + b5). The interaction coefficient is deduced by b2 + b5 while the standard error is obtained as $sqrt(Var b2 + Var b5 + 2 * covariance (b2,b5))$.

Value

• h_coxreg_inter_effect() returns a data.frame of covariate interaction effects consisting of the following variables: effect, term, term_label, level, n, hr, lcl, ucl, pval, and pval_inter.

• h_coxreg_extract_interaction() returns the result of an interaction test and the estimated values. If no interaction, h_coxreg_univar_extract() is applied instead.

• h_coxreg_inter_estimations() returns a list of matrices (one per level of variable) with rows corresponding to the combinations of variable and given, with columns:

  • coef_hat: Estimation of the coefficient.

  • coef_se: Standard error of the estimation.

  • hr: Hazard ratio.

  • ⁠lcl, ucl⁠: Lower/upper confidence limit of the hazard ratio.

Functions

• h_coxreg_inter_effect(): S3 generic helper function to determine interaction effect.

• h_coxreg_inter_effect(numeric): Method for numeric class. Estimates the interaction with a numeric covariate.

• h_coxreg_inter_effect(factor): Method for factor class. Estimate the interaction with a factor covariate.

• h_coxreg_inter_effect(character): Method for character class. Estimate the interaction with a character covariate. This makes an automatic conversion to factor and then forwards to the method for factors.

• h_coxreg_extract_interaction(): A higher level function to get the results of the interaction test and the estimated values.

• h_coxreg_inter_estimations(): Hazard ratio estimation in interactions.

Note

• Automatic conversion of character to factor does not guarantee results can be generated correctly. It is therefore better to always pre-process the dataset such that factors are manually created from character variables before passing the dataset to rtables::build_table().

Examples

library(survival)

set.seed(1, kind = "Mersenne-Twister")

# Testing dataset [survival::bladder].
dta_bladder <- with(
  data = bladder[bladder$enum < 5, ],
  data.frame(
    time = stop,
    status = event,
    armcd = as.factor(rx),
    covar1 = as.factor(enum),
    covar2 = factor(
      sample(as.factor(enum)),
      levels = 1:4,
      labels = c("F", "F", "M", "M")
    )
  )
)
labels <- c("armcd" = "ARM", "covar1" = "A Covariate Label", "covar2" = "Sex (F/M)")
formatters::var_labels(dta_bladder)[names(labels)] <- labels
dta_bladder$age <- sample(20:60, size = nrow(dta_bladder), replace = TRUE)

plot(
  survfit(Surv(time, status) ~ armcd + covar1, data = dta_bladder),
  lty = 2:4,
  xlab = "Months",
  col = c("blue1", "blue2", "blue3", "blue4", "red1", "red2", "red3", "red4")
)

mod <- coxph(Surv(time, status) ~ armcd * covar1, data = dta_bladder)
h_coxreg_extract_interaction(
  mod = mod, effect = "armcd", covar = "covar1", data = dta_bladder,
  control = control_coxreg()
)

mod <- coxph(Surv(time, status) ~ armcd * covar1, data = dta_bladder)
result <- h_coxreg_inter_estimations(
  variable = "armcd", given = "covar1",
  lvl_var = levels(dta_bladder$armcd),
  lvl_given = levels(dta_bladder$covar1),
  mod = mod, conf_level = .95
)
result

Cut numeric vector into empirical quantile bins

Description

This cuts a numeric vector into sample quantile bins.

Usage

cut_quantile_bins(
  x,
  probs = c(0.25, 0.5, 0.75),
  labels = NULL,
  type = 7,
  ordered = TRUE
)

Arguments

Value

• cut_quantile_bins: A factor variable with appropriately-labeled bins as levels.

Note

Intervals are closed on the right side. That is, the first bin is the interval ⁠[-Inf, q1]⁠ where q1 is the first quantile, the second bin is then ⁠(q1, q2]⁠, etc., and the last bin is ⁠(qn, +Inf]⁠ where qn is the last quantile.

Examples

# Default is to cut into quartile bins.
cut_quantile_bins(cars$speed)

# Use custom quantiles.
cut_quantile_bins(cars$speed, probs = c(0.1, 0.2, 0.6, 0.88))

# Use custom labels.
cut_quantile_bins(cars$speed, labels = paste0("Q", 1:4))

# NAs are preserved in result factor.
ozone_binned <- cut_quantile_bins(airquality$Ozone)
which(is.na(ozone_binned))
# So you might want to make these explicit.
explicit_na(ozone_binned)

Description function for s_count_abnormal_by_baseline()

Description

Description function that produces the labels for s_count_abnormal_by_baseline().

Usage

d_count_abnormal_by_baseline(abnormal)

Arguments

Value

Abnormal category labels for s_count_abnormal_by_baseline().

Examples

d_count_abnormal_by_baseline("LOW")

Description of cumulative count

Description

This is a helper function that describes the analysis in s_count_cumulative().

Usage

d_count_cumulative(threshold, lower_tail = TRUE, include_eq = TRUE)

Arguments

Value

Labels for s_count_cumulative().

Description function that calculates labels for s_count_missed_doses()

Description

Usage

d_count_missed_doses(thresholds)

Arguments

Value

d_count_missed_doses() returns a named character vector with the labels.

See Also

s_count_missed_doses()

Description of standard oncology response

Description

Describe the oncology response in a standard way.

Usage

d_onco_rsp_label(x)

Arguments

Value

Response labels.

See Also

estimate_multinomial_rsp()

Examples

d_onco_rsp_label(
  c("CR", "PR", "SD", "NON CR/PD", "PD", "NE", "Missing", "<Missing>", "NE/Missing")
)

# Adding some values not considered in d_onco_rsp_label

d_onco_rsp_label(
  c("CR", "PR", "hello", "hi")
)

Generate PK reference dataset

Description

Usage

d_pkparam()

Value

A data.frame of PK parameters.

Examples

pk_reference_dataset <- d_pkparam()

Description of the proportion summary

Description

This is a helper function that describes the analysis in s_proportion().

Usage

d_proportion(conf_level, method, long = FALSE)

Arguments

Value

String describing the analysis.

Description of method used for proportion comparison

Description

This is an auxiliary function that describes the analysis in s_proportion_diff().

Usage

d_proportion_diff(conf_level, method, long = FALSE)

Arguments

Value

A string describing the analysis.

See Also

prop_diff

Labels for column variables in binary response by subgroup table

Description

Internal function to check variables included in tabulate_rsp_subgroups() and create column labels.

Usage

d_rsp_subgroups_colvars(vars, conf_level = NULL, method = NULL)

Arguments

Value

A list of variables to tabulate and their labels.

Labels for column variables in survival duration by subgroup table

Description

Internal function to check variables included in tabulate_survival_subgroups() and create column labels.

Usage

d_survival_subgroups_colvars(vars, conf_level, method, time_unit = NULL)

Arguments

Value

A list of variables and their labels to tabulate.

Note

At least one of n_tot and n_tot_events must be provided in vars.

Description of the difference test between two proportions

Description

This is an auxiliary function that describes the analysis in s_test_proportion_diff.

Usage

d_test_proportion_diff(method)

Arguments

Value

A string describing the test from which the p-value is derived.

Conversion of days to months

Description

Conversion of days to months

Usage

day2month(x)

Arguments

Value

A numeric vector with the time in months.

Examples

x <- c(403, 248, 30, 86)
day2month(x)

Add titles, footnotes, page Number, and a bounding box to a grid grob

Description

This function is useful to label grid grobs (also ggplot2, and lattice plots) with title, footnote, and page numbers.

Usage

decorate_grob(
  grob,
  titles,
  footnotes,
  page = "",
  width_titles = grid::unit(1, "npc"),
  width_footnotes = grid::unit(1, "npc"),
  border = TRUE,
  padding = grid::unit(rep(1, 4), "lines"),
  margins = grid::unit(c(1, 0, 1, 0), "lines"),
  outer_margins = grid::unit(c(2, 1.5, 3, 1.5), "cm"),
  gp_titles = grid::gpar(),
  gp_footnotes = grid::gpar(fontsize = 8),
  name = NULL,
  gp = grid::gpar(),
  vp = NULL
)

Arguments

Details

The titles and footnotes will be ragged, i.e. each title will be wrapped individually.

Value

A grid grob (gTree).

Examples

library(grid)

titles <- c(
  "Edgar Anderson's Iris Data",
  paste(
    "This famous (Fisher's or Anderson's) iris data set gives the measurements",
    "in centimeters of the variables sepal length and width and petal length",
    "and width, respectively, for 50 flowers from each of 3 species of iris."
  )
)

footnotes <- c(
  "The species are Iris setosa, versicolor, and virginica.",
  paste(
    "iris is a data frame with 150 cases (rows) and 5 variables (columns) named",
    "Sepal.Length, Sepal.Width, Petal.Length, Petal.Width, and Species."
  )
)

## empty plot
grid.newpage()

grid.draw(
  decorate_grob(
    NULL,
    titles = titles,
    footnotes = footnotes,
    page = "Page 4 of 10"
  )
)

# grid
p <- gTree(
  children = gList(
    rectGrob(),
    xaxisGrob(),
    yaxisGrob(),
    textGrob("Sepal.Length", y = unit(-4, "lines")),
    textGrob("Petal.Length", x = unit(-3.5, "lines"), rot = 90),
    pointsGrob(iris$Sepal.Length, iris$Petal.Length, gp = gpar(col = iris$Species), pch = 16)
  ),
  vp = vpStack(plotViewport(), dataViewport(xData = iris$Sepal.Length, yData = iris$Petal.Length))
)
grid.newpage()
grid.draw(p)

grid.newpage()
grid.draw(
  decorate_grob(
    grob = p,
    titles = titles,
    footnotes = footnotes,
    page = "Page 6 of 129"
  )
)

## with ggplot2
library(ggplot2)

p_gg <- ggplot2::ggplot(iris, aes(Sepal.Length, Sepal.Width, col = Species)) +
  ggplot2::geom_point()
p_gg
p <- ggplotGrob(p_gg)
grid.newpage()
grid.draw(
  decorate_grob(
    grob = p,
    titles = titles,
    footnotes = footnotes,
    page = "Page 6 of 129"
  )
)

## with lattice
library(lattice)

xyplot(Sepal.Length ~ Petal.Length, data = iris, col = iris$Species)
p <- grid.grab()
grid.newpage()
grid.draw(
  decorate_grob(
    grob = p,
    titles = titles,
    footnotes = footnotes,
    page = "Page 6 of 129"
  )
)

# with gridExtra - no borders
library(gridExtra)
grid.newpage()
grid.draw(
  decorate_grob(
    tableGrob(
      head(mtcars)
    ),
    titles = "title",
    footnotes = "footnote",
    border = FALSE
  )
)

Update page number

Description

Automatically updates page number.

Usage

decorate_grob_factory(npages, ...)

Arguments

Value

Closure that increments the page number.

Decorate set of grobs and add page numbering

Description

Note that this uses the decorate_grob_factory() function.

Usage

decorate_grob_set(grobs, ...)

Arguments

Value

A decorated grob.

Examples

library(ggplot2)
library(grid)
g <- with(data = iris, {
  list(
    ggplot2::ggplotGrob(
      ggplot2::ggplot(mapping = aes(Sepal.Length, Sepal.Width, col = Species)) +
        ggplot2::geom_point()
    ),
    ggplot2::ggplotGrob(
      ggplot2::ggplot(mapping = aes(Sepal.Length, Petal.Length, col = Species)) +
        ggplot2::geom_point()
    ),
    ggplot2::ggplotGrob(
      ggplot2::ggplot(mapping = aes(Sepal.Length, Petal.Width, col = Species)) +
        ggplot2::geom_point()
    ),
    ggplot2::ggplotGrob(
      ggplot2::ggplot(mapping = aes(Sepal.Width, Petal.Length, col = Species)) +
        ggplot2::geom_point()
    ),
    ggplot2::ggplotGrob(
      ggplot2::ggplot(mapping = aes(Sepal.Width, Petal.Width, col = Species)) +
        ggplot2::geom_point()
    ),
    ggplot2::ggplotGrob(
      ggplot2::ggplot(mapping = aes(Petal.Length, Petal.Width, col = Species)) +
        ggplot2::geom_point()
    )
  )
})
lg <- decorate_grob_set(grobs = g, titles = "Hello\nOne\nTwo\nThree", footnotes = "")

draw_grob(lg[[1]])
draw_grob(lg[[2]])
draw_grob(lg[[6]])

Default string replacement for NA values

Description

The default string used to represent NA values. This value is used as the default value for the na_str argument throughout the tern package, and printed in place of NA values in output tables. If not specified for each tern function by the user via the na_str argument, or in the R environment options via set_default_na_str(), then NA is used.

Usage

default_na_str()

set_default_na_str(na_str)

Arguments

Value

• default_na_str returns the current value if an R environment option has been set for "tern_default_na_str", or NA_character_ otherwise.

• set_default_na_str has no return value.

Functions

• default_na_str(): Accessor for default NA value replacement string.

• set_default_na_str(): Setter for default NA value replacement string. Sets the option "tern_default_na_str" within the R environment.

Examples

# Default settings
default_na_str()
getOption("tern_default_na_str")

# Set custom value
set_default_na_str("<Missing>")

# Settings after value has been set
default_na_str()
getOption("tern_default_na_str")

Get default statistical methods and their associated formats, labels, and indent modifiers

Description

Utility functions to get valid statistic methods for different method groups (.stats) and their associated formats (.formats), labels (.labels), and indent modifiers (.indent_mods). This utility is used across tern, but some of its working principles can be seen in analyze_vars(). See notes to understand why this is experimental.

Usage

get_stats(
  method_groups = "analyze_vars_numeric",
  stats_in = NULL,
  custom_stats_in = NULL,
  add_pval = FALSE
)

get_stat_names(stat_results, stat_names_in = NULL)

get_formats_from_stats(
  stats,
  formats_in = NULL,
  levels_per_stats = NULL,
  tern_defaults = tern_default_formats
)

get_labels_from_stats(
  stats,
  labels_in = NULL,
  levels_per_stats = NULL,
  label_attr_from_stats = NULL,
  tern_defaults = tern_default_labels
)

get_indents_from_stats(
  stats,
  indents_in = NULL,
  levels_per_stats = NULL,
  tern_defaults = as.list(rep(0L, length(stats))) %>% setNames(stats),
  row_nms = lifecycle::deprecated()
)

tern_default_stats

tern_default_formats

tern_default_labels

summary_formats(type = "numeric", include_pval = FALSE)

summary_labels(type = "numeric", include_pval = FALSE)

Arguments