tern (version 0.9.8)

default_stats_formats_labels: 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)

Value

• get_stats() returns a character vector of statistical methods.

• get_stat_names() returns a named list of character vectors, indicating the names of statistical outputs.

• get_formats_from_stats() returns a named list of formats as strings or functions.

• get_labels_from_stats() returns a named list of labels as strings.

• get_indents_from_stats() returns a named list of indentation modifiers as integers.

• summary_formats() returns a named vector of default statistic formats for the given data type.

• summary_labels returns a named vector of default statistic labels for the given data type.

Format

• tern_default_stats is a named list of available statistics, with each element named for their corresponding statistical method group.

• tern_default_formats is a named vector of available default formats, with each element named for their corresponding statistic.

• tern_default_labels is a named character vector of available default labels, with each element named for their corresponding statistic.

Arguments

method_groups

(character)
indicates the statistical method group (tern analyze function) to retrieve default statistics for. A character vector can be used to specify more than one statistical method group.

stats_in

(character)
statistics to retrieve for the selected method group. If custom statistical functions are used, stats_in needs to have them in too.

custom_stats_in

(character)
custom statistics to add to the default statistics.

add_pval

(flag)
should "pval" (or "pval_counts" if method_groups contains "analyze_vars_counts") be added to the statistical methods?

stat_results

(list)
list of statistical results. It should be used close to the end of a statistical function. See examples for a structure with two statistical results and two groups.

stat_names_in

(character)
custom modification of statistical values.

stats

(character)
statistical methods to return defaults for.

formats_in

(named vector)
custom formats to use instead of defaults. Can be a character vector with values from formatters::list_valid_format_labels() or custom format functions. Defaults to NULL for any rows with no value is provided.

levels_per_stats

(named list of character or NULL)
named list where the name of each element is a statistic from stats and each element is the levels of a factor or character variable (or variable name), each corresponding to a single row, for which the named statistic should be calculated for. If a statistic is only calculated once (one row), the element can be either NULL or the name of the statistic. Each list element will be flattened such that the names of the list elements returned by the function have the format statistic.level (or just statistic for statistics calculated for a single row). Defaults to NULL.

tern_defaults

(list or vector)
defaults to use to fill in missing values if no user input is given. Must be of the same type as the values that are being filled in (e.g. indentation must be integers).

labels_in

(named character)
custom labels to use instead of defaults. If no value is provided, the variable level (if rows correspond to levels of a variable) or statistic name will be used as label.

label_attr_from_stats

(named list)
if labels_in = NULL, then this will be used instead. It is a list of values defined in statistical functions as default labels. Values are ignored if labels_in is provided or "" values are provided.

indents_in

(named integer)
custom row indent modifiers to use instead of defaults. Defaults to 0L for all values.

row_nms

Deprecation cycle started. See the levels_per_stats parameter for details.

type

(string)
"numeric" or "counts".

include_pval

(flag)
same as the add_pval argument in get_stats().

Functions

• get_stats(): Get statistics available for a given method group (analyze function). To check available defaults see tern::tern_default_stats list.

• get_stat_names(): Get statistical names available for a given method group (analyze function). Please use the s_* functions to get the statistical names.

• get_formats_from_stats(): Get formats corresponding to a list of statistics. To check available defaults see list tern::tern_default_formats.

• get_labels_from_stats(): Get labels corresponding to a list of statistics. To check for available defaults see list tern::tern_default_labels.

• get_indents_from_stats(): Get row indent modifiers corresponding to a list of statistics/rows.

• tern_default_stats: Named list of available statistics by method group for tern.

• tern_default_formats: Named vector of default formats for tern.

• tern_default_labels: Named character vector of default labels for tern.

• summary_formats(): Quick function to retrieve default formats for summary statistics: analyze_vars() and analyze_vars_in_cols() principally.

• summary_labels(): Quick function to retrieve default labels for summary statistics. Returns labels of descriptive statistics which are understood by rtables. Similar to summary_formats.

Details

Current choices for type are counts and numeric for analyze_vars() and affect get_stats().

summary_* quick get functions for labels or formats uses get_stats and get_labels_from_stats or get_formats_from_stats respectively to retrieve relevant information.

See Also

formatting_functions

Examples

# analyze_vars is numeric
num_stats <- get_stats("analyze_vars_numeric") # also the default

# Other type
cnt_stats <- get_stats("analyze_vars_counts")

# Weirdly taking the pval from count_occurrences
only_pval <- get_stats("count_occurrences", add_pval = TRUE, stats_in = "pval")

# All count_occurrences
all_cnt_occ <- get_stats("count_occurrences")

# Multiple
get_stats(c("count_occurrences", "analyze_vars_counts"))

stat_results <- list(
  "n" = list("M" = 1, "F" = 2),
  "count_fraction" = list("M" = c(1, 0.2), "F" = c(2, 0.1))
)
get_stat_names(stat_results)
get_stat_names(stat_results, list("n" = "argh"))

# Defaults formats
get_formats_from_stats(num_stats)
get_formats_from_stats(cnt_stats)
get_formats_from_stats(only_pval)
get_formats_from_stats(all_cnt_occ)

# Addition of customs
get_formats_from_stats(all_cnt_occ, formats_in = c("fraction" = c("xx")))
get_formats_from_stats(all_cnt_occ, formats_in = list("fraction" = c("xx.xx", "xx")))

# Defaults labels
get_labels_from_stats(num_stats)
get_labels_from_stats(cnt_stats)
get_labels_from_stats(only_pval)
get_labels_from_stats(all_cnt_occ)

# Addition of customs
get_labels_from_stats(all_cnt_occ, labels_in = c("fraction" = "Fraction"))
get_labels_from_stats(all_cnt_occ, labels_in = list("fraction" = c("Some more fractions")))

get_indents_from_stats(all_cnt_occ, indents_in = 3L)
get_indents_from_stats(all_cnt_occ, indents_in = list(count = 2L, count_fraction = 5L))
get_indents_from_stats(
  all_cnt_occ,
  indents_in = list(a = 2L, count.a = 1L, count.b = 5L)
)

summary_formats()
summary_formats(type = "counts", include_pval = TRUE)

summary_labels()
summary_labels(type = "counts", include_pval = TRUE)