% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/parse_dist.R
\name{parse_dist}
\alias{parse_dist}
\alias{parse_dist.default}
\alias{parse_dist.data.frame}
\alias{parse_dist.character}
\alias{parse_dist.factor}
\alias{parse_dist.brmsprior}
\alias{r_dist_name}
\title{Parse distribution specifications into columns of a data frame}
\usage{
parse_dist(
  object,
  ...,
  dist = ".dist",
  args = ".args",
  dist_obj = ".dist_obj",
  package = NULL,
  to_r_names = TRUE
)

\method{parse_dist}{default}(object, ...)

\method{parse_dist}{data.frame}(
  object,
  dist_col,
  ...,
  dist = ".dist",
  args = ".args",
  dist_obj = ".dist_obj",
  package = NULL,
  lb = "lb",
  ub = "ub",
  to_r_names = TRUE
)

\method{parse_dist}{character}(
  object,
  ...,
  dist = ".dist",
  args = ".args",
  dist_obj = ".dist_obj",
  package = NULL,
  to_r_names = TRUE
)

\method{parse_dist}{factor}(
  object,
  ...,
  dist = ".dist",
  args = ".args",
  dist_obj = ".dist_obj",
  package = NULL,
  to_r_names = TRUE
)

\method{parse_dist}{brmsprior}(
  object,
  dist_col = prior,
  ...,
  dist = ".dist",
  args = ".args",
  dist_obj = ".dist_obj",
  package = NULL,
  to_r_names = TRUE
)

r_dist_name(dist_name)
}
\arguments{
\item{object}{<\link{character} | \link{data.frame}> One of:
\itemize{
\item A character vector containing distribution specifications, like \code{c("normal(0,1)", "exp(1)")}
\item A data frame with a column containing distribution specifications.
}}

\item{...}{Arguments passed to other implementations of \code{parse_dist()}.}

\item{dist}{<\link[=character]{string}> The name of the output column to contain the distribution name.}

\item{args}{<\link[=character]{string}> The name of the output column to contain the arguments to the distribution.}

\item{dist_obj}{<\link[=character]{string}> The name of the output column to contain a \pkg{distributional}
object representing the distribution.}

\item{package}{<\link[=character]{string} | \link{environment} | \link{NULL}> The package or environment to search for
distribution functions in. Passed to \code{\link[distributional:dist_wrap]{distributional::dist_wrap()}}. One of:
\itemize{
\item a string: use the environment for the package with the given name
\item an \link{environment}: use the given environment
\item \code{NULL} (default): use the calling environment
}}

\item{to_r_names}{<scalar \link{logical}> If \code{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 \code{r}, \code{p}, \code{q}, and \code{d} representing random number generators, distribution functions,
etc. for that distribution), using the \code{r_dist_name} function. For example, \code{"normal"} is translated
into \code{"norm"} and \code{"lognormal"} is translated into \code{"lnorm"}.}

\item{dist_col}{<bare \link{language}> Column or column expression of \code{object} that resolves to a
character vector of distribution specifications (when \code{object} is a \code{\link[=data.frame]{data.frame()}}).}

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

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

\item{dist_name}{<\link{character}> For \code{r_dist_name()}, a character vector of distribution names to be
translated into distribution names R recognizes. Unrecognized names are left as-is.}
}
\value{
\itemize{
\item \code{parse_dist} returns a data frame containing at least two columns named after the \code{dist} and \code{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.
\item \code{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.
}
}
\description{
Parses simple string distribution specifications, like \code{"normal(0, 1)"}, into two columns of
a data frame, suitable for use with the \code{dist} and \code{args} aesthetics of \code{\link[=stat_slabinterval]{stat_slabinterval()}}
and its shortcut stats (like \code{\link[=stat_halfeye]{stat_halfeye()}}). This format is output
by \code{brms::get_prior}, making it particularly useful for visualizing priors from
brms models.
}
\details{
\code{\link[=parse_dist]{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 \code{".dist"} and \code{".args"} columns added.
\code{\link[=parse_dist]{parse_dist()}} uses \code{\link[=r_dist_name]{r_dist_name()}} to translate distribution names into names recognized
by R.

\code{\link[=r_dist_name]{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 \code{\link[=make.names]{make.names()}},
then translated (ignoring character case, \code{"."}, and \code{"_"}). Thus, \code{"lognormal"},
\code{"LogNormal"}, \code{"log_normal"}, \code{"log-Normal"}, and any number of other variants
all get translated into \code{"lnorm"}.
}
\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 follows the same format as above

}
\seealso{
See \code{\link[=stat_slabinterval]{stat_slabinterval()}} and its shortcut stats, which can easily make use of
the output of this function using the \code{dist} and \code{args} aesthetics.
}
