Sample dataset

For our examples, we’ll load the mockstudy data included with this package and use it to create a basic table. Because they have fewer levels, for brevity, we’ll use the variables arm, sex, and mdquality.s to create the example table. We’ll retain NAs in the table creation. See the appendix for notes regarding default NA handling and other useful information regarding tables in R.

# load the data
data(mockstudy)

# retain NAs when creating the table using the useNA argument
tab.ex <- table(mockstudy[, c("arm", "sex", "mdquality.s")], useNA="ifany")

Including combinations with frequencies of zero

The sparse= argument takes a single logical value as input. The default option is FALSE. If set to TRUE, the sparse option will include combinations with frequencies of zero in the list of results. As our initial table did not have any such levels, we create a second table to use in our example.

summary(freqlist(~ race + sex + arm, data = mockstudy, sparse = TRUE, digits.pct=1))

Options for NA handling

The various na.options= allow you to include or exclude data with missing values for one or more factor levels in the counts and percentages, as well as show the missing data but exclude it from the cumulative counts and percentages. The default option is to include all combinations with missing values.

summary(freqlist(tab.ex, na.options="include"))

summary(freqlist(tab.ex, na.options="showexclude"))

summary(freqlist(tab.ex, na.options="remove"))

Frequency counts and percentages subset by factor levels

The strata= argument internally subsets the data by the specified factor prior to calculating cumulative counts and percentages. By default, when used each subset will print in a separate table. Using the single = TRUE option when printing will collapse the subsetted result into a single table.

example3 <- freqlist(tab.ex, strata = c("arm","sex"))
summary(example3)

#using the single = TRUE argument will collapse results into a single table for printing
summary(example3, single = TRUE)

Show only the “n” most common combinations in each table (head() and sort())

You can now sort freqlist() objects, and, by taking the head() of the summary, output the most common frequencies. This looks the prettiest with dupLabels=TRUE.

head(summary(sort(example1, decreasing = TRUE), dupLabels = TRUE))

|arm       |sex    |mdquality.s | Freq| Cumulative Freq| Percent| Cumulative Percent|
|:---------|:------|:-----------|----:|---------------:|-------:|------------------:|
|F: FOLFOX |Male   |1           |  285|             285|   19.01|              19.01|
|A: IFL    |Male   |1           |  214|             499|   14.28|              33.29|
|F: FOLFOX |Female |1           |  198|             697|   13.21|              46.50|
|G: IROX   |Male   |1           |  187|             884|   12.47|              58.97|
|G: IROX   |Female |1           |  121|            1005|    8.07|              67.04|
|A: IFL    |Female |1           |  118|            1123|    7.87|              74.92|

Change labels on the fly

labs <- c(arm = "Arm", sex = "Sex", mdquality.s = "QOL", freqPercent = "%")
labels(example1) <- labs
summary(example1)

You can also supply labelTranslations= to summary().

summary(example1, labelTranslations = labs)

Using xtable() to format and print freqlist() results

Fair warning: xtable() has kind of a steep learning curve. These examples are given without explanation, for more advanced users.

require(xtable)

Loading required package: xtable

# set up custom function for xtable text
italic <- function(x) paste0('<i>', x, '</i>')

xftbl <- xtable(as.data.frame(summary(example1)), 
  caption = "xtable formatted output of freqlist data frame", align="|r|r|r|r|c|c|c|r|")

# change the column names
names(xftbl)[1:3] <- c("Arm", "Gender", "LASA QOL")

print(xftbl, sanitize.colnames.function = italic, include.rownames = FALSE, type = "html", comment = FALSE)

Use freqlist in bookdown

Since the backbone of freqlist() is knitr::kable(), tables still render well in bookdown. However, print.summary.freqlist() doesn’t use the caption= argument of kable(), so some tables may not have a properly numbered caption. To fix this, use the method described on the bookdown site to give the table a tag/ID.

