The following vignettes complement this page:

Recommendations for Using summarytools With Rmarkdown

Introduction to summarytools (Content is almost the same as this page, but has different formatting and shows moe examples)

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 core 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. A summary of those changes can be found near the end of this page.

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

Magick++ Dependency 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.

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.

There is more than one way to do this, but the best approach is to simply pass the data frame object (subsetted if needed) to freq(): (results not shown)

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

We can without fear pass a whole data frame to freq(); it will figure out which variables to ignore (continuous numerical variables, or variables having many, many distinct values).

We’ll now use a sample data frame called tobacco, which is included in summarytools. 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 will ignore non-numerical columns (and display a message to that effect).

descr(iris, style = "rmarkdown")

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 a complete list of available statistics.

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

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.

dfSummary(tobacco, plain.ascii = FALSE, style = "grid", 
          graph.magnif = 0.75, valid.col = FALSE, tmp.img.dir = "/tmp")

While rendering html tables with view() doesn’t require it, here it is essential to specify tmp.img.dir. We’ll explain why further below.

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. The view() function simply acts as a wrapper around print.summarytools(), specifying method = 'viewer'. When used outside RStudio, method falls back to “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 the four core summarytools functions. It returns a list-type object containing as many elements as there are categories in the grouping variable.

Why not just use by()? The reason is that by() creates objects of class “by()”, which have a dedicated print() method conflicting with summarytools’ way of printing list-type objects. Since print.by() can’t be redefined (as of CRAN policies), the sensible solution was to introduce a function that is essentially a clone of by(), except that the objects it creates have the class “stby”, allowing the desired flexibility.

Using the iris data frame, we will now 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

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"): (results not shown)

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. Instead of showing several tables, each having one column, summarytools assembles everything into a single table:

data(tobacco)
with(tobacco, stby(BMI, age.gr, descr, 
                        stats = c("mean", "sd", "min", "med", "max")))

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

The transposed version looks like this:

This is a little trickier – the working syntax 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))

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 just set it globally in a “setup” chunk:

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

        Refer to this page for more 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,          # This is a must in Rmd documents
#            style = "rmarkdown",          # idem
#            dfSummary.varnumbers = FALSE, # This keeps results narrow enough
#            dfSummary.valid.col = FALSE)  # idem
#```
#
# ```{r, echo=FALSE}
# st_css()
# ```

For data frames containing numerous variables, we can use the max.tbl.height argument to wrap the results in a scrollable window having the specified height, in pixels. For instance:

print(dfSummary(tobacco, valid.col = FALSE, graph.magnif = 0.75), 
      max.tbl.height = 300, method = "render")

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, md, or just plain text (txt). The file extension indicates to summarytools what type of file should be generated.

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 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():

(*) Set to FALSE in Shiny apps

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.

Here’s an example in which we override 3 function-specific arguments, and one element of the heading:

(age_stats <- freq(tobacco$age.gr)) 

tobacco$age.gr
Type: Factor

print(age_stats, report.nas = FALSE, totals = FALSE, display.type = FALSE,
      Variable.label = "Age Group")

tobacco$age.gr
Label: Age Group

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 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 global 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)

When generating markdown (as opposed to html) summaries in an .Rmd document, three elements are needed to display proper png graphs:

1 - plain.ascii is FALSE
2 - style is “grid”
3 - tmp.img.dir is defined

Why the third element? Although R makes it really easy to create temporary files and directories, they do have long pathnames, especially on Windows. Combine this with the fact that Pandoc currently determines the final (rendered) column widths by counting characters, including those of pathnames pointing to images. What we get is… some issues of proportion (!).

At this time, there seems to be only one solution around this problem: cut down on characters in pathnames. So instead of this:

+-----------+-------------------------------------------------------------------------+---------+
| Variable  | Graph                                                                   | Valid   |
+===========+=========================================================================+=========+
| gender\   | ![](C:/Users/johnny/AppData/Local/Temp/RtmpYRgetx/file5aa4549a4d71.png) | 978\    |
| [factor]  |                                                                         | (97.8%) |
+----+---------------+----------------------------------------------------------------+---------+

…we aim for this:

+---------------+----------------------+---------+
| Variable      | Graph                | Valid   |
+===============+======================+=========+
| gender\       | ![](/tmp/ds0001.png) | 978\    |
| [factor]      |                      | (97.8%) |
+---------------+----------------------+---------+

Now CRAN policies are really strict when it comes to writing content in the user directories, or anywhere outside R’s temporary zone (for good reasons). So we need to let the users set this location themselves, therefore implicitly consenting to content being written outside R’s temporary zone.

On Mac OS and Linux, using “/tmp” makes a lot of sense: it’s short, and it’s self-cleaning. On Windows, there is no such convenient directory, so we need to pick one – be it absolute (“/tmp”) or relative (“img”, or simply “.”). Two things are to be kept in mind: it needs to be short (5 characters max) and we need to clean it up manually.

It is now possible to switch the language used in the outputs. So far, not too many languages are available (French, Spanish and Russian), but with the community’s involvement, I hope we can gather a good number of them in reasonable time.

To switch languages, simply use

st_options(lang = "fr")

Any function will now produce outputs using that language:

view(freq(iris$Species))

The language used for producing the object is stored within it as an attribute. This is to avoid problems when switching languages between the moment the object is stored, and the moment at which it is printed.

On most Windows systems, it will be necessary to change the LC_CTYPE element of the locale settings if the character set is not included in the current locale. For instance, in order to get good results – or rather, any results at all – with the Russian language in a “latin1” environment, we’ll need to do this:

Sys.setlocale("LC_CTYPE", "russian")
st_options(lang = 'ru')

Then, to go back to default settings:

Sys.setlocale("LC_CTYPE", "")
st_options(lang = "en")

With the new function useTranslations(), you can add your own set of translations. For this, download the template csv file from this page.

After you’re done translating the +/- 70 items, simply call the useTranslations() function, giving it as sole argument the path to the csv file you’ve just created. Note that such custom translations will not persist across R sessions. This means that we should always have handy this csv file if we’re to print objects created with it.

As stated earlier, version 0.9 brings many improvements to summarytools. Here are the key elements:

• Translations
• 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; legacy way of setting options is still supported
  • Several global options were added, with a focus on simplifying Rmarkdown document creation
• 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()
  • Improved number alignment
• 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 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 can 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)
  • max.tbl.height parameter added

• 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

No changes break backward compatibility, but at least one legacy feature will be abandoned in some further release. Namely, the boolean parameter omit.headings, which has been replaced by the more straightforward headings. For now, a message is shown whenever the “old” parameter name is used, encouraging users to switch to the newer one.

For a preview of what’s coming in the next release, see the development branch.

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.