Latest Improvements

Version 0.8.3 brings several improvements to summarytools, notably:

• Introduction of global settings (customizable defaults)
• Options to make content fit more naturally in shiny apps or Rmarkdown documents
• A better handling of “split-group” statistics with by()
• A more thorough documentation

summarytool’s Core Functions

1 - freq() : Frequency Tables

The freq() function generates a table of frequencies with counts and proportions. Since this page use markdown rendering, we’ll set style = 'rmarkdown' to take advantage of it.

library(summarytools)
freq(iris$Species, style = "rmarkdown")

freq(iris$Species, report.nas = FALSE, style = "rmarkdown", omit.headings = TRUE)

2 - ctable() : Cross-Tabulations

We’ll now use a sample data frame called tobacco, which is included in the package. We want to cross-tabulate the two categorical variables smoker and diseased. By default, ctable() gives row proportions, but we’ll include the full syntax anyway.

Since markdown has not support (yet) for multi-line headings, we’ll show an image of the resulting html table.

with(tobacco, print(ctable(smoker, diseased), method = 'render'))

Notice that instead of ctable(tobacco$smoker, tobacco$diseased, ...), we used the with() function, making the syntax less redundant.

It is possible to display column, total, or no proportions at all. We can also omit the marginal totals to have a simple “2 x 2” table.

with(tobacco, 
     print(ctable(smoker, diseased, prop = 'n', totals = FALSE), 
           omit.headings = TRUE, method = "render"))

3 - descr() : Descriptive Univariate Stats

The descr() function generates common central tendency statistics and measures of dispersion for numerical data. It can handle single vectors as well as data frames, in which case it just ignores non-numerical columns (and displays a message to that effect).

descr(iris, style = "rmarkdown")

Non-numerical variable(s) ignored: Species

descr(iris, stats = c("mean", "sd", "min", "med", "max"), transpose = TRUE, 
      omit.headings = TRUE, style = "rmarkdown")

Non-numerical variable(s) ignored: Species

4 - dfSummary() : Data Frame Summaries

dfSummary() collects information about all variables in a data frame and displays it in a singe, legible table.

To generate a summary report and have it displayed in RStudio’s Viewer pane (or in your default Web Browser if working with another interface), we simply do like this:

view(dfSummary(iris))

It is also possible to use dfSummary() in Rmarkdown documents. In this next example, note that due to rmarkdown compatibility issues, histograms are not shown. We’re working on this. Further down, we’ll see how tu use html rendering to go around this problem.

dfSummary(tobacco, plain.ascii = FALSE, style = "grid")

The print() and view() Functions

summarytools has a generic print method, print.summarytools(). By default, its method argument is set to 'pander'. One of the ways in which view() is useful is that we can use it to easily display html outputs in RStudio’s Viewer. In this case, the view() function simply acts as a wrapper around the generic print() function, specifying the method = 'viewer' for us. When used outside RStudio, the method falls back on 'browser' and the report is fired up in the system’s default browser.

Using by() to Show Results By Groups

With freq() and descr(), you can use R’s base function by() to show statistics split by a ventilation / categorical variable. R’s by() function returns a list containing as many summarytools objects as there are categories in our ventilation variable.

To propertly display the content present in that list, we use the view() function. Using print(), while technically possible, will not give as much satisfactory results.

# First save the results
iris_stats_by_species <- by(data = iris, 
                            INDICES = iris$Species, 
                            FUN = descr, stats = c("mean", "sd", "min", "med", "max"), 
                            transpose = TRUE)

# Then use view(), like so:
view(iris_stats_by_species, method = "pander", style = "rmarkdown")

view(iris_stats_by_species)

data(tobacco) # tobacco is an example dataframe included in the package
BMI_by_age <- with(tobacco, 
                   by(BMI, age.gr, descr, 
                      stats = c("mean", "sd", "min", "med", "max")))
view(BMI_by_age, "pander", style = "rmarkdown")

BMI_by_age <- with(tobacco, 
                   by(BMI, age.gr, descr,  transpose = TRUE,
                      stats = c("mean", "sd", "min", "med", "max")))
view(BMI_by_age, "pander", style = "rmarkdown", omit.headings = TRUE)

Using lapply() to Show Several freq() tables at once

As is the case for by(), the view() function is essential for making results nice and tidy.

tobacco_subset <- tobacco[ ,c("gender", "age.gr", "smoker")]
freq_tables <- lapply(tobacco_subset, freq)
view(freq_tables, footnote = NA, file = 'freq-tables.html')

Using summarytools in Rmarkdown documents

As we have seen, summarytools can generate both text (including rmarkdown) and html results. Both can be used in Rmarkdown, according to your preferences. There is a vignette dedicated to this, which gives several examples, but if you’re in a hurry, here are a few tips to get started:

• Always set the knitr chunk option results = 'asis'. You can do this on a chunk-by-chunk basis, but here is how to do it globally:

    knitr::opts_chunk$set(echo = TRUE, results = 'asis')

          Refer to this page for more on knitr’s options.

• To get better results when using html (with method = 'render'), set up your .Rmd document so it includes summarytool’s css.

# ---
# title: "RMarkdown using summarytools"
# output: 
#   html_document: 
#     css: C:/R/win-library/3.4/summarytools/includes/stylesheets/summarytools.css
# ---

Writing Output to Files

The console will always tell you the location of the temporary html file that is created in the process. However, you can specify the name and location of that file explicitly if you need to reuse it later on:

view(iris_stats_by_species, file = "~/iris_stats_by_species.html")

Based on the file extension you provide (.html vs others), summarytools will use the appropriate method; there is no need to specify the method argument.

Global options

Version 0.8.3 introduced the following set of global options:

• round.digits = 2
• plain.ascii = TRUE
• omit.headings = FALSE (if using in a markdown document or a shiny app, setting this to TRUE might be preferable
• footnote = 'default' (set to empty string or NA to omit footnote)
• display.labels = TRUE
• freq.totals = TRUE
• freq.display.nas = TRUE
• ctable.totals = TRUE
• ctable.prop = 'r' (display row proportions by default)
• descr.stats = 'all'
• descr.transpose = FALSE
• bootstrap.css = TRUE (if using in a markdown document or a shiny app, setting this to FALSE might be preferable
• custom.css = NA
• escape.pipe = FALSE

st_options()                      # display all global options' values
st_options('round.digits')        # display only one option
st_options('omit.headings', TRUE) # change an option's value
st_options('footnote', NA)        # Turn off the footnote on all outputs.
                                  # This option was used prior to generating
                                  # the present document.

Overriding formatting attributes

When a summarytools object is stored, its formatting attributes are stored with it. However, you can override most of them when using the print() and view() functions.

age_stats <- freq(tobacco$age.gr)  # age_stats contains a regular output for freq 
                                   # including headings, NA counts, and Totals
print(age_stats, style = "rmarkdown", report.nas = FALSE, 
                 totals = FALSE, omit.headings = TRUE)

Order of Priority for Options / Parameters

1. Options over-ridden explicitly with print() or view() have precendence
2. options specified as explicit arguments to freq() / ctable() / descr() / dfSummary() come second
3. Global options, which can be set with st_options, come third

Customizing looks with CSS

Version 0.8 of summarytools uses RStudio’s htmltools package and version 4 of Bootstrap’s cascading stylesheets.

It is possible to include your own css if you wish to customize the look of the output tables. See the documentation for the package’s print.summarytools() function for details, but here is a quick example to give you the gist of it.

.table-condensed {
  font-size: 8px;
}

view(dfSummary(tobacco), custom.css = 'path/to/custom.css', 
     table.classes = 'table-condensed')

Working with shiny apps

To include summarytools functions into shiny apps, it is recommended that you:

• set bootstrap.css = FASE to avoid interacting with the app’s layout
  
• adjust the size of the graphs in dfSummary()
• set omit.headings to TRUE

print(dfSummary(somedata, graph.magnif = 0.8), 
      method = 'render',
      omit.headings = TRUE,
      bootstrap.css = FALSE)

Getting Most Properties of an Object With what.is()

When developing, we often use a number of functions to obtain an object’s properties. what.is() proposes to lump together the results of most of these functions (class(), typeof(), attributes() and others).

what.is(iris)

$properties
      property      value
1        class data.frame
2       typeof       list
3         mode       list
4 storage.mode       list
5          dim    150 x 5
6       length          5
7    is.object       TRUE
8  object.type         S3
9  object.size 7256 Bytes

$attributes.lengths
    names     class row.names 
        5         1       150 

$extensive.is
[1] "is.data.frame" "is.list"       "is.object"     "is.recursive" 
[5] "is.unsorted"  

Limitations

• The text histograms in dfSummary are not yet supported in rmarkdown. Better use the ‘render’ method.
• It is not possible to control the heading levels of individual items. You can however choose to omit.headings altogether.

Stay Up-to-date

Check out the project’s page - from there you can see the latest updates and also submit feature requests.

To install the version of summarytools that is on CRAN, but that might have benefited from quick fixes:

install.packages('devtools')
library(devtools)
install_github('dcomtois/summarytools')

To install the package in its development version, use

install_github('dcomtois/summarytools', ref='dev-current')

Final notes

The package comes with no guarantees. It is a work in progress and feedback / feature requests are welcome. Just send me an email (dominic.comtois (at) gmail.com), or open an Issue on GitHub if you find a bug.