Package 'tableone'

Description

Convert a t1_summary object to a huxtable

Usage

## S3 method for class 't1_shape'
as_huxtable(
  x,
  ...,
  font_size = getOption("tableone.font_size", 8),
  font = getOption("tableone.font", "Arial"),
  footer_text = NULL,
  show_binary_value = NULL
)

Arguments

Value

a formatted table as a huxtable

Description

This is responsible for printing the significance test results and comparison

Usage

## S3 method for class 't1_signif'
as_huxtable(
  x,
  ...,
  layout = "compact",
  override_percent_dp = list(),
  override_real_dp = list(),
  p_format = names(.pvalue.defaults),
  font_size = getOption("tableone.font_size", 8),
  font = getOption("tableone.font", "Arial"),
  footer_text = NULL,
  show_binary_value = NULL
)

Arguments

Value

a formatted table as a huxtable

Examples

library(tableone)
tmp = iris %>% dplyr::group_by(Species) %>%
  as_t1_signif(tidyselect::everything()) %>%
  huxtable::as_huxtable()

Description

Convert a t1_summary object to a huxtable

Usage

## S3 method for class 't1_summary'
as_huxtable(
  x,
  ...,
  layout = "single",
  override_percent_dp = list(),
  override_real_dp = list(),
  font_size = getOption("tableone.font_size", 8),
  font = getOption("tableone.font", "Arial"),
  footer_text = NULL,
  show_binary_value = NULL
)

Arguments

Value

a formatted table as a huxtable

Description

The data set description is a simple summary of the data formats, types and missingness

Usage

as_t1_shape(df, ..., label_fn = label_extractor(df), units = extract_units(df))

Arguments

Value

a t1_shape data frame.

Examples

tmp = iris %>% as_t1_shape(
  tidyselect::everything()
)

Description

The population comparison is a summary of the co-variates in a data set with no reference to outcome, but comparing intervention groups. It will report summary statistics for continuous and counts for categorical data, for each of the intervention groups, and reports on the significance of the association in relation to the intervention groups. It gives a clear summary of whether data is correlated to intervention.

Usage

as_t1_signif(
  df,
  ...,
  label_fn = label_extractor(df),
  units = extract_units(df),
  override_type = list(),
  override_method = list()
)

Arguments

Value

a t1_signif dataframe.

Examples

tmp = iris %>% dplyr::group_by(Species) %>% as_t1_signif(tidyselect::everything())
tmp = diamonds %>% dplyr::group_by(is_colored) %>% as_t1_signif(tidyselect::everything())

Description

The population description is a simple summary of the co-variates in a data set with no reference to outcome, and not comparing intervention (although it might contain intervention rates.) It will report summary statistics for continuous and counts for categorical data,

Usage

as_t1_summary(
  df,
  ...,
  label_fn = label_extractor(df),
  units = extract_units(df),
  override_type = list()
)

Arguments

Value

a t1_summary data frame.

Examples

tmp = iris %>% as_t1_summary(
  tidyselect::everything(),
  override_type = c(Petal.Length = "mean_sd", Petal.Width = "mean_sd")
)

Description

A list of columns for a test case

Usage

bad_test_cols

Format

bad_test_cols

Test data

Description

The missing data summary is a simple summary of the missingness of co-variates in a data set with no reference to outcome, but comparing intervention groups. It reports summary counts for missingness in data and reports on the significance of that missingness in relation to the intervention groups, allowing a clear summary of whether data is missing at random compared to the intervention.

Usage

compare_missing(
  df,
  ...,
  label_fn = label_extractor(df),
  p_format = names(.pvalue.defaults),
  font_size = getOption("tableone.font_size", 8),
  font = getOption("tableone.font", "Arial"),
  significance_limit = 0.05,
  missingness_limit = 0.1,
  footer_text = NULL,
  raw_output = FALSE
)

Arguments

Value

a huxtable formatted table.

Examples

# this option lets us change the column name for p value from its default
# "P value"
old = options("tableone.pvalue_column_name"="p-value")

# missing at random
missing_diamonds %>% dplyr::group_by(is_colored) %>% compare_missing(tidyselect::everything())

# nothing missing
iris %>% dplyr::group_by(Species) %>% compare_missing(tidyselect::everything())

# MNAR: by design missingness is correlated with grouping
mnar_two_class_1000 %>% dplyr::group_by(grouping) %>% compare_missing(tidyselect::everything())

options(old)

