Tools to Quickly and Neatly Summarize Data

Description

summarytools is a collection of functions which neatly and quickly summarize numerical and categorical data. Data frame summaries, frequency tables and cross-tabulations, as well as common descriptive (univariate) statistics can be produced in a straightforward manner. Users with little to no prior R programming experience but who are familiar with popular commercial statistical software such as SAS, SPSS and Stata will feel right at home.

Details

These are the four core functions:

dfSummary

Extensive yet legible data frame summaries.

freq

Frequency tables supporting weights and displaying proportions of valid and of total data, including cumulative proportions.

descr

All common univariate descriptive stats applied to a single vector or to all numerical vectors contained in a data frame.

ctable

Cross-tabulations for pairs of categorical variables – accepting both numerical and character vectors, as well as factors. Choose between Total, Columns or Rows proportions, and optionally display chi-square statistic (with corresponding p-value), odds ratio, as well as risk ratio with flexible confidence intervals.

Choice of output formats:

plain ascii

Ideal when showing results in the R console.

rmarkdown

Perfect for writing short papers or presentations.

html

A format very well integrated in RStudio – but will work with any Web browser. Use the view function to display results directly in RStudio's viewer, or in your preferred Web browser.

Author(s)

Maintainer: Dominic Comtois dominic.comtois@gmail.com

See Also

Useful links:

• https://github.com/dcomtois/summarytools

• Report bugs at https://github.com/dcomtois/summarytools/issues

Delete Temporary Html Files

Description

Delete temporary files created when using generic print method with method='browser' or method='viewer', or when calling view() function.

Usage

cleartmp(all = TRUE, silent = FALSE, verbose = FALSE)

Arguments

Note

Given that all temporary files are deleted automatically when an R session is ended, this function is an overkill in most circumstances. It could however be useful in server-type setups.

Author(s)

Dominic Comtois, dominic.comtois@gmail.com

Cross-Tabulation

Description

Cross-tabulation for a pair of categorical variables with either row, column, or total proportions, as well as marginal sums. Works with numeric, character, as well as factor variables.

Usage

ctable(
  x,
  y,
  prop = st_options("ctable.prop"),
  useNA = "ifany",
  totals = st_options("ctable.totals"),
  style = st_options("style"),
  round.digits = st_options("ctable.round.digits"),
  justify = "right",
  plain.ascii = st_options("plain.ascii"),
  headings = st_options("headings"),
  display.labels = st_options("display.labels"),
  split.tables = Inf,
  na.val = st_options("na.val"),
  rev = "none",
  dnn = c(substitute(x), substitute(y)),
  chisq = FALSE,
  OR = FALSE,
  RR = FALSE,
  weights = NA,
  rescale.weights = FALSE,
  ...
)

Arguments

Details

For risk ratios and odds ratios, the expected structure of the contingency table is as follows (using “No” as reference):

             Outcome
 Exposure      Yes     No
  Yes          a       b
  No           c       d

The rev parameter allows for different structures; use either one of “rows”, “columns”, or “both” to indicate which dimension(s) to reverse in order to match that structure. This does not affect display.

Value

A list containing two matrices, cross_table and proportions. The print method takes care of assembling figures from those matrices into a single table. The returned object has classes “summarytools” and “list”, unless stby is used, in which case we have an object of class “stby”.

Note

Markdown does not fully support multi-header tables; until such support is available, the recommended way to display cross-tables in .Rmd documents is to use 'method=render'. See package vignettes for examples.

Author(s)

Dominic Comtois, dominic.comtois@gmail.com

See Also

table, xtabs

Examples

data("tobacco")
ctable(tobacco$gender, tobacco$smoker)

# Use with() to simplify syntax
with(tobacco, ctable(gender, smoker))

# Show column proportions, without totals
with(tobacco, ctable(smoker, diseased, prop = "c", totals = FALSE))

# Simple 2 x 2 table with odds ratio and risk ratio
with(tobacco, ctable(smoker, diseased, totals = FALSE, headings = FALSE,
                     prop = "r", OR = TRUE, RR = TRUE))

# Grouped cross-tabulations
with(tobacco, stby(data = list(x = smoker, y = diseased), 
                   INDICES = gender, FUN = ctable))


## Not run: 
ct <- ctable(tobacco$gender, tobacco$smoker)

# Show html results in browser
print(ct, method = "browser")

# Save results to html file
print(ct, file = "ct_gender_smoker.html")

# Save results to text file
print(ct, file = "ct_gender_smoker.txt")

## End(Not run)

Modify Keywords Used In Outputs

Description

