Loading supplementary packages

suppressPackageStartupMessages(require(tangram.pipe))
suppressPackageStartupMessages(require(knitr))
suppressPackageStartupMessages(require(kableExtra))

Numeric Rows

To start off, we will first add a numeric row to the table. The function num_row reads in data that is numeric in form, and by default calculates the five-number summary statistics (minimum, first quartile, median, third quartile, maximum), as well as the mean and standard deviation for the numeric variable within each column. Since we specified overall=TRUE in the initialization step, an overall summary row will be included as well. The default summary function is num_default, but the user may write their own function to calculate different summary statistics from what is shown here.

Currently, there are five summary functions available for use within num_row. The default summary to use for each row can be specified in tbl_start, or determined using the summary argument of each row

num_default : Calculates the five-number summary, mean, and standard deviation

num_minmax : Calculates the minimum and maximum values

num_medianiqr : Calculates the median and interquartile range

num_mean_sd : Calculates the mean and standard deviation

num_date : Calculates the five-number summary for a date object

More information on writing your own summary functions can be found in the accompanying package vignette “Writing User-Defined Summary Functions”

Let’s start by calculating summary statistics for the Sepal Length in the iris dataset. Since it makes more sense to display the variable name as “Sepal Length” rather than the R-generated “Sepal.Length”, we will use the rowlabel argument to make this change for the table. Note that if you have a dataframe with labelled variables as columns, leaving rowlabel blank will automatically input the variable’s label as the rowlabel. To output the final object, we use the function tbl_out to display the table.

tbl1 <- tbl_start(data=iris, col_var="Species", missing=FALSE, overall=TRUE, comparison=FALSE) %>% 
  num_row(row_var="Sepal.Length", rowlabel="Sepal Length") %>%
  tbl_out()
tbl1 %>% 
  tangram_styling() %>% 
  kable(escape=F, align="l") %>% 
  trimws %>% 
  kable_styling(c("striped","bordered"))

By default, each row function will use two decimal places in reported statistics. We can use the digits argument to specify more or fewer significant digits in the reported table.

tbl1 <- tbl_start(data=iris, col_var="Species", missing=FALSE, overall=TRUE, comparison=FALSE) %>% 
  num_row(row_var="Sepal.Length", rowlabel="Sepal Length", digits=4) %>%
  tbl_out()
tbl1 %>% 
  tangram_styling() %>% 
  kable(escape=F, align="l") %>% 
  trimws %>% 
  kable_styling(c("striped","bordered"))

There is a small amount of missing data within the iris dataset. Currently, num_row filters out the missing data and only considers data with complete cases of the row and column variables. To see how much missing data there is in the sepal length, we specify missing=TRUE.

tbl1 <- tbl_start(data=iris, col_var="Species", missing=FALSE, overall=TRUE, comparison=FALSE) %>% 
  num_row(row_var="Sepal.Length", rowlabel="Sepal Length", missing=TRUE) %>%
  tbl_out()
tbl1 %>% 
  tangram_styling() %>% 
  kable(escape=F, align="l") %>% 
  trimws %>% 
  kable_styling(c("striped","bordered"))

The function above tells us that the dataset is missing a sepal length measurement for one of the virginica flowers. Note that the function cannot locate instances of missingness in the column variable.

Finally, suppose we want to look at the differences in means across all species. The function num_diff for the comparison argument will calculated the mean difference in sepal length for each row compared to a reference category, which is coded as the first column variable in the table. Here, versicolor and virginica will be compared to setosa. The function also provides a 95% Confidence interval to accompany the mean difference. Currently, num_diff is the only built-in comparison function for num_row.

tbl1 <- tbl_start(data=iris, col_var="Species", missing=FALSE, overall=TRUE, comparison=FALSE) %>% 
  num_row(row_var="Sepal.Length", rowlabel="Sepal Length", comparison=num_diff) %>%
  tbl_out()