Description

The outcome table is a simple summary of a binary or categorical outcome in a data set compared by intervention groups. The comparison is independent of any covariates, and is a preliminary output prior to more formal statistical analysis or model fitting.

Usage

compare_outcomes(
  df,
  ...,
  label_fn = label_extractor(df),
  units = extract_units(df),
  override_type = list(),
  layout = "compact",
  override_percent_dp = list(),
  override_real_dp = list(),
  p_format = names(.pvalue.defaults),
  font_size = getOption("tableone.font_size", 8),
  font = getOption("tableone.font", "Arial"),
  footer_text = NULL,
  show_binary_value = NULL,
  raw_output = FALSE
)

Arguments

Details

It reports summary counts for the outcomes and a measure of significance of the relationship between outcome and intervention. Interpretation of significance tests, should include Bonferroni adjustment.

Value

a huxtable formatted table.

Description

The population comparison is a summary of the co-variates in a data set with no reference to outcome, but comparing intervention groups. It will report summary statistics for continuous and counts for categorical data, for each of the intervention groups, and reports on the significance of the association in relation to the intervention groups. It gives a clear summary of whether data is correlated to intervention.

Usage

compare_population(
  df,
  ...,
  label_fn = label_extractor(df),
  units = extract_units(df),
  override_type = list(),
  override_method = list(),
  layout = "compact",
  override_percent_dp = list(),
  override_real_dp = list(),
  p_format = names(.pvalue.defaults),
  font_size = getOption("tableone.font_size", 8),
  font = getOption("tableone.font", "Arial"),
  footer_text = NULL,
  show_binary_value = NULL,
  raw_output = FALSE
)

Arguments

Value

a huxtable formatted table.

Examples

# the heuristics detect that Petals in the iris data set are not normally
# distributed and hence report median and IQR:
iris %>% dplyr::group_by(Species) %>% compare_population(tidyselect::everything())

# Missing data
old = options("tableone.show_pvalue_method"=FALSE)
missing_diamonds %>%
  dplyr::group_by(is_colored) %>%
  compare_population(-color, layout="relaxed")

tmp = missing_diamonds %>% explicit_na() %>% dplyr::group_by(is_colored)
tmp %>% compare_population(-color,
    footer_text = c(
      "IQR: Interquartile range; CI: Confidence interval",
      "Line two")
    )

options(old)

Description

Group data count and calculate proportions by column.

Usage

count_table(
  df,
  rowGroupVars,
  colGroupVars,
  numExpr = dplyr::n(),
  denomExpr = dplyr::n(),
  totalExpr = dplyr::n(),
  subgroupLevel = length(rowGroupVars),
  glue = list(`Count [%] (N={sprintf("%d",N)})` =
    "{sprintf(\"%d/%d [%1.1f%%]\", x, n, mean*100)}"),
  label_fn = label_extractor(df),
  font_size = getOption("tableone.font_size", 8),
  font = getOption("tableone.font", "Arial")
)

Arguments

Value

a huxtable with the count and proportions of the rows groups

Examples

diamonds %>% count_table(dplyr::vars(cut,clarity), dplyr::vars(color), subgroupLevel = 1)

Description

Deals with some annoying issues classifying integer data sets, such as ages, into groups. where you want to specify just the change over points as integers and clearly label the resulting ordered factor.

Usage

cut_integer(
  x,
  cut_points,
  glue = "{label}",
  lower_limit = -Inf,
  upper_limit = Inf,
  ...
)

Arguments

Value

an ordered factor of the integer

Examples

cut_integer(stats::rbinom(20,20,0.5), c(5,10,15))
cut_integer(floor(stats::runif(100,-10,10)), cut_points = c(2,3,4,6), lower_limit=0, upper_limit=10)
cut_integer(1:10, cut_points = c(1,3,9))

Description

Customisation of output can use one of these entries as a starting point. A custom layout should look like one of the entries in level 2 of this nested list, containing 4 named entries, one for each type of table summary.

Usage

default.format

Format

default.format

A names list of lists:

level one

The name of the table layout

level two

The name of the summary type required. one of subtype_count, median_iqr,mean_sd,skipped

level three

a named list of column=⁠glue specification⁠ pairs. The column (itself a glue spec) might reference N_total, N_present or .unit but typically will be a fixed string- it defines the name of the table column to generate. The ⁠glue specification⁠ defines the layout of that column, and can use summary statistics as below

subtype_count

