R: Query and set summarytools global options

st_options {summarytools}

R Documentation

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)

[Package summarytools version 1.0.1 Index]