tbl1 %>% 
  tangram_styling() %>% 
  kable(escape=F, align="l") %>% 
  trimws %>% 
  kable_styling(c("striped","bordered"))

Categorical Rows

Now, we will look at adding categorical variables. The function cat_row reads in data that is categorical in form, and by default calculates the number of instances for each row category within each column category, as well as the column-wise proportions. The default summary function is cat_default, but the user may write their own function to calculate different summary statistics from what is shown here.

Currently, there are four summary functions available for use within cat_row. The default summary to use for each row can be specified in tbl_start, or determined using the summary argument of each row.

cat_default : Calculates the cell counts and column-wise proportions

cat_pct : Calculates the cell counts and column-wise percentages

cat_count : Calculates the cell counts

cat_jama : Calculates the column-wise percentages and cell counts divided by column totals. This is the style used by the Journal of the American Medical Association.

We will demonstrate this function by looking at Stem.Size in the iris dataset. Note that cat_row and num_row have nearly identical arguments, but cat_row allows you to choose the number of spaces to indent category names using the indent argument. The default setting is 5 spaces.

tbl1 <- tbl_start(data=iris, col_var="Species", missing=FALSE, overall=TRUE, comparison=FALSE) %>% 
  cat_row("Stem.Size", rowlabel="Stem Size") %>%
  tbl_out()
tbl1 %>% 
  tangram_styling() %>% 
  kable(escape=F, align="l") %>% 
  trimws %>% 
  kable_styling(c("striped","bordered"))

Setting missing=TRUE will reveal the proportion of each species that does not have a corresponding entry for stem size. When missing data is accounted for, the missingness will be recorded as the percentage of each column that is designated as missing data.

tbl1 <- tbl_start(data=iris, col_var="Species", missing=FALSE, overall=TRUE, comparison=FALSE) %>% 
  cat_row("Stem.Size", rowlabel="Stem Size", missing=TRUE) %>%
  tbl_out()
tbl1 %>% 
  tangram_styling() %>% 
  kable(escape=F, align="l") %>% 
  trimws %>% 
  kable_styling(c("striped","bordered"))

We can also sort a categorical row in ascending or descending order by category counts for a specified column. The ordering argument will sort the row variable, and sortcol specifies which column we could like to sort our row by. Permissible arguments for ordering are c("ascending", "descending"); by default, the row function will sort by the overall cell counts unless a valid column category name is inputted into sortcol. If an invalid category name is used, the row function will sort by the overall cell counts instead.

tbl1 <- tbl_start(data=iris, col_var="Species", missing=FALSE, overall=TRUE, comparison=FALSE) %>% 
  cat_row("Stem.Size", rowlabel="Stem Size (Ascending by versicolor)", missing=TRUE, 
          ordering = "ascending", sortcol = "versicolor") %>%
  cat_row("Stem.Size", rowlabel="Stem Size (Descending by overall count)", missing=TRUE, 
          ordering = "descending") %>%
  tbl_out()
tbl1 %>% 
  tangram_styling() %>% 
  kable(escape=F, align="l") %>% 
  trimws %>% 
  kable_styling(c("striped","bordered"))

Finally, let’s look at a comparison test for a categorical row. The default comparison function is cat_comp_default, which will calculate the relative entropy between each column and the reference category, as well as conduct a Chi-Square Goodness of Fit test on the data present. Currently, cat_comp_default is the only built-in function for categorical data, but a user may write their own function to use instead.

tbl1 <- tbl_start(data=iris, col_var="Species", missing=FALSE, overall=TRUE, comparison=FALSE) %>% 
  cat_row("Stem.Size", rowlabel="Stem Size", comparison=cat_comp_default) %>%
  tbl_out()
tbl1 %>% 
  tangram_styling() %>% 
  kable(escape=F, align="l") %>% 
  trimws %>% 
  kable_styling(c("striped","bordered"))

Binary Rows