summary(freqlist(~ sex + age, data = mockstudy), title="(\\#tab:mytableby) Caption here")

NAs

There are several widely used options for basic tables in R. The table() function in base R is probably the most common; by default it excludes NA values. You can change NA handling in base::table() using the useNA= or exclude= arguments.

# base table default removes NAs
tab.d1 <- base::table(mockstudy[, c("arm", "sex", "mdquality.s")], useNA="ifany")
tab.d1

, , mdquality.s = 0

           sex
arm         Male Female
  A: IFL      29     12
  F: FOLFOX   31     21
  G: IROX     17     14

, , mdquality.s = 1

           sex
arm         Male Female
  A: IFL     214    118
  F: FOLFOX  285    198
  G: IROX    187    121

, , mdquality.s = NA

           sex
arm         Male Female
  A: IFL      34     21
  F: FOLFOX   95     61
  G: IROX     24     17

xtabs() is similar to table(), but uses a formula-based syntax. However, NAs must be explicitly added to each factor using the addNA() function or using the argument addNA = TRUE.

# without specifying addNA
tab.d2 <- xtabs(formula = ~ arm + sex + mdquality.s, data = mockstudy)
tab.d2

, , mdquality.s = 0

           sex
arm         Male Female
  A: IFL      29     12
  F: FOLFOX   31     21
  G: IROX     17     14

, , mdquality.s = 1

           sex
arm         Male Female
  A: IFL     214    118
  F: FOLFOX  285    198
  G: IROX    187    121

# now with addNA
tab.d3 <- xtabs(~ arm + sex + addNA(mdquality.s), data = mockstudy)
tab.d3

, , addNA(mdquality.s) = 0

           sex
arm         Male Female
  A: IFL      29     12
  F: FOLFOX   31     21
  G: IROX     17     14

, , addNA(mdquality.s) = 1

           sex
arm         Male Female
  A: IFL     214    118
  F: FOLFOX  285    198
  G: IROX    187    121

, , addNA(mdquality.s) = NA

           sex
arm         Male Female
  A: IFL      34     21
  F: FOLFOX   95     61
  G: IROX     24     17

Since the formula method of freqlist() uses xtabs(), NAs should be treated in the same way. includeNA() can also be helpful here for setting explicit NA values.

Table dimname names (dnn)

Supplying a data.frame to the table() function without giving columns individually will create a contingency table using all variables in the data.frame.

However, if the columns of a data.frame or matrix are supplied separately (i.e., as vectors), column names will not be preserved.

# providing variables separately (as vectors) drops column names
table(mockstudy$arm, mockstudy$sex, mockstudy$mdquality.s)

, ,  = 0

           
            Male Female
  A: IFL      29     12
  F: FOLFOX   31     21
  G: IROX     17     14

, ,  = 1

           
            Male Female
  A: IFL     214    118
  F: FOLFOX  285    198
  G: IROX    187    121

If desired, you can use the dnn= argument to pass variable names.

# add the column name labels back using dnn option in base::table
table(mockstudy$arm, mockstudy$sex, mockstudy$mdquality.s, dnn=c("Arm", "Sex", "QOL"))

, , QOL = 0

           Sex
Arm         Male Female
  A: IFL      29     12
  F: FOLFOX   31     21
  G: IROX     17     14

, , QOL = 1

           Sex
Arm         Male Female
  A: IFL     214    118
  F: FOLFOX  285    198
  G: IROX    187    121

You can also name the arguments to table():

table(Arm = mockstudy$arm, Sex = mockstudy$sex, QOL = mockstudy$mdquality.s)

, , QOL = 0

           Sex
Arm         Male Female
  A: IFL      29     12
  F: FOLFOX   31     21
  G: IROX     17     14

, , QOL = 1

           Sex
Arm         Male Female
  A: IFL     214    118
  F: FOLFOX  285    198
  G: IROX    187    121

If using freqlist(), you can provide the labels directly to freqlist() or to summary() using labelTranslations=.