Query and set summarytools global options

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

option

option(s) name(s) to query (optional). Can be a single string or a vector of strings to query multiple values.

value

The value you wish to assign to the option specified in the first argument. This is for backward-compatibility, as all options can now be set via their own parameter. That is, instead of st_options('plain.ascii', FALSE)), use st_options(plain.ascii = FALSE).

style

Character. One of “simple” (default), “rmarkdown”, or “grid”. Does not apply to dfSummary.

plain.ascii

Logical. pander argument; when TRUE, no markup characters will be used (useful when printing to console). TRUE by default, but when style = 'rmarkdown', it is automatically set to FALSE. To override this behavior, plain.ascii = TRUE must be specified in the function call.

round.digits

Numeric. Defaults to 2.

headings

Logical. Set to FALSE to remove all headings from outputs. Only the tables will be printed out, except when by or lapply are used. In that case, the variable or the group will still appear before each table. TRUE by default.

footnote

Character. When the default value “default” is used, the package name & version, as well as the R version number are displayed below html outputs. Set no NA to omit the footnote, or provide a custom string. Applies only to html outputs.

display.labels

Logical. TRUE by default. Set to FALSE to omit data frame and variable labels in the headings section.

na.val

Character. For factors and character vectors, consider this value as NA. Ignored if there are actual NA values or if it matches no value / factor level in the data. NULL by default.

bootstrap.css

Logical. Specifies whether to include Bootstrap css in html reports' head section. Defaults to TRUE. Set to FALSE when using the “render” method inside a shiny app to avoid interacting with the app's layout.

custom.css

Character. Path to an additional, user-provided, CSS file. NA by default.

escape.pipe

Logical. Set to TRUE if Pandoc conversion is your goal and you have unsatisfying results with grid or multiline tables. FALSE by default.

char.split

Numeric. Maximum number of characters allowed in a column heading for descr and ctable html outputs. Any variable name having more than this number of characters will be split on two or more lines. Defaults to 12.

freq.cumul

Logical. Corresponds to the cumul parameter of freq. TRUE by default.

freq.totals

Logical. Corresponds to the totals parameter of freq. TRUE by default.

freq.report.nas

Logical. Corresponds to the display.nas parameter of freq. TRUE by default.

freq.ignore.threshold

Numeric. Number of distinct values above which numerical variables are ignored when calling freq with a whole data frame as main argument. Defaults to 25.

freq.silent

Logical. Hide console messages. FALSE by default.

ctable.prop

Character. Corresponds to the prop parameter of ctable. Defaults to “r” (row).

ctable.totals

Logical. Corresponds to the totals parameter of ctable. TRUE by default.

ctable.round.digits

Numeric. Defaults to 1.

ctable.silent

Logical. Hide console messages. FALSE by default.

descr.stats

Character. Corresponds to the stats parameter of descr. Defaults to “all”.

descr.transpose

Logical. Corresponds to the transpose parameter of descr. FALSE by default.

descr.silent

Logical. Hide console messages. FALSE by default.

dfSummary.style

Character. “multiline” by default. Set to “grid” for R Markdown documents.

dfSummary.varnumbers

Logical. In dfSummary, display variable numbers in the first column. Defaults to TRUE.

dfSummary.class

Logical. Show data classes in Name column. TRUE by default. variable numbers in the first column. Defaults to TRUE.

dfSummary.labels.col

Logical. In dfSummary, display variable labels Defaults to TRUE.

dfSummary.valid.col

Logical. In dfSummary, include column indicating count and proportion of valid (non-missing). TRUE by default.

dfSummary.na.col

Logical. In dfSummary, include column indicating count and proportion of missing (NA) values. TRUE by default.

dfSummary.graph.col

Logical. Display barplots / histograms column in dfSummary html reports. TRUE by default.

dfSummary.graph.magnif

Numeric. Magnification factor, useful if dfSummary graphs show up too large (then use a value between 0 and 1) or too small (use a value > 1). Must be positive. Default to 1.