can use level, prob.0.5, prob.0.025, prob.0.975, unit, n, N. n is subgroup count, N is data count.

median_iqr

can use q.0.5, q.0.25, ..., unit, n, N - n excludes missing, N does not.

mean_sd

can use mean, sd, unit, n, N - n excludes missing, N does not.

skipped

can use n, N - n excludes missing, N does not.

Description

The population description is a simple summary of the co-variates in a data set with no reference to outcome, and not comparing intervention (although it might contain intervention rates.) It will report summary statistics for continuous and counts for categorical data,

Usage

describe_data(
  df,
  ...,
  label_fn = label_extractor(df),
  units = extract_units(df),
  layout = "single",
  font_size = getOption("tableone.font_size", 8),
  font = getOption("tableone.font", "Arial"),
  footer_text = NULL,
  raw_output = FALSE
)

Arguments

Value

a huxtable formatted table.

Examples

# Overriding the heuristics is possible:
iris %>% describe_data(tidyselect::everything())

diamonds %>% dplyr::group_by(is_colored) %>% describe_data(tidyselect::everything())

Description

The population description is a simple summary of the co-variates in a data set with no reference to outcome, and not comparing intervention (although it might contain intervention rates.) It will report summary statistics for continuous and counts for categorical data,

Usage

describe_population(
  df,
  ...,
  label_fn = label_extractor(df),
  units = extract_units(df),
  override_type = list(),
  layout = "single",
  override_percent_dp = list(),
  override_real_dp = list(),
  font_size = getOption("tableone.font_size", 8),
  font = getOption("tableone.font", "Arial"),
  footer_text = NULL,
  show_binary_value = NULL,
  raw_output = FALSE
)

Arguments

Value

a huxtable formatted table.

Examples

# the heuristics detect that Petals in the iris data set are not normally
# distributed and hence report median and IQR:
iris %>% describe_population(tidyselect::everything())

# Overriding the heuristics is possible:
iris %>% describe_population(
  tidyselect::everything(),
  override_type = c(Petal.Length = "mean_sd", Petal.Width = "mean_sd")
)

# The counts sometimes seem redundant if there is no missing information:
diamonds %>% describe_population(tidyselect::everything())

# however in a data set with missing values the denominators are important:
missing_diamonds %>% describe_population(tidyselect::everything())

# for factor levels we can make the missing values more explicit
missing_diamonds %>% explicit_na() %>%
  describe_population(tidyselect::everything())

# in the output above the price variable is not # presented the way we would
# like so here we override the number of decimal places shown for the price
# variable while we are at it we will use a mid point for the decimal point,
# and make the variable labels sentence case.

old = options("tableone.dp"="\u00B7")
missing_diamonds %>%
  explicit_na() %>%
  describe_population(
    tidyselect::everything(),
    label_fn=stringr::str_to_sentence,
    override_real_dp=list(price=6)
  )
options(old)

Description

with a binary class is_coloured based on the color column

Usage

diamonds

Format

diamonds

Test data

Description

Converts NA values in any factors in the dataframe into a new level - This is a thin wrapper for forcats::fct_explicit_na() but with missing value level added regardless of whether any values missing. This forces an empty row in count tables.

Usage

explicit_na(df, na_level = "<missing>", hide_if_empty = FALSE)

Arguments

Value

the dataframe with all factor columns containing explicit na values

Examples

# before
missing_diamonds %>% dplyr::group_by(cut) %>% dplyr::count()
# after
missing_diamonds %>% explicit_na() %>% dplyr::group_by(cut) %>% dplyr::count()

Description

Get summary comparisons and statistics between variables as raw data.

Usage

extract_comparison(
  df,
  ...,
  label_fn = label_extractor(df),
  override_type = list(),
  p_format = names(.pvalue.defaults),
  override_method = list(),
  power_analysis = FALSE,
  override_power = list(),
  raw_output = FALSE
)

Arguments

Value

a list of accessor functions for the summary data allowing granular access to the results of the analysis:

• comparison$compare(.variable, .characteristic = NULL) - prints a comparison between the different intervention groups for the specified variable (and optionally the given characteristic if it is a categorical variable).

• comparison$filter(.variable, .intervention = NULL, .characteristic = NULL) extracts a given variable (e.g. gender), optionally for a given level of intervention (e.g. control) and if categorical a given characteristic (e.g. male). This will output a dataframe with all the calculated summary variables, for all qualifying intervention, variable and characteristic combinations, significance tests (and power analyses) for the qualifying variable (comparing intervention groups).

