Parse distribution specifications into columns of a data frame

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

parse_dist(
  object,
  ...,
  dist = ".dist",
  args = ".args",
  dist_obj = ".dist_obj",
  package = NULL,
  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",
  dist_obj = ".dist_obj",
  package = NULL,
  lb = "lb",
  ub = "ub",
  to_r_names = TRUE
)

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

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

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

r_dist_name(dist_name)

Arguments

object

<character | data.frame> One of:

A character vector containing distribution specifications, like c("normal(0,1)", "exp(1)")
A data frame with a column containing distribution specifications.

...

Arguments passed to other implementations of parse_dist().

dist

<string> The name of the output column to contain the distribution name.

args

<string> The name of the output column to contain the arguments to the distribution.

dist_obj

<string> The name of the output column to contain a distributional object representing the distribution.

package

<string | environment | NULL> The package or environment to search for distribution functions in. Passed to distributional::dist_wrap(). One of:

a string: use the environment for the package with the given name
an environment: use the given environment
NULL (default): use the calling environment

to_r_names

<scalar logical> 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

<bare language> Column or column expression of object that resolves to a character vector of distribution specifications (when object is a data.frame()).

lb

<string> The name of an input column (for data.frame and brms::prior objects) that contains the lower bound of the distribution, which if present will produce a truncated distribution using dist_truncated(). Ignored if object[[lb]] is NULL or if it is NA for the corresponding input row.

ub

<string> The name of an input column (for data.frame and brms::prior objects) that contains the upper bound of the distribution, which if present will produce a truncated distribution using dist_truncated(). Ignored if object[[ub]] is NULL or if it is NA for the corresponding input row.

dist_name

<character> For r_dist_name(), a character vector of distribution names to be translated into distribution names R recognizes. Unrecognized names are left as-is.

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.

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".

Examples


library(dplyr)

# parse dist can operate on strings directly...
parse_dist(c("normal(0,1)", "student_t(3,0,1)"))
#> # A tibble: 2 × 3
#>   .dist     .args               .dist_obj
#>   <chr>     <list>                 <dist>
#> 1 norm      <list [2]>         norm(0, 1)
#> 2 student_t <list [3]> 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)
#>              prior     .dist   .args          .dist_obj
#> 1      normal(0,1)      norm    0, 1         norm(0, 1)
#> 2 student_t(3,0,1) student_t 3, 0, 1 student_t(3, 0, 1)

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

Parse distribution specifications into columns of a data frame

Arguments

Value

Details

See also

Examples