atable (version 0.1.0)

atable: Create Tables for Reporting of Clinical Trials

Description

Applies descriptive statistics and hypothesis tests to data, and arranges the results for printing.

Usage

atable(x, ...)
# S3 method for data.frame
atable(x, target_cols, group_col = NULL,
  split_cols = NULL, format_to = atable_options("format_to"),
  drop_levels = TRUE, add_levels_for_NA = FALSE, ...)
# S3 method for formula
atable(formula, data, ...)

Arguments

x

An object. If x is a data.frame, it must have unique and syntactically valid colnames, see is_syntactically_valid_name.

...

Passed from and to other methods.

target_cols

A character vector containing some column names of x.

Descriptive statistics and hypothesis test are applied to these columns depending on their class. The descriptive statistics are defined by statistics; their representation and format by format_statistics.

Hypothesis test are defined by two_sample_htest or multi_sample_htest (depending on the number of levels of group_col); their representation and format by format_tests. Note that atable always adds one name to target_cols to count the number of obsservations. This name is stored in atable_options('colname_for_observations').

group_col

A character of length 1 containing a column of x or NULL. This column defines the groups that are compared by the hypothesis tests. as.factor is applied to this column before further processing. Default is NULL, meaning that no hypothesis tests are applied.

split_cols

A character vector containing some of colnames(x) or NULL. x is splitted by these columns before descriptive statistics and hypothesis test are applied. as.factor is applied to this column before further processing. Default is NULL, meaning that no splitting is done.

format_to

A character vector of length 1. Specifies the format of the output of atable. Possible values are 'Latex', 'Word', 'Raw', 'HTML'. Default is defined atable_options.

drop_levels

A logical. If TRUE then droplevels is called on group_col and split_cols beforefurther processsing. Default is TRUE.

add_levels_for_NA

If TRUE then addNA is called on group_col and split_cols before further processsing. Default is FALSE.

formula

A formula of the form target_cols ~ group_col | split_cols. The | separates the group_col from the split_cols. Read the | as 'given' as in a conditional probability P(target_cols | split_cols). target_cols and split_cols may contain multiple names separated by +. group_col must be a single name if given. group_col and split_cols may be omitted and can be replaced by 1 in this case. The | may also be omitted if no split_cols are given.

data

Passed to atable(x = data, ...).

Value

Results depend on format_to:

• 'Raw': A list with two elemtents called 'statistics_result' and 'tests_result', that contain all results of the descriptve statistics and the hypothesis tests. This format useful, when extracting a specific result unformated (when format_to is not 'Raw' all numbers are also returned, but as rounded characters for pretty printing and squeezed into a data.frame).

  • 'statistics_result': contains a data.frame with colnames c(split_cols, group_col, target_cols. split_cols and group_col retain their original values (now as factor). target_cols contain lists with the results of function statistics. As the result of function statistics is also a list, target_cols contain lists of lists.

  • 'tests_result': has the same structure as 'statistics_result', but contains the results of two_sample_htest and multi_sample_htest. Note that tests_result only exists if split_cols is not NULL.

• 'Word': A data.frame. Column atable_options('colname_for_group') contains all combinations of the levels of split_cols and the names of the results of function format_statistics.

  Further columns are the levels of group_col the names of the results of format_tests.

  The levels of split_cols and the statistics are arranged vertically. The hypothesis test are arranged horizontally.

• 'HTML': Same as for format_to = 'Word' but a different character indents the first column.

• 'Latex': Same as for format_to = 'Word' but a different character indents the first column and with translate_to_LaTeX applied afterwards.

Methods (by class)

• data.frame: applies descriptive statistics and hypothesis tests, arranges the results for printing.

• formula: parses the formula and passes its parts to atable.

Examples

# NOT RUN {
# See vignette for more examples:
# utils::vignette("atable_usage", package = "atable")

# Analyse datasets::ToothGrowth:
# Length of tooth for each dose level and delivery method:
atable::atable(datasets::ToothGrowth,
  target_cols = 'len',
  group_col = 'supp',
  split_cols = 'dose',
  format_to = 'Word')
# Print in .docx with e.g. flextable::regulartable and officer::body_add_table

# Analyse datasets::ChickWeight:
# Weight of chickens for each time point and diet:
atable(weight ~ Diet | Time, datasets::ChickWeight, format_to = 'Latex')
# Print as .pdf with e.g. Hmisc::latex

# Analyse atable::test_data:
atable(Numeric + Logical + Factor + Ordered ~ Group | Split1 + Split2,
  atable::test_data, format_to = 'HTML')
# Print as .html with e.g. knitr::kable and options(knitr.kable.NA = '')

# For print on Console use format_to = 'Word'.
# }