As an alternative to use_custom_lang, this function allows temporarily modifying the pre-defined terms in the outputs.

Usage

define_keywords(..., ask = TRUE, file = NA)

Arguments

Details

On systems with GUI capabilities, a window will pop-up when calling define_keywords() without any parameters, allowing the modification of the custom column. The changes will be active as long as the package is loaded. When the edit window is closed, a dialog will pop up, prompting the user to save the modified set of keywords in a custom csv language file that can later be used with use_custom_lang.

Here is the full list of modifiable keywords.

title.freq

main heading for freq()

title.freq.weighted

main heading for freq() (weighted)

title.ctable

main heading for ctable()

title.ctable.weighted

main heading ctable() (weighted)

title.ctable.row

indicates what proportions are displayed

title.ctable.col

indicates what proportions are displayed

title.ctable.tot

indicates what proportions are displayed

title.descr

main heading for descr()

title.descr.weighted

main heading for descr() (weighted)

title.dfSummary

main heading for dfSummary()

n

heading item used in descr()

dimensions

heading item used in dfSummary()

duplicates

heading item used in dfSummary()

data.frame

heading item (all functions)

label

heading item (all functions) & column name in dfSummary()

variable

heading item (all functions) & column name in dfSummary()

group

heading item (all functions when used with stby()

by

heading item for descr() when used with stby()

weights

heading item - descr() & freq()

type

heading item for freq()

logical

heading item - type in freq()

character

heading item - type in freq()

numeric

heading item - type in freq()

factor

heading item - type in freq()

factor.ordered

heading item - type in freq()

date

heading item - type in freq()

datetime

heading item - type in freq()

freq

column name in freq()

pct

column name in freq() when report.nas=FALSE

pct.valid.f

column name in freq()

pct.valid.cum

column name in freq()

pct.total

column name in freq()

pct.total.cum

column name in freq()

pct.cum

column name in freq()

valid

column name in freq() and dfSummary() & column content in dfSummary()

invalid

column content in dfSummary() (emails)

total

column grouping in freq(), html version

mean

row name in descr()

sd.long

row name in descr()

sd

cell content (dfSummary)

min

row name in descr()

q1

row name in descr() - 1st quartile

med

row name in descr()

q3

row name in descr() - 3rd quartile

max

row name in descr()

mad

row name in descr() - Median Absolute Deviation

iqr

row name in descr() - Inter-Quartile Range

cv

row name in descr() - Coefficient of Variation

skewness

row name in descr()

se.skewness

row name in descr() - Std. Error for Skewness

kurtosis

row name in descr()

n.valid

row name in descr() - Count of non-missing values

pct.valid

row name in descr() - pct. of non-missing values

no

column name in dfSummary() - position of column in the data frame

stats.values

column name in dfSummary()

freqs.pct.valid

column name in dfSummary()

graph

column name in dfSummary()

missing

column name in dfSummary()

distinct.value

cell content in dfSummary() - singular form

distinct.values

cell content in dfSummary() - plural form

all.nas

cell content in dfSummary() - column has only NAs

all.empty.str

cell content in dfSummary() - column has only empty strings

all.empty.str.nas

cell content in dfSummary() - col. has only NAs and empty strings

no.levels.defined

cell content in dfSummary() - factor has no levels defined

int.sequence

cell content in dfSummary()

rounded

cell content in dfSummary() - note appearing in Stats/Values

others

cell content in dfSummary() - nbr of values not displayed

codes

cell content in dfSummary() - When UPC codes are detected

mode

cell content in dfSummary() - mode = most frequent value

med.short

cell content in dfSummary() - median (shortened term)

start

cell content in dfSummary() - earliest date for date-type cols

end

cell content in dfSummary() - latest date for data-type cols

emails

cell content in dfSummary()

generated.by

footnote content

version

footnote content

date.fmt

footnote - date format (see strptime)

Note

Setting a keyword starting with “title.” to NA or to empty string causes the main title to disappear altogether, which might be desired in some circumstances (when generating a table of contents, for instance).

Examples

## Not run: 
define_keywords(n = "Nb. Obs.")

## End(Not run) 

Univariate Statistics for Numerical Data

Description

Calculates mean, sd, min, Q1\*, median, Q3\*, max, MAD, IQR\*, CV, skewness\*, SE.skewness\*, and kurtosis\* on numerical vectors. (\*) Not available when using sampling weights.

Usage

descr(
  x,
  var = NULL,
  stats = st_options("descr.stats"),
  na.rm = TRUE,
  round.digits = st_options("round.digits"),
  transpose = st_options("descr.transpose"),
  order = "sort",
  style = st_options("style"),
  plain.ascii = st_options("plain.ascii"),
  justify = "r",
  headings = st_options("headings"),
  display.labels = st_options("display.labels"),
  split.tables = 100,
  weights = NULL,
  rescale.weights = FALSE,
  ...
)

Arguments

Details

Since version 1.1, the stats argument can be set in a more flexible way; keywords (all, common, fivenum) can be combined with single statistics, or their “negation”. For instance, using stats = c("all", "-q1", "-q3") would show all except q1 and q3.

For further customization, you could redefine any preset in the following manner: .st_env$descr.stats$common <- c("mean", "sd", "n"). Use caution when modifying .st_env, and reload the package if errors ensue. Changes are temporary and will not persist across R sessions.

Value

An object having classes “matrix” and “summarytools” containing the statistics, with extra attributes useful to other functions/methods.

Author(s)

Dominic Comtois, dominic.comtois@gmail.com

Examples

data("exams")

# All stats (default behavior) for all numerical variables
descr(exams)

# Show only "common" statistics, plus "n"
descr(exams, stats = c("common", "n"))

# Selection of statistics, transposing the results
descr(exams, stats = c("mean", "sd", "min", "max"), transpose = TRUE)

# Rmarkdown-ready
descr(exams, plain.ascii = FALSE, style = "rmarkdown")

# Grouped statistics
data("tobacco")
with(tobacco, stby(BMI, gender, descr, check.nas = FALSE))

# Grouped statistics in tidy table:
tb(with(tobacco, stby(BMI, age.gr, descr, stats = "common")))

## Not run: 
# Show in Viewer (or browser if not in RStudio)
view(descr(exams))

# Save to html file with title
print(descr(exams),
      file = "descr_exams.html", 
      report.title = "BMI by Age Group",
      footnote = "<b>Schoolyear:</b> 2018-2019<br/><b>Semester:</b> Fall")

## End(Not run)

Data frame Summary

Description

Summary of a data frame consisting of: variable names and types, labels if any, factor levels, frequencies and/or numerical summary statistics, barplots/histograms, and valid/missing observation counts and proportions.

Usage

dfSummary(
  x,
  round.digits = 1,
  varnumbers = st_options("dfSummary.varnumbers"),
  class = st_options("dfSummary.class"),
  labels.col = st_options("dfSummary.labels.col"),
  valid.col = st_options("dfSummary.valid.col"),
  na.col = st_options("dfSummary.na.col"),
  graph.col = st_options("dfSummary.graph.col"),
  graph.magnif = st_options("dfSummary.graph.magnif"),
  style = st_options("dfSummary.style"),
  plain.ascii = st_options("plain.ascii"),
  justify = "l",
  na.val = st_options("na.val"),
  col.widths = NA,
  headings = st_options("headings"),
  display.labels = st_options("display.labels"),
  max.distinct.values = 10,
  trim.strings = FALSE,
  max.string.width = 25,
  split.cells = 40,
  split.tables = Inf,
  tmp.img.dir = st_options("tmp.img.dir"),
  keep.grp.vars = FALSE,
  silent = st_options("dfSummary.silent"),
  ...
)

Arguments

Details

The default value plain.ascii = TRUE is intended to facilitate interactive data exploration. When using the package for reporting with rmarkdown, make sure to set this option to FALSE.

When trim.strings is set to TRUE, trimming is done before calculating frequencies, be aware that those will be impacted accordingly.

Specifying tmp.img.dir allows producing results consistent with pandoc styling while also showing png graphs. Due to the fact that in Pandoc, column widths are determined by the length of cell contents even if said content is merely a link to an image, using standard R temporary directory to store the images would cause columns to be exceedingly wide. A shorter path is needed. On Mac OS and Linux, using “/tmp” is a sensible choice, since this directory is cleaned up automatically on a regular basis. On Windows however, there is no such convenient directory, so the user has to choose a directory and cleanup the temporary images manually after the document has been rendered. Providing a relative path such as “img”, omitting “./”, is recommended. The maximum length for this parameter is set to 5 characters. It can be set globally with st_options (e.g.: st_options(tmp.img.dir = ".").

It is possible to control which statistics are shown in the Stats / Values column. For this, see the Details and Examples sections of st_options.

Value

A data frame with additional class summarytools containing as many rows as there are columns in x, with attributes to inform print method. Columns in the output data frame are:

No

Number indicating the order in which column appears in the data frame.

Variable

Name of the variable, along with its class(es).

Label

Label of the variable (if applicable).

Stats / Values

For factors, a list of their values, limited by the max.distinct.values parameter. For character variables, the most common values (in descending frequency order), also limited by max.distinct.values. For numerical variables, common univariate statistics (mean, std. deviation, min, med, max, IQR and CV).

Freqs (% of Valid)

For factors and character variables, the frequencies and proportions of the values listed in the previous column. For numerical vectors, number of distinct values, or frequency of distinct values if their number is not greater than max.distinct.values.

Text Graph

An ASCII histogram for numerical variables, and ASCII barplot for factors and character variables.

Graph

An html encoded graph, either barplot or histogram.

Valid

Number and proportion of valid values.

Missing

Number and proportion of missing (NA and NAN) values.

Note

Several packages provide functions for defining variable labels, summarytools being one of them. Some packages (Hmisc in particular) employ special classes for labelled objects, but summarytools doesn't use nor look for any such classes.

Author(s)

Dominic Comtois, dominic.comtois@gmail.com

See Also

label, print.summarytools

Examples

data("tobacco")
saved_x11_option <- st_options("use.x11")
st_options(use.x11 = FALSE)
dfSummary(tobacco)

# Exclude some of the columns to reduce table width
dfSummary(tobacco, varnumbers = FALSE, valid.col = FALSE)

# Limit number of categories to be displayed for categorical data
dfSummary(tobacco, max.distinct.values = 5, style = "grid")

# Using stby()
stby(tobacco, tobacco$gender, dfSummary)

st_options(use.x11 = saved_x11_option)

## Not run: 

# Show in Viewer or browser - no capital V in view(); stview() is also
# available in case of conflicts with other packages)
view(dfSummary(iris))

# Rmarkdown-ready
dfSummary(tobacco, style = "grid", plain.ascii = FALSE,
          varnumbers = FALSE, valid.col = FALSE, tmp.img.dir = "./img")

# Using group_by()
tobacco %>% group_by(gender) %>% dfSummary()

## End(Not run)

Bulletin de notes (donnees simulees)

Description

Jeu de donnees simulees contenant les notes de 30 etudiants, avec les colonnes suivantes:

• etudiant Nom de l'etudiant.

• sexe Variable categorielle (facteur). Deux niveaux: “Fille”, “Garcon”.

• francais Note en francais (numerique).

• math Note en maths (numerique).

• geographie Note en geographie (numerique).

• histoire Note en histoire (numerique).

• economie Note en economie (numerique).

• anglais Note en anglais (numerique).

Usage

data(examens)

Format

Un data frame de 30 rangees et 8 colonnes

Details

Donnees simulees. Les notes de chaque etudiant sont centrees autour d'une moyenne personnelle et ecart-type randomises.

A copy of this dataset is available in English under the name “exams”.

Report Cards - Simulated Data

Description

A simulated dataset with grades for hypothetical 30 students, with the following variables:

• student Student's name.

• gender Factor with 2 levels: “Girl”, “Boy”.

• french French Grade (numerical).

• math Math Grade (numerical).

• geography Geography Grade (numerical).

• history History Grade (numerical).

• economics Economics Grade (numerical).

• english English Grade (numerical).

Usage

data(exams)

Format

A data frame with 30 rows and 8 variables

Details

All names and grades are simulated. Grades for each student are centered around a personal randomized average and standard deviation.

A copy of this dataset is also available in French under the name “examens”.

format_number

Description

Used internally (not exported) to apply all relevant formatting. It is documented here only because it can be used when setting the dfSummary.custom.1 and dfSummary.custom.1 options.

Usage

format_number(x, round.digits, ...)

Arguments

Examples

## Not run: 
format_number(IQR(column_data, na.rm = TRUE), round.digits)
format_number(IQR(column_data, na.rm = TRUE), decimal.mark = ",")

## End(Not run)

Frequency Tables for Factors and Other Discrete Data

Description

Displays weighted or unweighted frequencies, including <NA> counts and proportions.

Usage

freq(
  x,
  var = NULL,
  round.digits = st_options("round.digits"),
  order = "default",
  style = st_options("style"),
  plain.ascii = st_options("plain.ascii"),
  justify = "default",
  cumul = st_options("freq.cumul"),
  totals = st_options("freq.totals"),
  report.nas = st_options("freq.report.nas"),
  rows = numeric(),
  missing = "",
  na.val = st_options("na.val"),
  display.type = TRUE,
  display.labels = st_options("display.labels"),
  headings = st_options("headings"),
  weights = NA,
  rescale.weights = FALSE,
  ...
)

Arguments

Details

The default plain.ascii = TRUE option is there to make results appear cleaner in the console. To avoid rmarkdown rendering problems, this option is automatically set to FALSE whenever style = "rmarkdown" (unless plain.ascii = TRUE is made explicit in the function call).

Value

A frequency table of class matrix and summarytools with added attributes used by print method.

Note

The data type represents the class in most cases.

Author(s)

Dominic Comtois, dominic.comtois@gmail.com

See Also

table

Examples

data(tobacco)
freq(tobacco$gender)
freq(tobacco$gender, totals = FALSE)

# Ignore NA's, don't show totals, omit headings
freq(tobacco$gender, report.nas = FALSE, totals = FALSE, headings = FALSE)

# In .Rmd documents, use the two following arguments, minimally
freq(tobacco$gender, style="rmarkdown", plain.ascii = FALSE)

# Grouped Frequencies
with(tobacco, stby(diseased, smoker, freq))
(fr_smoker_by_gender <- with(tobacco, stby(smoker, gender, freq)))

# Print html Source
print(fr_smoker_by_gender, method = "render", footnote = NA)

# Order by frequency (+ to -)
freq(tobacco$age.gr, order = "freq")

# Order by frequency (- to +)
freq(tobacco$age.gr, order = "-freq")

# Use the 'rows' argument to display only the 10 most common items
freq(tobacco$age.gr, order = "freq", rows = 1:10)

## Not run: 
# Display rendered html results in RStudio's Viewer
# notice 'view()' is NOT written with capital V
# If working outside RStudio, Web browser is used instead
# A temporary file is stored in temp dir
view(fr_smoker_by_gender)

# Display rendered html results in default Web browser
# A temporary file is stored in temp dir here too
print(fr_smoker_by_gender, method = "browser")

# Write results to text file (.txt, .md, .Rmd) or html file (.html)
print(fr_smoker_by_gender, method = "render", file = "fr_smoker_by_gender.md)
print(fr_smoker_by_gender, method = "render", file = "fr_smoker_by_gender.html)

## End(Not run)

Get or Set Variable or Data Frame Labels

Description

Assigns a label to a vector or data frame, or returns value stored in the object's label attribute (or NA if none exists).

Usage

label(x, all = FALSE, fallback = FALSE, simplify = FALSE)
label(x) <- value
llabel(x, all = TRUE, fallback = FALSE, simplify = FALSE)

Arguments

Details

The wrapper function llabel was named that way to avoid conflicting with base function labels.

Value

A single character vector if all = FALSE (default), or a named list if all = TRUE (named vector when using simplify = TRUE.

Note

Loosely based on Gergely Daróczi's label function.

Author(s)

Dominic Comtois, dominic.comtois@gmail.com,

Extract Data Information From Arguments Passed to Functions (internal)

Description

Using sys.calls(), sys.frames() and match.call(), this utility function extracts and/or infers information about the data being processed. Data frame name, variable names and labels if any, subsetting information, grouping information (when by() is used) are returned by the function which tries various methods to get this information.

Usage

parse_call(
  mc,
  var = "x",
  df_name = TRUE,
  df_label = TRUE,
  var_name = TRUE,
  var_label = TRUE,
  caller = "",
  silent = TRUE
)

Arguments

Value

A list consisting of one or many of the following items

• df_name The data frame name

• df_label The data frame label

• var_name The variable name(s)

• var_label The variable label

• by_var The variable used in by(), when in the call stack

• by_group The group, when by() was used

• by_first Binary indicator used when by() is in the call stack

• by_last Binary indicator

Author(s)

Dominic Comtois, dominic.comtois@gmail.com

Print Method for Objects of Class “list”

Description

Displays a list comprised of summarytools objects created with lapply.

Usage

## S3 method for class 'list'
print(x, method = "pander", file = "", 
  append = FALSE, report.title = NA, table.classes = NA, 
  bootstrap.css = st_options('bootstrap.css'), 
  custom.css = st_options('custom.css'), silent = FALSE, 
  footnote = st_options('footnote'), collapse = 0,
  escape.pipe = st_options('escape.pipe'), ...)

Arguments

Details

This function is there only for cases where the object to be printed was created with lapply, as opposed to the recommended functions for creating grouped results (stby and group_by).

Print Method for Objects of Class “stby”

Description

Displays a list comprised of summarytools objects created with stby.

Usage

## S3 method for class 'stby'
print(x, method = "pander", file = "", 
  append = FALSE, report.title = NA, table.classes = NA, 
  bootstrap.css = st_options('bootstrap.css'), 
  custom.css = st_options('custom.css'), silent = FALSE, 
  footnote = st_options('footnote'), 
  escape.pipe = st_options('escape.pipe'), ...)

Arguments

print.summarytools

Description

Display summarytools objects in the console, in Web Browser or in RStudio's Viewer, or write content to file.

Usage

## S3 method for class 'summarytools'
print(x, method = "pander", file = "",
   append = FALSE, report.title = NA, table.classes = NA,
   bootstrap.css = st_options('bootstrap.css'),
   custom.css = st_options('custom.css'), silent = FALSE,
   footnote = st_options('footnote'), max.tbl.height = Inf,
   collapse = 0, escape.pipe = st_options("escape.pipe"), ...)

Arguments

Details

Ascii and markdown tables are generated using pander.

The following arguments can be used to override formatting attributes stored in the object:

• style

• round.digits (except for dfSummary objects)

• plain.ascii

• justify

• split.tables

• headings

• display.labels

• varnumbers (dfSummary objects only)

• labels.col (dfSummary objects only)

• graph.col (dfSummary objects only)

• valid.col (dfSummary objects only)

• na.col (dfSummary objects only)

• col.widths (dfSummary objects only)

• keep.grp.vars (dfSummary objects only)

• report.nas (freq objects only)

• display.type (freq objects only)

• missing (freq objects only)

• totals (freq and ctable objects)

• caption (freq and ctable objects)

The following arguments can be used to override heading elements:

• Data.frame

• Data.frame.label

• Variable

• Variable.label

• Group

• date

• Weights (freq & descr objects)

• Data.type (freq objects only)

• Row.variable (ctable objects only)

• Col.variable (ctable objects only)

Value

NULL when method="pander"; A file path returned invisibly when method="viewer" or "browser". In the latter case, the file path is also passed to shell.exec (Windows) or system (*nix), causing the document to be opened in default Web browser.

Author(s)

Dominic Comtois, dominic.comtois@gmail.com

References

Summarytools on GitHub List of pander options Bootstrap Cascading Stylesheets

See Also

pander

Examples

## Not run: 
data(tobacco)
view(dfSummary(tobacco), footnote = NA)

## End(Not run)
data(exams)
print(freq(exams$gender), style = 'rmarkdown')
print(descr(exams), headings = FALSE)

Include summarytools' css Into Active Document

Description

Generate the css needed by summarytools in html documents.

Usage

st_css(main = TRUE, global = FALSE, bootstrap = FALSE, style.tag = TRUE, ...)

Arguments

Details

Typically the function is called right after the initial setup chunk of an R markdown document, in a chunk having options echo=FALSE and results="asis".

Value

The css file(s) content silently as a character vector, and prints (using cat()) the content.

Author(s)

Dominic Comtois, dominic.comtois@gmail.com

Query and set summarytools global options

Description

To list all summarytools global options, call without arguments. To display the value of one or several options, enter the name(s) of the option(s) in a character vector as sole argument. To reset all options, use single unnamed argument ‘reset’ or 0.

Usage

st_options(
  option = NULL,
  value = NULL,
  style = "simple",
  plain.ascii = TRUE,
  round.digits = 2,
  headings = TRUE,
  footnote = "default",
  display.labels = TRUE,
  na.val = NULL,
  bootstrap.css = TRUE,
  custom.css = NA_character_,
  escape.pipe = FALSE,
  char.split = 12,
  freq.cumul = TRUE,
  freq.totals = TRUE,
  freq.report.nas = TRUE,
  freq.ignore.threshold = 25,
  freq.silent = FALSE,
  ctable.prop = "r",
  ctable.totals = TRUE,
  ctable.round.digits = 1,
  ctable.silent = FALSE,
  descr.stats = "all",
  descr.transpose = FALSE,
  descr.silent = FALSE,
  dfSummary.style = "multiline",
  dfSummary.varnumbers = TRUE,
  dfSummary.class = TRUE,
  dfSummary.labels.col = TRUE,
  dfSummary.valid.col = TRUE,
  dfSummary.na.col = TRUE,
  dfSummary.graph.col = TRUE,
  dfSummary.graph.magnif = 1,
  dfSummary.silent = FALSE,
  dfSummary.custom.1 = expression(paste(paste0(trs("iqr"), " (", trs("cv"), ") : "),
    format_number(IQR(column_data, na.rm = TRUE), round.digits), " (",
    format_number(sd(column_data, na.rm = TRUE)/mean(column_data, na.rm = TRUE),
    round.digits), ")", collapse = "", sep = "")),
  dfSummary.custom.2 = NA,
  tmp.img.dir = NA_character_,
  subtitle.emphasis = TRUE,
  lang = "en",
  use.x11 = TRUE
)

Arguments

Details

The dfSummary.custom.1 and dfSummary.custom.2 options must be defined as expressions. In the expression, use the culumn_data variable name to refer to data. Assume the type to be numerical (real or integer). The expression must paste together both the labels (short name for the statistic(s) being displayed) and the statistics themselves. Although round can be used, a better alternative is to call the internal format_number, which uses format to apply all relevant formatting that is active within the call to dfSummary. For keywords having a translated term, the trs() internal function can be used (see Examples).

Note

To learn more about summarytools options, see vignette("introduction", "summarytools").

Examples

# show all summarytools global options
st_options()

# show a specific option
st_options("round.digits")

# show two (or more) options
st_options(c("plain.ascii", "style", "footnote"))

## Not run: 
# set one option
st_options(plain.ascii = FALSE)

# set one options, legacy way
st_options("plain.ascii", FALSE)

# set several options
st_options(plain.ascii = FALSE,
           style       = "rmarkdown",
           footnote    = NA)

# reset all
st_options('reset')
# ... or
st_options(0)

# Define custom dfSummary stats
st_options(dfSummary.custom.1 = expression(
  paste(
    "Q1 - Q3 :",
    format_number(
      quantile(column_data, probs = .25, type = 2, 
               names = FALSE, na.rm = TRUE), round.digits
    ),
    "-",
    format_number(
      quantile(column_data, probs = .75, type = 2, 
               names = FALSE, na.rm = TRUE), round.digits
    ),
    collapse = ""
  )
))

dfSummary(iris)

# Set back to default value
st_options(dfSummary.custom.1 = "default")

## End(Not run)
 

Obtain Grouped Statistics With summarytools

Description

An adaptation base R's by function, designed to optimize the results' display.

Usage

stby(data, INDICES, FUN, ..., useNA = FALSE)

Arguments

Details

When the grouping variable(s) contain NA values, the base::by function (as well as summarytools versions prior to 1.1.0) ignores corresponding groups. Version 1.1.0 allows setting useNA = TRUE to make new groups using NA values on the grouping variable(s), just as dplyr::group_by does.

When NA values are detected and useNA = FALSE, a message is displayed; to disable this message, set check.nas = FALSE.

Value

An object of classes “list” and “summarytools”, giving results for each subset.

See Also

by, group_by

Examples

data("tobacco")
with(tobacco, stby(data = BMI, INDICES = gender, FUN = descr,
                   check.nas = FALSE))
with(tobacco, stby(data = smoker, INDICES = gender, freq, useNA = TRUE))
with(tobacco, stby(data = list(x = smoker, y = diseased),
                   INDICES = gender, FUN = ctable, useNA = TRUE))
                   

Usage du tabac et etat de sante (donnees simulees)

Description

Jeu de donnees simulees de 1000 sujets, avec les colonnes suivantes:

• sexe Variable categorielle (facteur), 2 niveaux: “F” et “M”. Environ 500 chacun.

• age Numerique.

• age.gr Groupe d'age - variable categorielle, 4 niveaux.

• IMC Indice de masse corporelle (numerique).

• fumeur Variable categorielle, 2 niveaux (“Oui” / “Non”).

• cigs.par.jour Nombre de cigarettes fumees par jour (numerique).

• malade Variable categorielle, 2 niveaux (“Oui” / “Non”).

• maladie Champs texte.

• ponderation Poids echantillonal (numerique).

Usage

data(tabagisme)

Format

Un data frame de 1000 rangees et 9 colonnes

Details

Note sur la simulation des donnees: la probabilite pour un sujet de tomber dans la categorie “malade” est basee sur une fonction arbitraire faisant intervenir l'age, l'IMC et le nombre de cigarettes fumees par jour.

A copy of this dataset is available in English under the name “tobacco”.

Convert Summarytools Objects into Tibbles

Description

Make a tidy dataset out of freq() or descr() outputs

Usage

tb(
  x,
  order = 1,
  drop.var.col = FALSE,
  recalculate = TRUE,
  fct.to.chr = FALSE,
  ...
)

Arguments

Details

stby, which is based on and by, initially make the first variable vary, keeping the other(s) constant. On the other hand, group_by initially keeps the first grouping variable(s) constant, making the last one vary. This will impact the ordering of the rows (and as a result, the cumulative percent columns, if present).

Also, keep in mind that while group_by shows NA groups by default, useNA = TRUE must be used to achieve the same results with stby.

Value

A tibble which is constructed following the tidy principles.

Examples

tb(freq(iris$Species))
tb(descr(iris, stats = "common"))

data("tobacco")
tb(stby(tobacco, tobacco$gender, descr, stats = "fivenum",check.nas = FALSE), 
   order=3)
tb(stby(tobacco, tobacco$gender, descr, stats = "common", useNA = TRUE))

# Compare stby() and group_by() groups' ordering
tb(with(tobacco, stby(diseased, list(gender, smoker), freq, useNA = TRUE)))

## Not run: 
tobacco |> dplyr::group_by(gender, smoker) |> freq(diseased) |> tb()

## End(Not run)

Tobacco Use and Health - Simulated Dataset

Description

A simulated datasets of 1,000 subjects, with the following variables:

Usage

data(tobacco)

Format

A data frame with 1000 rows and 9 variables

Details

• gender Factor with 2 levels: “F” and “M”, having roughly 500 of each.

• age Numerical.

• age.gr Factor with 4 age categories.

• BMI Body Mass Index (numerical).

• smoker Factor (“Yes” / “No”).

• cigs.per.day Number of cigarettes smoked per day (numerical).

• diseased Factor (“Yes” / “No”).

• disease Character.

• samp.wgts Sampling weights (numerical).

A note on simulation: probability for an individual to fall into category “diseased” is based on an arbitrary function involving age, BMI and number of cigarettes per day.

A copy of this dataset is also available in French under the name “tabagisme”.

Clear Variable and Data Frame Label(s)

Description

Returns the object with all labels removed. The “label” attribute as well as the “labelled” class (used by Hmisc and labelled) are cleared.

Usage

unlabel(x)

Arguments

Author(s)

Dominic Comtois, dominic.comtois@gmail.com,

See Also

label

Import and use a custom language

Description

If your language is not available or if you wish to customize the outputs' language to suit your preference, you can set up a translations file (see details) and import it with this function.

Usage

use_custom_lang(file)

Arguments

Details

To build the translations file, copy the language_template.csv file located in the installed package's includes directory and fill out the ‘custom’ column using a text editor, leaving column titles unchanged. The file must also retain its UTF-8 encoding.

view

Description

Visualize results in RStudio's Viewer or in Web Browser

Usage

view(x, method = "viewer", file = "", append = FALSE,
  report.title = NA, table.classes = NA, 
  bootstrap.css = st_options("bootstrap.css"), 
  custom.css = st_options("custom.css"), silent = FALSE, 
  footnote = st_options("footnote"),
  max.tbl.height = Inf,
  collapse = 0,
  escape.pipe = st_options("escape.pipe"), ...)

Arguments

Details

Creates html outputs and displays them in RStudio's viewer, in a browser, or renders the html code in R markdown documents.

For objects of class “summarytools”, this function is simply a wrapper around print.summarytools with method = "viewer".

Objects of class “by”, “stby”, or “list” are dispatched to the present function, as it can manage multiple objects, whereas print.summarytools can only manage one object at a time.

Obtain Extended Properties of Objects

Description

Combination of most common “macro-level” functions that describe an object.

Usage

what.is(x, ...)

Arguments

Details

An alternative to calling in turn class, typeof, dim, and so on. A call to this function will readily give all this information at once.

Value

A list with following elements:

properties

A data frame with the class(es), type, mode and storage mode of the object as well as the dim, length and object.size.

attributes.lengths

A named character vector giving all attributes (c.f. “names”, “row.names”, “class”, “dim”, and so forth) along with their length.

extensive.is

A character vector of all the identifier functions. (starting with “is.”) that yield TRUE when used with x as argument.

function.type

When x is a function, results of ftype are added.

Author(s)

Dominic Comtois, dominic.comtois@gmail.com

See Also

class, typeof, mode, storage.mode, dim, length, is.object, otype, object.size, ftype

Examples

what.is(1)
what.is(NaN)
what.is(iris3)
what.is(print)
what.is(what.is)

Remove Attributes to Get a Simplified Object

Description

Get rid of summarytools-specific attributes to get a simple data structure (matrix, array, ...), which can be easily manipulated.

Usage

zap_attr(x, except = c("dim", "dimnames"))

Arguments

Details

If the object contains grouped results:

• The inner objects will lose their attributes

• The “stby” class will be replaced with “by”

• The “dim” and “dimnames” attributes will be set to available relevant values, but expect slight differences between objects created with stby() vs group_by().

Examples

data(tobacco)
zap_attr(descr(tobacco))
zap_attr(freq(tobacco$gender))