The final type of data we will examine here is binary data; this is when a variable can only take on two possible values. In a table, it can be helpful to only include one of the options if the second entry can be deduced from looking at the first. This is done using the binary_row function. The default summary function is binary_default, but the user may write their own function to calculate different summary statistics from what is shown here.

Currently, there are four summary functions available for use within binary_row. The default summary to use for each row can be specified in tbl_start, or determined using the summary argument of each row.

binary_default : Calculates the cell counts and column-wise proportions

binary_pct : Calculates the cell counts and column-wise percentages

binary_count: Calculates the cell counts

binary_jama : Calculates the column-wise percentages and cell counts divided by column totals. This is the style used by the Journal of the American Medical Association.

Note that a user may use cat_row to process binary data if they wish to see both row entries included in the table.

We will now demonstrate the use of binary_row on the color variable in iris. In the dataset, the available colors are blue and purple, so we do not wish to include both entries here.

tbl1 <- tbl_start(data=iris, col_var="Species", missing=FALSE, overall=TRUE, comparison=FALSE) %>% 
  binary_row("color", rowlabel = "Color") %>%
  tbl_out()
tbl1 %>% 
  tangram_styling() %>% 
  kable(escape=F, align="l") %>% 
  trimws %>% 
  kable_styling(c("striped","bordered"))

The binary_row function includes all of the same arguments as the previous row functions, but additionally includes three new arguments. reference allows a user to choose which group will appear on the table. By default, the alphabetically first row group will appear on the table, which is why ‘Blue’ appeared above. If we want to see the statistics for purple flowers, we can run the following code.

tbl1 <- tbl_start(data=iris, col_var="Species", missing=FALSE, overall=TRUE, comparison=FALSE) %>% 
  binary_row("color", rowlabel = "Color", reference="Purple") %>%
  tbl_out()
tbl1 %>% 
  tangram_styling() %>% 
  kable(escape=F, align="l") %>% 
  trimws %>% 
  kable_styling(c("striped","bordered"))

Notice in the previous examples that the binary row is contained entirely within one row. This is because many tables in professional journals will often abbreviate binary data to fit within a single row of data. If you do not wish to do this within your table, you can set the additional argument compact to be FALSE and display the row information in more than one row.

tbl1 <- tbl_start(data=iris, col_var="Species", missing=FALSE, overall=TRUE, comparison=FALSE) %>% 
  binary_row("color", rowlabel = "Color", compact = FALSE) %>%
  tbl_out()
tbl1 %>% 
  tangram_styling() %>% 
  kable(escape=F, align="l") %>% 
  trimws %>% 
  kable_styling(c("striped","bordered"))

As of package version 1.1.2, the user can now choose to remove the reference group label from the table if they do not want it to be present. The argument ref.label allows a user to toggle the name of the reference group in the table; by default, this is set to on, but a user can input off to remove it.

Finally, let’s look at some comparison functions used for binary data. By default, this row function will calculate the difference in proportions by using binary_diff if comparison=TRUE during initialization. This will calculate differences in proportions across columns; the calculations will also include 95% Confidence intervals.

tbl1 <- tbl_start(data=iris, col_var="Species", missing=FALSE, overall=TRUE, comparison=FALSE) %>% 
  binary_row("color", comparison=binary_diff) %>%
  tbl_out()
tbl1 %>% 
  tangram_styling() %>% 
  kable(escape=F, align="l") %>% 
  trimws %>% 
  kable_styling(c("striped","bordered"))

The package has two additional options for comparison tests using binary data. Odds ratios can be calculated using binary_or, and risk ratios can be calculated with binary_rr. Note that if comparison=TRUE is initialized in tbl_start and a user wants to use an odds ratio or risk ratio here, comparison must be set to either of those two options in this row addition, since excluding the argument will lead to binary_diff being called by default.

tbl1 <- tbl_start(data=iris, col_var="Species", missing=FALSE, overall=TRUE, comparison=FALSE) %>% 
  binary_row("color", comparison=binary_or) %>%
  tbl_out()
