compare_variables: Compare variables between groups
In tern: Create Common TLGs Used in Clinical Trials

compare_variables

R Documentation

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"),
  .formats = NULL,
  .labels = NULL,
  .indent_mods = NULL
)

s_compare(x, .ref_group, .in_ref_col, ...)

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

## S3 method for class 'factor'
s_compare(x, .ref_group, .in_ref_col, denom = "n", na.rm = TRUE, ...)

## S3 method for class 'character'
s_compare(
  x,
  .ref_group,
  .in_ref_col,
  denom = "n",
  na.rm = TRUE,
  .var,
  verbose = TRUE,
  ...
)

## S3 method for class 'logical'
s_compare(x, .ref_group, .in_ref_col, na.rm = TRUE, denom = "n", ...)

Arguments

`lyt`	(`PreDataTableLayouts`) layout that analyses will be added to.
`vars`	(`character`) variable names for the primary analysis variable to be iterated over.
`var_labels`	(`character`) variable labels.
`na_str`	(`string`) string used to replace all `NA` or empty values in the output.
`nested`	(`flag`) whether this layout instruction should be applied within the existing layout structure _if possible (`TRUE`, the default) or as a new top-level element (`FALSE`). Ignored if it would nest a split. underneath analyses, which is not allowed.
`...`	arguments passed to `s_compare()`.
`na.rm`	(`flag`) whether `NA` values should be removed from `x` prior to analysis.
`show_labels`	(`string`) label visibility: one of "default", "visible" and "hidden".
`table_names`	(`character`) this can be customized in the case that the same `vars` are analyzed multiple times, to avoid warnings from `rtables`.
`section_div`	(`string`) string which should be repeated as a section divider after each group defined by this split instruction, or `NA_character_` (the default) for no section divider.
`.stats`	(`character`) statistics to select for the table. Run `get_stats("analyze_vars_numeric", add_pval = TRUE)` to see statistics available for numeric variables, and `get_stats("analyze_vars_counts", add_pval = TRUE)` for statistics available for non-numeric variables.
`.formats`	(named `character` or `list`) formats for the statistics. See Details in `analyze_vars` for more information on the `"auto"` setting.
`.labels`	(named `character`) labels for the statistics (without indent).
`.indent_mods`	(named `integer`) indent modifiers for the labels. Each element of the vector should be a name-value pair with name corresponding to a statistic specified in `.stats` and value the indentation for that statistic's row label.
`x`	(`numeric`) vector of numbers we want to analyze.
`.ref_group`	(`data.frame` or `vector`) the data corresponding to the reference group.
`.in_ref_col`	(`flag`) `TRUE` when working with the reference level, `FALSE` otherwise.
`denom`	(`string`) choice of denominator for factor proportions, can only be `n` (number of values in this row and column intersection).
`.var`	(`string`) single variable name that is passed by `rtables` when requested by a statistics function.
`verbose`	(`flag`) whether warnings and messages should be printed. Mainly used to print out information about factor casting. Defaults to `TRUE`.

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.

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)

tern documentation built on Sept. 24, 2024, 9:06 a.m.