Getting started with tibbleOne

Why use tibbleOne?

The goal of tibbleOne is to make it easy for analysts to include a Table 1 object in html, LaTeX, and word documents. Notably, this package has far fewer features than the outstanding TableOne package and many similar types of R packages for this task, but tibbleOne is handy for getting a readable Table 1 into a markdown document with minimal effort.

Example

The primary function in tibbleOne is tibble_one(). It is a formula-based function with some flexibility. In the code block below, I’ll use tibble_one() to tabulate participant characteristics in the primary biliary cirrhosis dataset (adapted from the pbc data in the survival package).

First, I make a meta dataset that contains data about our data. Initially, I will indicate the labels and groups for variables. In addition to setting groups and labels for variables, I may also want to write some key details about a variable or two, and pass that information into my tables as a footnote. Last, some variable labels have abbreviations in them, and those need to be expanded on in the footnotes of the table.


library(tibbleOne)
library(kableExtra)
library(tidyverse)
library(survival)

data("pbc_tbl1")

# set attributes and then build a meta data set

meta <- pbc_tbl1 %>%
  # labels are used to represent column names in table 1
  set_variable_labels(
    status = "Status ALC",
    trt = "Treatment group",
    age = 'Age',
    sex = 'Sex at birth',
    ascites = 'Ascites',
    bili = 'Bili levels',
    edema = 'Edema',
    albumin = 'Serum Alb'
  ) %>%
  # units must be attached to continuous variables
  set_variable_units(
    age = 'years',
    bili = 'mg/dl',
    albumin = 'g/dl'
  ) %>% 
  # variables in the same group are clustered together table 1
  set_variable_groups(
    Outcomes = c('status'),
    Exposures = c('ascites','bili','albumin','edema','stage')
  ) %>% 
  set_variable_notes(
    age = "important note about age"
  ) %>% 
  set_variable_abbrs(
    status = c(ALC = "at last contact"),
    bili = c(Bili = "bilirubin"),
    albumin = c(Alb = 'albumin')
  ) %>% 
  build_meta()

meta
#> $data
#> # A tibble: 9 x 8
#>   variable label          type    unit  group    abbr     note     labels  
#>   <chr>    <chr>          <chr>   <chr> <chr>    <list>   <list>   <list>  
#> 1 age      Age            numeric years None     <chr [1~ <chr [1~ <chr [1~
#> 2 sex      Sex at birth   factor  %     None     <chr [1~ <chr [1~ <chr [1~
#> 3 status   Status ALC     factor  %     Outcomes <chr [1~ <chr [1~ <chr [4~
#> 4 trt      Treatment gro~ factor  %     None     <chr [1~ <chr [1~ <chr [1~
#> 5 stage    Stage          factor  %     Exposur~ <chr [1~ <chr [1~ <chr [5~
#> 6 ascites  Ascites        factor  %     Exposur~ <chr [1~ <chr [1~ <chr [1~
#> 7 bili     Bili levels    numeric mg/dl Exposur~ <chr [1~ <chr [1~ <chr [1~
#> 8 edema    Edema          factor  %     Exposur~ <chr [1~ <chr [1~ <chr [4~
#> 9 albumin  Serum Alb      numeric g/dl  Exposur~ <chr [1~ <chr [1~ <chr [1~
#> 
#> $group_levels
#> [1] "None"      "Outcomes"  "Exposures"
#> 
#> $var_levels
#> [1] "status"  "ascites" "bili"    "albumin" "edema"   "stage"  
#> 
#> $add_perc_to_cats
#> [1] TRUE
#> 
#> attr(,"class")
#> [1] "meta"

meta data

meta data allows tibbleOne objects to carry along information that pertains to variable labels, abbreviations, units, and footnotes. Initially, this type of information was stored as an attribute on a tibble, but attributes of tibble objects can be wiped away by some operations, so it seemed much safer to store the information remotely in a meta data object.

kable output

The kable() function from the knitr package and the host of extra functions from the kableExtra package are meant to be combined with tibbleOne objects to create publishable tables. A user may pass their tibble_one() output into the convenience function, to_kable(), to produce a table such as the one below.

Treatment group
Overall
(N = 418)
D-penicillmain
(N = 158)
Placebo
(N = 154)
Age, years 50.7 (10.4) 51.4 (11.0) 48.6 (9.96)
Female, % 89.5 86.7 90.3
Outcomes
Status ALC, %
Censored 55.5 52.5 55.2
Transplant 5.98 6.33 5.84
Dead 38.5 41.1 39.0
Exposures
Ascites, % 7.69 8.86 6.49
Bili levels, mg/dl 1.40 [0.80-3.40] 1.40 [0.80-3.20] 1.30 [0.72-3.60]
Serum Alb, g/dl 3.53 [3.24-3.77] 3.56 [3.21-3.83] 3.54 [3.34-3.78]
Edema, %
None 84.7 83.5 85.1
Untreated or successfully treated 10.5 10.1 8.44
Treatment resistant 4.78 6.33 6.49
Stage, %
One 5.10 7.59 2.60
Two 22.3 22.2 20.8
Three 37.6 35.4 41.6
Four 35.0 34.8 35.1
ALC = at last contact, Alb = albumin, Bili = bilirubin
* Table values for continuous variables are mean (standard deviation) or median [interquartile range]. Table values for categorical variables are percent.
important note about age

kable also provides LaTex tables when the markdown output is set as a pdf.

flextable output

The flextable() package comprises functions that help construct tables in Microsoft word. tibbleOne provides a function to help users send their tibble_out() output into the framework of flextable package. The function is called to_word()

Treatment group

Characteristic*

Overall
(N = 418)

D-penicillmain
(N = 158)

Placebo
(N = 154)

Age, years

50.7 (10.4)

51.4 (11.0)

48.6 (9.96)

Female, %

89.5

86.7

90.3

Outcomes

Status ALC, %

Censored

55.5

52.5

55.2

Transplant

5.98

6.33

5.84

Dead

38.5

41.1

39.0

Exposures

Ascites, %

7.69

8.86

6.49

Bili levels, mg/dl

1.40 [0.80-3.40]

1.40 [0.80-3.20]

1.30 [0.72-3.60]

Serum Alb, g/dl

3.53 [3.24-3.77]

3.56 [3.21-3.83]

3.54 [3.34-3.78]

Edema, %

None

84.7

83.5

85.1

Untreated or successfully treated

10.5

10.1

8.44

Treatment resistant

4.78

6.33

6.49

Stage, %

One

5.10

7.59

2.60

Two

22.3

22.2

20.8

Three

37.6

35.4

41.6

Four

35.0

34.8

35.1

*Table values for continuous variables are mean (standard deviation) or median [interquartile range]. Table values for categorical variables are percent.

important note about age

ALC = at last contact, Alb = albumin, Bili = bilirubin

Summary

The example above shows how tibbleOne can be used to direct your R output into any of three formats for writing articles (Word, html, and Tex). The code used to create tibbleOne tables