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)

# examine the data
str(mockstudy)

'data.frame':   1499 obs. of  14 variables:
 $ case       : int  110754 99706 105271 105001 112263 86205 99508 90158 88989 90515 ...
 $ age        : atomic  67 74 50 71 69 56 50 57 51 63 ...
  ..- attr(*, "label")= chr "Age in Years"
 $ arm        : atomic  F: FOLFOX A: IFL A: IFL G: IROX ...
  ..- attr(*, "label")= chr "Treatment Arm"
 $ sex        : Factor w/ 2 levels "Male","Female": 1 2 2 2 2 1 1 1 2 1 ...
 $ race       : atomic  Caucasian Caucasian Caucasian Caucasian ...
  ..- attr(*, "label")= chr "Race"
 $ fu.time    : int  922 270 175 128 233 120 369 421 387 363 ...
 $ fu.stat    : int  2 2 2 2 2 2 2 2 2 2 ...
 $ ps         : int  0 1 1 1 0 0 0 0 1 1 ...
 $ hgb        : num  11.5 10.7 11.1 12.6 13 10.2 13.3 12.1 13.8 12.1 ...
 $ bmi        : atomic  25.1 19.5 NA 29.4 26.4 ...
  ..- attr(*, "label")= chr "Body Mass Index (kg/m^2)"
 $ alk.phos   : int  160 290 700 771 350 569 162 152 231 492 ...
 $ ast        : int  35 52 100 68 35 27 16 12 25 18 ...
 $ mdquality.s: int  NA 1 1 1 NA 1 1 1 1 1 ...
 $ age.ord    : Ord.factor w/ 8 levels "10-19"<"20-29"<..: 6 7 4 7 6 5 4 5 5 6 ...

# 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.

# we create a second table example to showcase the sparse argument
tab.sparse <- table(mockstudy[, c("race", "sex", "arm")])

nobysparse <- freqlist(tab.sparse, sparse = TRUE, digits = 1)
summary(nobysparse)

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 groupBy 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.

withby <- freqlist(tab.ex, groupBy = c("arm", "sex"))
summary(withby)

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

Change labels on the fly

At this time, the labels can be changed just for the variables (e.g. not the frequency columns).

labels(noby) <- c("Arm", "Sex", "OtherThing")
summary(noby)

You can also supply labelTranslations to summary.

summary(noby, labelTranslations = c("Hi there", "What up", "Bye"))

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(noby[["freqlist"]], 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)

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, there is not an option for retaining NAs in the xtabs function; instead, NAs must be added to each level of the factor where present using the addNA function.

# 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

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
tab.d4 <- base::table(mockstudy[, "arm"], mockstudy[, "sex"], mockstudy[, "mdquality.s"])
tab.d4

, ,  = 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
tab.dnn <- base::table(mockstudy[, "arm"], mockstudy[, "sex"], mockstudy[, "mdquality.s"], 
    dnn = c("Amy", "Susan", "George"))
tab.dnn

, , George = 0

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

, , George = 1

           Susan
Amy         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.