st_options: Query and set summarytools global options

In summarytools: Tools to Quickly and Neatly Summarize Data

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,
  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,
  descr.stats = "all",
  descr.transpose = FALSE,
  descr.silent = FALSE,
  dfSummary.style = "multiline",
  dfSummary.varnumbers = 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.
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.
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.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()

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

summarytools documentation built on May 20, 2022, 9:06 a.m.