compare_variables {tern} | 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"),
.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
lyt |
( |
vars |
( |
var_labels |
( |
na_str |
( |
nested |
( |
... |
additional arguments passed to
|
na_rm |
( |
show_labels |
( |
table_names |
( |
section_div |
( |
.stats |
( Options for numeric variables are: Options for non-numeric variables are: |
.stat_names |
( |
.formats |
(named |
.labels |
(named |
.indent_mods |
(named |
x |
( |
Value
-
compare_vars()
returns a layout object suitable for passing to further layouting functions, or tortables::build_table()
. Adding this function to anrtable
layout will add formatted rows containing the statistics froms_compare()
to the table layout.
-
s_compare()
returns output ofs_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 forrtables::analyze()
. -
s_compare()
: S3 generic function to produce a comparison summary. -
s_compare(numeric)
: Method fornumeric
class. This uses the standard t-test to calculate the p-value. -
s_compare(factor)
: Method forfactor
class. This uses the chi-squared test to calculate the p-value. -
s_compare(character)
: Method forcharacter
class. This makes an automatic conversion tofactor
(with a warning) and then forwards to the method for factors. -
s_compare(logical)
: Method forlogical
class. A chi-squared test is used. If missing values are not removed, then they are counted asFALSE
.
Note
For factor variables,
denom
for factor proportions can only ben
since the purpose is to compare proportions between columns, therefore a row-based proportion would not make sense. Proportion based onN_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
, theseNA
values are excluded by default. To includeNA
values setna.rm = FALSE
and missing values will be displayed as anNA
level. Alternatively, an explicit factor level can be defined forNA
values during pre-processing viadf_explicit_na()
- the defaultna_level
("<Missing>"
) will also be excluded whenna.rm
is set toTRUE
.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 viaref_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)