ggdist: parse_dist – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

parse_dist

Parse distribution specifications into columns of a data frame

Description

Parses simple string distribution specifications, like "normal(0, 1)", into two columns of a data frame, suitable for use with stat_dist_slabinterval() and its shortcut stats (like stat_dist_halfeye). This format is output by brms::get_prior, making it particularly useful for visualizing priors from brms models.

Usage

parse_dist(object, ..., dist = ".dist", args = ".args", to_r_names = TRUE)

## Default S3 method:
parse_dist(object, ...)

## S3 method for class 'data.frame'
parse_dist(
  object,
  dist_col,
  ...,
  dist = ".dist",
  args = ".args",
  to_r_names = TRUE
)

## S3 method for class 'character'
parse_dist(object, ..., dist = ".dist", args = ".args", to_r_names = TRUE)

## S3 method for class 'factor'
parse_dist(object, ..., dist = ".dist", args = ".args", to_r_names = TRUE)

## S3 method for class 'brmsprior'
parse_dist(
  object,
  dist_col = prior,
  ...,
  dist = ".dist",
  args = ".args",
  to_r_names = TRUE
)

r_dist_name(dist_name)

Arguments

`object`	A character vector containing distribution specifications or a data frame with a column containing distribution specifications.
`...`	Arguments passed to other implementations of `parse_dist`.
`dist`	The name of the output column to contain the distribution name
`args`	The name of the output column to contain the arguments to the distribution
`to_r_names`	If `TRUE` (the default), certain common aliases for distribution names are automatically translated into names that R can recognize (i.e., names which have functions starting with `r`, `p`, `q`, and `d` representing random number generators, distribution functions, etc. for that distribution), using the `r_dist_name` function. For example, `"normal"` is translated into `"norm"` and `"lognormal"` is translated into `"lnorm"`.
`dist_col`	A bare (unquoted) column or column expression that resolves to a character vector of distribution specifications.
`dist_name`	For `r_dist_name`, a character vector of distribution names to be translated into distribution names R recognizes. Unrecognized names are left as-is.

Details

parse_dist() can be applied to character vectors or to a data frame + bare column name of the column to parse, and returns a data frame with ".dist" and ".args" columns added. parse_dist() uses r_dist_name() to translate distribution names into names recognized by R.

r_dist_name() takes a character vector of names and translates common names into R distribution names. Names are first made into valid R names using make.names(), then translated (ignoring character case, ".", and "_"). Thus, "lognormal", "LogNormal", "log_normal", "log-Normal", and any number of other variants all get translated into "lnorm".

Value

parse_dist returns a data frame containing at least two columns named after the dist and args parameters. If the input is a data frame, the output is a data frame of the same length with those two columns added. If the input is a character vector or factor, the output is a two-column data frame with the same number of rows as the length of the input.
r_dist_name returns a character vector the same length as the input containing translations of the input names into distribution names R can recognize.

Examples

library(dplyr)

# parse dist can operate on strings directly...
parse_dist(c("normal(0,1)", "student_t(3,0,1)"))

# ... or on columns of a data frame, where it adds the
# parsed specs back on as columns
data.frame(prior = c("normal(0,1)", "student_t(3,0,1)")) %>%
  parse_dist(prior)

# parse_dist is particularly useful with the output of brms::prior(),
# which follow the same format as above

ggdist

Visualizations of Distributions and Uncertainty

v2.4.0

GPL (>= 3)

Authors

Matthew Kay [aut, cre]

Initial release

2021-01-03