• comparison$signif_tests(.variable) - extracts for a given variable (e.g. gender) the significance tests (and optionally power analyses) of the univariate comparison between different interventions and the variable.

• comparison$summary_stats(.variable, .intervention = NULL, .characteristic = NULL) extracts a given variable (e.g. gender), optionally for a given level of intervention (e.g. control) and if categorical a given characteristic (e.g. male). This returns only the summary stats for all qualifying intervention, variable and characteristic combinations.

Description

Extracts units set as dataframe column attributes

Usage

extract_units(df)

Arguments

Value

a named list of column / unit pairs.

Examples

iris = iris %>% set_units(-Species, units="mm")
iris %>% extract_units()

Description

Uses the default formatter set globally in options("tableone.pvalue_formatter") in preference the one defined by p_format which is only used if no default is set.

Usage

format_pvalue(p.value, p_format = names(.pvalue.defaults))

Arguments

Value

a formatted P-value

Description

The functions in tableone will record the methods used for reporting in a scientific paper. This is both for normality assumption tests and for significance tests.

Usage

get_footer_text(df_output)

Arguments

Value

the footnotes if they exist as a list (NULL otherwise)

Examples

iris %>% describe_population(tidyselect::everything()) %>% get_footer_text()
iris %>% dplyr::group_by(Species) %>%
  compare_population(tidyselect::everything()) %>% get_footer_text()

Description

At some point we need to take information from the tables produced by tableone and place it into the main text of the document. It is annoying if this cannot be done automatically. the group_comparison() function enables extraction of one or more head to head comparisons and provides a fairly flexible mechanism for building the precise format desired.

Usage

group_comparison(
  t1_signif,
  variable = NULL,
  subgroup = NULL,
  intervention = NULL,
  percent_fmt = "%1.1f%%",
  p_format = names(.pvalue.defaults),
  no_summary = FALSE,
  summary_glue = NULL,
  summary_arrange = NULL,
  summary_sep = ", ",
  summary_last = " versus ",
  no_signif = FALSE,
  signif_glue = NULL,
  signif_sep = NULL,
  signif_last = NULL
)

Arguments

Value

ideally a single string but various things will be returned depending on hos much input is constrained, and sometimes will provide guidance about what next to do. The intention is the function to be used interactively until a satisfactory result is obtained.

Examples

tmp = diamonds %>%
  dplyr::group_by(is_colored) %>%
  set_units(price,units="£") %>%
  compare_population(-color, raw_output=TRUE)

# The tabular output is retrieved by converting to a huxtable
# as_huxtable(tmp, layout="simple")

# An unqualified group_comparison call gives informative messages
# about what can be compared:
tmp %>% group_comparison()

# filtering down the data gets us to a specific comparison:
tmp %>% group_comparison(variable = "cut", subgroup="Fair") %>% dplyr::glimpse()

# With further interactive exploration the
# data available for that comparison can be made into a glue string
tmp %>% group_comparison(variable = "cut", subgroup="Fair", intervention = "clear",
  summary_glue = "{is_colored}: {x}/{n} ({prob.0.5}%)",
  signif_glue = "{variable}={subgroup}; {text}; Overall p-value for '{variable}': {p.value}.")

# group comparisons above using many individual subgroups are a bit confusing because
# the p-value is at the variable level. This is less of an issue for continuous
# or binary values.
tmp %>% group_comparison(
  variable = "price",
  summary_glue = "{is_colored}: {unit}{q.0.5}; IQR: {q.0.25} \u2014 {q.0.75} (n={n})",
  signif_glue = "{variable}: {text}; P-value {p.value}.")

# Sometimes we only want to extract a p-value:
tmp %>%
  group_comparison(variable = "cut", subgroup="Fair", no_summary=TRUE) %>%
  dplyr::glimpse()

Description

Retrieve column labels are embedded as an attribute of each column.

Usage

label_extractor(df, ..., attribute = "label")

Arguments

Value

a labelling function. This is specific to the dataframe provided in df

Examples

iris = set_labels(iris, c(
    "Sepal Length", "Sepal Width",
    "Petal Length", "Petal Width",  "Species"
 ))
fn = label_extractor(iris,tolower)
fn(colnames(iris))

Description

