The following vignettes complement this page:

Recommendations for Using summarytools With Rmarkdown
Changes Introduced in summarytools 0.9

summarytools is an R package providing tools to neatly and quickly summarize data. It can also make R a little easier to learn and to use, especially for data cleaning and preliminary analysis. Four functions are at the heart of the package:

• freq() : frequency tables with proportions, cumulative proportions and missing data information
• ctable() : cross-tabulations between two factors or any discrete data, with total, rows or columns proportions, as well as marginal totals
• descr() : descriptive (univariate) statistics for numerical data
• dfSummary() : Extensive data frame summaries that facilitate data cleaning and firsthand evaluation

An emphasis has been put on both what and how results are presented, so that the package can serve both as an exploration and reporting tool, used on its own for minimal reports, or with other sets of tools such as rmarkdown, and knitr.

Building on the strengths of pander and htmltools, the outputs produced by summarytools can be:

• Displayed in plain text in the R console (default behaviour)
• Used in Rmarkdown documents and knitted along with other text and R output
• Written to html files that fire up in RStudio’s Viewer pane or in the default browser
• Written to plain or Rmarkdown text files

It is also possible to include summarytools’ functions in Shiny apps. Notably, radiant, a Shiny-based package for business analytics, uses dfSummary() to describe imported data frames.

Version 0.9 brings many changes and improvements. This document gives a detailed description of those changes, but a summary can also be found at the end of the present page.

This is the recommended method, as some minor fixes are made available between CRAN releases.

Magick++ Dependancy on Linux and Mac OS

Before proceeding, you must install Magick++

 - deb: 'libmagick++-dev' (Debian, Ubuntu)
 - rpm: 'ImageMagick-c++-devel' (Fedora, CentOS, RHEL)
 - csw: 'imagemagick_dev' (Solaris)

On MacOS it is recommended to use install ImageMagick-6 from homebrew
with extra support for fontconfig and rsvg rendering:
   brew reinstall imagemagick@6 --with-fontconfig --with-librsvg

For older Ubuntu versions Trusty (14.04) and Xenial (16.04) use the PPA:
   sudo add-apt-repository -y ppa:opencpu/imagemagick
   sudo apt-get update
   sudo apt-get install -y libmagick++-dev

After this is done, proceed with the installation:

install.packages("devtools")
library(devtools)
install_github("rapporter/pander") # Necessary for optimal results!
install_github("dcomtois/summarytools")

Simply install it with install.packages():

install.packages("summarytools")

The official documentation can be found here.

The freq() function generates a table of frequencies with counts and proportions. Since GitHub uses markdown rendering, we’ve set the style argument to “rmarkdown”. When creating Rmd documents, knitr takes care of converting the generated markup characters into actual html or pdf formatting.

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

iris$Species
Type: Factor

If we do not worry about missing data, we can set report.nas = FALSE:

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

We can simplify the results further and omit the Totals row by specifying totals = FALSE.

To get familiar with the various output styles, try different values for style – “simple”, “rmarkdown” or “grid”, and see how this affects the results in the console.

We’ll now use a sample data frame called tobacco, which is included in the package. We want to cross-tabulate two categorical variables: smoker and diseased.

Since markdown does not support multiline headings, we’ll show a rendered html version of the results:

print(ctable(tobacco$smoker, tobacco$diseased, prop = "r"), method = "render")

Note that we have to set the knitr chunk option results to “asis” for the results to appear as they should.

By default, ctable() shows row proportions. To show column or total proportions, use prop = "c" or prop = "t", respectively. To omit proportions, use prop = "n".

In the next example, we’ll create a simple “2 x 2” table:

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

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

iris
N: 150

If your eyes/brain prefer seeing things the other way around, just use transpose = TRUE. Here, we also select only the statistics we wish to see, and specify headings = FALSE to avoid reprinting the same information as above.

We specify the stats we wish to report with the stats argument, which also accepts values “all”, “fivenum”, and “common”. See ?descr for The full list of available statistics.

descr(iris, stats = "common", transpose = TRUE, 
      headings = FALSE, style = "rmarkdown")

## Non-numerical variable(s) ignored: Species

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 the default Web browser if working outside RStudio), we simply do as follows:

library(summarytools)
view(dfSummary(iris))

Of course, it is also possible to use dfSummary() in Rmarkdown documents. It is usually a good idea to exclude a column or two, otherwise the table might be a bit too wide. For instance, since the Valid and NA columns are redundant, we can drop one of them.

You might notice a message about temporary files being stored in the “img” subdirectory; the reason why these temporary images are not written in the system temporary directory is that by doing so, we would have long paths to those files, and due to a limitation in pandoc, this would mean extremely wide columns. Using cleartmp(), we can delete those temporary images.

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 print() method, specifying method = 'viewer'. When used outside RStudio, this method falls back on “browser” and the report is shown in the system’s default browser.

We can use stby() the same way as R’s base function by() with all main summarytools functions. This returns a list-type object containing as many elements as there are categories in the grouping variable.

Using the iris data frame, we will display descriptive statistics by Species.

(iris_stats_by_species <- stby(data = iris, 
                               INDICES = iris$Species, 
                               FUN = descr, stats = c("mean", "sd", "min", "med", "max"), 
                               transpose = TRUE))

## Non-numerical variable(s) ignored: Species

Descriptive Statistics
iris
Group: Species = setosa
N: 50

Group: Species = versicolor
N: 50

Group: Species = virginica
N: 50

To see an html version of these results, we simply use view() (also possible is to use print() with method = "viewer"):

view(iris_stats_by_species)
# or
print(iris_stats_by_species, method = "viewer")

A special situation occurs when we want grouped statistics for one variable only using descr(). Instead of showing several tables with only one column each, summarytools assembles everything into a single table:

data(tobacco)
BMI_by_age <- with(tobacco, 
                   stby(BMI, age.gr, descr, 
                        stats = c("mean", "sd", "min", "med", "max")))
print(BMI_by_age, style = "rmarkdown")

BMI by age.gr
Data Frame: tobacco
N: 258

The transposed version looks like this:

BMI_by_age <- with(tobacco, 
                   stby(BMI, age.gr, descr,  transpose = TRUE,
                        stats = c("mean", "sd", "min", "med", "max")))
print(BMI_by_age, style = "rmarkdown", headings = FALSE)

The syntax to use is as follows:

stby(list(x = tobacco$smoker, y = tobacco$diseased), tobacco$gender, ctable)
# or equivalently
with(tobacco, stby(list(x = smoker, y = diseased), gender, ctable))

There is more than one way to do this, but I recommend passing the data frame object (subsetted if needed) directly to freq():

freq(tobacco[ ,c("gender", "age.gr", "smoker")])

Another way to do it would be using lapply(), but automatic printing will not be optimal; we’ll need to explicitly call the print() method to have proper results (i.e. without repeating heading elements).

As we have seen, summarytools can generate both text/markdown and html results. Both types of outputs can be used in Rmarkdown documents. The vignette Recommendations for Using summarytools With Rmarkdown provides good guidelines, but 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 it is easier 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 generating html output with method = 'render', set up your .Rmd document so that it includes summarytools’ css. The st_css() function makes this very easy.

# ---
# title: "RMarkdown using summarytools"
# output: html_document
# ---
#
# ```{r setup, include=FALSE}
# library(knitr)
# opts_chunk$set(comment = NA, prompt = FALSE, cache = FALSE, results = 'asis')
# library(summarytools)
# st_options(plain.ascii = FALSE, style = "rmarkdown")
#```
#
# ```{r, echo=FALSE}
# st_css()
# ```
#
# ```{r}
# print(dfSummary(tobacco, style = 'grid', graph.magnif = 0.82), 
#       method = 'render', headings = FALSE, varnumbers=FALSE, valid.col = FALSE)
# ```

We can use the file argument with print() or view() to indicate that we want to save the results in a file, be it html, Rmd or plain text. The file extension indicates what type of file we wish to generate.

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

The append argument allows adding content to existing files generated by summarytools. This is useful if you want to quickly include several statistical tables in a single file. It is a quick alternative to creating an .Rmd document.

The following options can be set with st_options():

General Options

Function-Specific Options

st_options()                      # display all global options values
st_options('round.digits')        # display the value of a specific option
st_options(style = 'rmarkdown')   # change one or several options' values
st_options(footnote = NA)         # Turn off the footnote on all outputs.
                                  # This option was used prior to generating
                                  # the present document.

