Introduction to summarytools

Four Core Functions

The package is built around four main functions:

• freq() – Frequency tables with proportions, cumulative proportions and missing data information
• ctable() – Cross-Tabulations with row, column, or total proportions, as well as marginal totals
• descr() – Descriptive (univariate) statistics for numerical vectors which is more thorough than fivenum() and other similar functions
• dfSummary() – Data frame summaries that facilitate data cleaning and firsthand evaluation

Output Options

All summarytools objects returned by the main functions can be:

• Displayed as plain text in the console (default behavior)
• Redirected to plain text, markdown/rmarkdown or HTML documents
• Rendered to HTML and shown in default Web Browser or in RStudio’s Viewer

Text-based output relies on the pander package, while html output relies on RStudio’s htmltools.

Bare-Bones Example: Frequency Table

To show what default (console) outputs look like, we’ll first generate a frequency table for iris$Species.

freq(iris$Species)

Frequencies   
Species     
Data frame: iris   
Type: Factor (unordered)   

                   Freq   % Valid   % Valid Cum.   % Total   % Total Cum.
---------------- ------ --------- -------------- --------- --------------
          setosa     50     33.33          33.33     33.33          33.33
      versicolor     50     33.33          66.67     33.33          66.67
       virginica     50     33.33         100.00     33.33         100.00
            <NA>      0                               0.00         100.00
           Total    150    100.00         100.00    100.00         100.00

To get familiar with the output styles, try different values for style= and see how results look in the console.

```{r, results='asis'}
library(summarytools)  
freq(tobacco$smoker, style='rmarkdown')  
```

Frequencies

smoker
Data frame: tobacco
Type: Factor (unordered)

Descriptive (Univariate) Statistics

The descr() function accepts both vectors and data frames, in which case it will show statistics for all numerical variables it contains. We’ll use one of the datasets included in the package.

data(exams)
descr(exams[ ,3:5], style='rmarkdown')

descr(exams, style = 'rmarkdown', transpose = TRUE)

with(tobacco, ctable(smoker, diseased, prop = 'n', totals = FALSE))

Cross-Tabulation 
smoker * diseased   
Data Frame: tobacco   
-------- ---------- ----- -----
           diseased   Yes    No
  smoker                       
     Yes              125   173
      No               99   603
-------- ---------- ----- -----

with(tobacco, ctable(smoker, diseased, prop = 'r'))

Cross-Tabulation / Row proportions 
smoker * diseased   
Data Frame: tobacco   
-------- ---------- ------------- ------------- ---------------
           diseased           Yes            No           Total
  smoker                                                       
     Yes              125 (41.9%)   173 (58.1%)    298 (100.0%)
      No               99 (14.1%)   603 (85.9%)    702 (100.0%)
   Total              224 (22.4%)   776 (77.6%)   1000 (100.0%)
-------- ---------- ------------- ------------- ---------------

crosstable <- with(tobacco, ctable(smoker, diseased))
print(crosstable, method='render', footnote = NA)

dfSummary(tobacco, style='grid', plain.ascii = FALSE, graph.col = FALSE)

Data Frame Summary

tobacco
N: 1000

For this one, we can use styles “multiline” (default) or “grid”. We must however specify plain.ascii=FALSE when using markdown, otherwise the rendered results will be problematic.

Redirecting Output

my_summary <- dfSummary(tobacco)  
print(my_summary, file = "tobacco.txt", style = "grid")  # Creates tobacco.txt
my_stats <- descr(tobacco)
print(my_stats, file="tobacco.txt", append = TRUE) # Appends results to tobacco.txt

print(dfSummary(tobacco), method = 'browser')  # Displays results in default Web Browser
print(dfSummary(tobacco), method = 'viewer')   # Displays results in RStudio's Viewer
view(dfSummary(tobacco))                       # Same as line above -- view() is a wrapper function

print(dfSummary(tobacco), file = '~/Documents/tobacco_summary.html')

Using by(), with(), and lapply()

Summarytools functions support the use of by(), with(), and lapply(), at least when used in good measure.

Since objects generated by those native functions have their own class (they are special lists containing summarytools objects), they are not sent to the package’s generic print method automatically. In order to have the best results, the following method is recommended: First, store the object generated by one of the native functions. Then, use view() either with method='pander' to show results in console, or omitting the method argument to see (HTML) results in the Viewer or Browser.

stats <- by(data = exams$geography, INDICES = exams$gender, FUN = descr, style = 'rmarkdown')
view(stats, method = 'pander')

Other Tricks To Try Out

There are many things you can do to build elaborate, fine-tuned reports. Let’s mention a few…

• For HTML reports, footnotes can be customized or removed
• For text reports, captions can be added with the caption= argument
• Text files as well as HTML files can be appended with as many results you need

• Custom CSS can be added – you can specify custom classes for any table you generate For instance:

  view(with(tobacco, ctable(gender, smoker)), 
   report.title = "Summary of the tobacco sample data frame",
    html.table.class = "table table-bordered table-striped table-responsive",
    footnote = "Extended use of Bootstrap classes")

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

When developing, we often use a number functions to obtain an object’s properties. what.is() proposes to lump together the results of such 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 7088 Bytes

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

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

Limitations

• The graph column in dfSummary is not yet supported in rmarkdown
  
• It is not possible to control the heading levels of individual items

Learn more and stay up-to-date

Check the project’s page for more examples; from there you can also submit feature requests or signal problems you might encounter.

To install the package in its development version, use

install.packages('devtools')
library(devtools)
install_github('dcomtois/summarytools', ref='dev-current')