It is simpler for presentation and sometimes more correct for discrete valued data to be represented as factors. Such discrete valued data might be logical values, character values, or numeric values with a limited number of levels (e.g. scores). this function lets you convert (a subset of) data frame columns into factors using

Usage

make_factors(
  df,
  ...,
  .logical = c("yes", "no"),
  .numeric = "{name}={value}",
  .character = NULL
)

Arguments

Value

a dataframe with the columns converted to factors

Examples

iris %>%
  make_factors(tidyselect::ends_with("Length"), .numeric = "{name}={round(value)}") %>%
  dplyr::glimpse()

# Convert everything in diamonds to be a factor, rounding all
# the numeric values and converting all the names to upper case
tmp = diamonds %>%
  dplyr::mutate(is_colored = color > "F") %>%
  make_factors(tidyselect::everything(), .numeric="{toupper(name)}={round(value)}")

# as we included `price` which has very many levels one factor is unuseable with 11602 levels:
length(levels(tmp$price))

# we could explicitly exclude it from the `tidyselect` syntax `...` parameter:
diamonds %>% dplyr::mutate(is_colored = color > "F") %>%
  make_factors(-price, .numeric="{toupper(name)}={round(value)}") %>%
  dplyr::glimpse()

# or alternatively we set a limit on the maximum number of factors, which
# in this example picks up the `depth` and `table` columns as exceeding this
# new limit:

old = options("tableone.max_discrete_levels"=16)
diamonds %>% dplyr::mutate(is_colored = color > "F") %>%
  make_factors(tidyselect::everything(), .numeric="{toupper(name)}={round(value)}") %>%
  dplyr::glimpse()

options(old)

# converting a character vector. Here we specify `.character` as a list giving the
# possible levels of `alpha2`. Values outside of this list are converted to `NA`

set.seed(100)
eg_character = tibble::tibble(
  alpha1 =  sample(letters,50,replace=TRUE),
  alpha2 = sample(LETTERS,50,replace=TRUE)
)

eg_character %>%
  make_factors(tidyselect::everything(), .character = list(alpha2 = LETTERS[3:20]))

Description

with 10% of entries replaced by NA and a binary class is_coloured based on the color column

Usage

missing_diamonds

Format

missing_diamonds

Test data

Description

A random data test dataset with 2 classes (groupings column) one of which has 10% missing data and the other has 20%

Usage

mnar_two_class_1000

Format

mnar_two_class_1000

Test data

Description

A multi-class dataset with equal random samples in each class

Usage

multi_class_negative

Format

multi_class_negative

Test data

Description

columns contain a set of random data of different types e.g. uniform continuous, normal, binomial, multinomial.

Usage

one_class_test_100

Format

one_class_test_100

Test data

Description

columns contain a set of random data of different types e.g. uniform continuous, normal, binomial, multinomial.

Usage

one_class_test_1000

Format

one_class_test_1000

Test data

Description

Comparing missingness by looking at a table is good but we also want to update models to exclude missing data from the predictors.

Usage

remove_missing(
  df,
  ...,
  label_fn = label_extractor(df),
  significance_limit = 0.05,
  missingness_limit = 0.1
)

Arguments

Value

a list of formulae with missing parameters removed

Examples

df = iris %>%
  dplyr::mutate(Petal.Width = ifelse(
    stats::runif(dplyr::n()) < dplyr::case_when(
      Species == "setosa" ~ 0.2,
      Species == "virginica" ~ 0.1,
      TRUE~0
    ),
    NA,
    Petal.Width
  ))
remove_missing(df, ~ Species + Petal.Width + Sepal.Width, ~ Species + Petal.Length + Sepal.Length)

Description

Set a label attribute

Usage

set_labels(df, labels, attribute = "label")

Arguments

Value

the same dataframe with each column labelled

Examples

iris = set_labels(iris,
  c("Sepal Length", "Sepal Width",
    "Petal Length", "Petal Width",  "Species"
   ))
fn = label_extractor(iris,tolower)
fn(colnames(iris))

Description

Title

Usage

set_units(df, ..., units)

Arguments

Value

the dataframe with the unit attribute updated

Examples

iris = iris %>% set_units(-Species, units="mm")
iris %>% extract_units()

Description

A list of columns for a test case

Usage

test_cols

Format

test_cols

Test data

Description

columns contain a set of random data of different types e.g. uniform continuous, normal, binomial, multinomial. in grouping 1 there is 100 items in grouping 2 there are 1000 items

Usage

two_class_test

Format

one_class_test_100

Test data