When a summarytools object is created, its formatting attributes are stored within it. However, you can override most of them when using the print() method or the view() function.

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, Variable.label = "Age Group")

tobacco$age.gr
Label: Age Group
Type: Factor

Note that the original attributes are still part of the age_stats object, left unchanged.

1. Options overridden explicitly in print() or view() have precedence
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

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 ?print.summarytools for all the details, but here is a quick example.

Say you need to make the font size really really small. For this, you would create a .css file - let’s call it “custom.css” - containing a class definition such as the following:

.tiny-text {
  font-size: 8px;
}

Then, to apply it to a summarytools object and display it in your browser:

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

To display a smaller table that is not that small, you can use the provided css class st-small.

To include summarytools functions in Shiny apps, it is recommended that you:

• set bootstrap.css = FALSE to avoid interacting with the app’s layout
• omit headings by setting the global option headings = FALSE
• adjust the size of the graphs in dfSummary() using the dfSummary.graph.magnif gobal option
• if dfSummary() outputs are too wide, try omitting a column or two (valid.col and varnumbers, for instance)
• if needed, set the column widths manually with the col.widths parameter of the print() method or the view() function

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

As stated earlier, version 0.9 brings many improvements to summarytools. This document gives a detailed description of the changes, but here are the main elements:

• Translations
  • For now, only a limited number of languages are available (fr, es, ru), but as users contribute their own translations, the list will hopefully grow much larger
  • To use a different language than English, call the st_options() function, like so: st_options(lang = "fr")
  • An additional function, useTranslations() allows using custom translations; a template is available here
• Improved printing of list objects
  • Objects of class “stby” are automatically printed in the console with optimal results; no more need for view(x, method = "pander"); simply use stby() instead of by()
  • Regular lists containing summarytools objects can also be printed with optimal results simply by calling print(x) (as opposed to “stby” objects, their automatic printing will not be optimal; that being said, freq() now accepts data frames as its first argument, so the need for lapply() is greatly diminished)
• Easier management of global settings with st_options()
  • st_options() now has as many parameters as there are options to set, making it possible to set all options with only one function call; the legacy way of setting options is still supported however
  • Several global options were added, simplifying Rmarkdown document creation
• Changes to dfSummary()
  • Now fully compatible with Rmarkdown
  • Number of columns is now included in the heading section
  • Number of duplicated rows is also shown in the heading section
  • Bar plots now more accurately reflect counts, as they are not stretched across table cells (this allows the comparison of frequencies across variables)
  • Columns with particular content (unary/binary, integer sequences, UPC/EAN codes) are treated differently; more relevant information is displayed, while irrelevant information is hidden
  • For html outputs, a new parameter col.widths may be used to set the width of the resulting table’s columns; this addresses an issue with some graphs not being shown at the desired magnification level (although much effort has been put into improving this as well)
  • Graph background transparency “works” in a more consistent way
• Changes to descr()
  • For the stats argument, Values “fivenum” and “common” are now allowed, the latter representing the collection of mean, sd, min, med, max, n.valid, and pct.valid
  • Improved outputs when using stby()
  • The variable used for weights (if any) is removed automatically from the data so no stats are produced for it
• Changes to freq()
  • As mentioned earlier, the function now accepts data frames as its main argument; this makes practically obsolete the use of lapply() with it
  • Improved outputs when using stby()
• Changes to ctable()
  • Fully supports stby()
  • Number alignment in html tables much improved

Other notable changes

• The omit.headings parameter has been replaced by the more straightforward (and still boolean) headings. omit.heandings is still supported but will be deprecated in future releases
• Because it was subject to errors, the Rows Subset heading element has been removed. If there is a strong need for it, I can bring it back in a future release (just let me known by email or on GitHub if you’d like to have it back)
• Under the hood, much has been going on; the lengthier functions have been split into more manageable parts, and several normalizing operations were performed, facilitating maintenance and improving code readability

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 if you find a bug or wish to submit a feature request.

Also, the package grew significantly larger, and maintaining it all by myself is time consuming. If you would like to contribute, please get in touch, I’d greatly appreciate the help.