tbl1 %>% 
  tangram_styling() %>% 
  kable(escape=F, align="l") %>% 
  trimws %>% 
  kable_styling(c("striped","bordered"))

tbl1 <- tbl_start(data=iris, col_var="Species", missing=FALSE, overall=TRUE, comparison=FALSE) %>% 
  binary_row("color", comparison=binary_rr) %>%
  tbl_out()
tbl1 %>% 
  tangram_styling() %>% 
  kable(escape=F, align="l") %>% 
  trimws %>% 
  kable_styling(c("striped","bordered"))

N Row

The n_row function will count the number of rows in your dataset, as well as the total instances of each column variable. Note that you can decide whether or not you want this function to include the missing data as part of your row count. For the example below we will not include rows from missing data.

tbl1 <- tbl_start(data=iris, col_var="Species", missing=FALSE, overall=TRUE, comparison=FALSE) %>% 
  n_row() %>%
  tbl_out()
tbl1 %>% 
  tangram_styling() %>% 
  kable(escape=F, align="l") %>% 
  trimws %>% 
  kable_styling(c("striped","bordered"))

Adding an empty row

The empty_row function will add a blank row to the final table. This is useful if a user wants to include blank space between some of table’s rows. The user only needs to specify the name of the list object in order to create the blank row. An optional argument is a header to include, should the user want to create a label for the subsequent rows that follow in the table.

tbl1 <- tbl1 %>% empty_row()

Single Column of Data

The package can handle cases where a user only wants a single summary column of data. In the iris dataset, if we set the column variable to be NULL in tbl_start, we can obtain just one summary column for the dataset without breaking the table up by columns. Note that comparison functions will not run here, even if the comparison argument is set to TRUE.

tbl1 <- tbl_start(iris, NULL, missing=FALSE, overall=TRUE, comparison=FALSE) %>%
  n_row() %>%
  num_row("Sepal.Length", rowlabel="Sepal Length") %>%
  tbl_out()
tbl1 %>% 
  tangram_styling() %>%
  kable(escape=F, align="l") %>% 
  trimws %>% 
  kable_styling(c("striped","bordered"))

1.1.2 (released August 2022)

1. The digits parameter is now available in tbl_start for specifying default digits to use throughout the table.

2. Added ref.label argument in binary summary functions to allow user to toggle reference group labels in binary rows.

3. Deprecated the print.tangram.pipe function, as the update to tbl_out in version 1.1.1 rendered this function obsolete.

1.1.1 (released April 2022)

1. Fixed a bug in num_row where column category names with spaces would not format correctly.

2. Changed binary_row output to include the rowlabel along with the displayed category when compact = TRUE.

3. Fixed a bug in binary_row where numeric row category labels would not format correctly when compact = TRUE.

4. Added ordering and sortcol arguments to cat_row.

5. Edited categorical summary functions to utilize sorting arguments.

6. Added prewritten summary functions num_date, cat_count, and binary_count.

7. Edited tbl_out to output the finalized dataframe object (previous version only appended the final table to the table information list).

1.1.0 (released October 2021)

1. Changed the rowlabels argument to rowlabel.

2. Options overall, missing, and comparison now have default values in tbl_start().

3. Only leading white spaces are formatted to HTML form in tangram_styling.

4. Added n_row() as a row function to the table.

5. Added prewritten summary functions num_minmax, num_medianiqr, num_mean_sd, cat_pct, cat_jama, binary_pct, binary_jama.

6. Added options default_num_summary, default_cat_summary, default_binary_summary to tbl_start(). Default values are set to the default summary functions for each row.

7. Changed the summary argument within the row functions to automatically use the default specified in tbl_start(), unless another function is supplied by the user. The default in the function argument has changed from a function to NULL.

8. Summary functions now take on generic arguments specified by an ellipsis (…), but still work the same as before within the row functions.

9. binary_row() now has the option to condense to one row (compact). Default is TRUE.