dfSummary.silent

Logical. Hide console messages. FALSE by default.

dfSummary.custom.1

Expression. First of two optional expressions which once evaluated will populate lines 3+ of the `Stats / Values` cell when column data is numerical and has more distinct values than allowed by the max.distinct.values parameter. By default, it contains the expression which generates the `IQR (CV) : ...` line. To reset it back to this default value, use st_options(dfSummary.custom.1 = "default"). See Details and Examples sections for more.

dfSummary.custom.2

Expression. Second the two optional expressions which once evaluated will populate lines 3+ of the `Stats / Values` cell when the column data is numerical and has more distinct values than allowed by the `max.distinct.values` parameter. NA by default. See Details and Examples sections for more.

tmp.img.dir

Character. Directory used to store temporary images. See Details section of dfSummary. NA by default.

subtitle.emphasis

Logical. Controls the formatting of the “subtitle” (the data frame or variable name, depending on context. When TRUE (default), “h4” is used, while with FALSE, “bold” / “strong” is used. Hence the default value gives it stronger emphasis.

lang

Character. A 2-letter code for the language to use in the produced outputs. Currently available languages are: ‘en’, ‘es’, ‘fr’, ‘pt’, ‘ru’, and ‘tr’.

use.x11

Logical. TRUE by default. In console-only environments, setting this to FALSE will prevent errors occurring when dfSummary tries to generate html “Base64-encoded” graphs.

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()
#> $style
#> [1] "simple"
#> 
#> $plain.ascii
#> [1] TRUE
#> 
#> $round.digits
#> [1] 2
#> 
#> $headings
#> [1] TRUE
#> 
#> $footnote
#> [1] "default"
#> 
#> $display.labels
#> [1] TRUE
#> 
#> $na.val
#> NULL
#> 
#> $bootstrap.css
#> [1] TRUE
#> 
#> $custom.css
#> [1] NA
#> 
#> $escape.pipe
#> [1] FALSE
#> 
#> $char.split
#> [1] 12
#> 
#> $freq.cumul
#> [1] TRUE
#> 
#> $freq.totals
#> [1] TRUE
#> 
#> $freq.report.nas
#> [1] TRUE
#> 
#> $freq.ignore.threshold
#> [1] 25
#> 
#> $freq.silent
#> [1] FALSE
#> 
#> $ctable.prop
#> [1] "r"
#> 
#> $ctable.totals
#> [1] TRUE
#> 
#> $ctable.round.digits
#> [1] 1
#> 
#> $ctable.silent
#> [1] FALSE
#> 
#> $descr.stats
#> [1] "all"
#> 
#> $descr.transpose
#> [1] FALSE
#> 
#> $descr.silent
#> [1] FALSE
#> 
#> $dfSummary.style
#> [1] "multiline"
#> 
#> $dfSummary.varnumbers
#> [1] TRUE
#> 
#> $dfSummary.class
#> [1] TRUE
#> 
#> $dfSummary.labels.col
#> [1] TRUE
#> 
#> $dfSummary.graph.col
#> [1] TRUE
#> 
#> $dfSummary.valid.col
#> [1] TRUE
#> 
#> $dfSummary.na.col
#> [1] TRUE
#> 
#> $dfSummary.graph.magnif
#> [1] 1
#> 
#> $dfSummary.silent
#> [1] 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
#> [1] NA
#> 
#> $tmp.img.dir
#> [1] NA
#> 
#> $subtitle.emphasis
#> [1] TRUE
#> 
#> $lang
#> [1] "en"
#> 
#> $use.x11
#> [1] TRUE
#> 

# show a specific option
st_options("round.digits")
#> [1] 2

# show two (or more) options
st_options(c("plain.ascii", "style", "footnote"))
#> $plain.ascii
#> [1] TRUE
#> 
#> $style
#> [1] "simple"
#> 
#> $footnote
#> [1] "default"
#> 

if (FALSE) { # \dontrun{
# 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")
} # }