% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/point_interval.R
\name{point_interval}
\alias{point_interval}
\alias{point_interval.default}
\alias{point_interval.tbl_df}
\alias{point_interval.numeric}
\alias{point_interval.rvar}
\alias{point_interval.distribution}
\alias{qi}
\alias{ll}
\alias{ul}
\alias{hdi}
\alias{Mode}
\alias{Mode.default}
\alias{Mode.rvar}
\alias{Mode.distribution}
\alias{hdci}
\alias{mean_qi}
\alias{median_qi}
\alias{mode_qi}
\alias{mean_ll}
\alias{median_ll}
\alias{mode_ll}
\alias{mean_ul}
\alias{median_ul}
\alias{mode_ul}
\alias{mean_hdi}
\alias{median_hdi}
\alias{mode_hdi}
\alias{mean_hdci}
\alias{median_hdci}
\alias{mode_hdci}
\title{Point and interval summaries for tidy data frames of draws from distributions}
\usage{
point_interval(
  .data,
  ...,
  .width = 0.95,
  .point = median,
  .interval = qi,
  .simple_names = TRUE,
  na.rm = FALSE,
  .exclude = c(".chain", ".iteration", ".draw", ".row"),
  .prob
)

\method{point_interval}{default}(
  .data,
  ...,
  .width = 0.95,
  .point = median,
  .interval = qi,
  .simple_names = TRUE,
  na.rm = FALSE,
  .exclude = c(".chain", ".iteration", ".draw", ".row"),
  .prob
)

\method{point_interval}{tbl_df}(.data, ...)

\method{point_interval}{numeric}(
  .data,
  ...,
  .width = 0.95,
  .point = median,
  .interval = qi,
  .simple_names = FALSE,
  na.rm = FALSE,
  .exclude = c(".chain", ".iteration", ".draw", ".row"),
  .prob
)

\method{point_interval}{rvar}(
  .data,
  ...,
  .width = 0.95,
  .point = median,
  .interval = qi,
  .simple_names = TRUE,
  na.rm = FALSE
)

\method{point_interval}{distribution}(
  .data,
  ...,
  .width = 0.95,
  .point = median,
  .interval = qi,
  .simple_names = TRUE,
  na.rm = FALSE
)

qi(x, .width = 0.95, .prob, na.rm = FALSE)

ll(x, .width = 0.95, na.rm = FALSE)

ul(x, .width = 0.95, na.rm = FALSE)

hdi(
  x,
  .width = 0.95,
  na.rm = FALSE,
  ...,
  density = density_bounded(trim = TRUE),
  n = 4096,
  .prob
)

Mode(x, na.rm = FALSE, ...)

\method{Mode}{default}(
  x,
  na.rm = FALSE,
  ...,
  density = density_bounded(trim = TRUE),
  n = 2001,
  weights = NULL
)

\method{Mode}{rvar}(x, na.rm = FALSE, ...)

\method{Mode}{distribution}(x, na.rm = FALSE, ...)

hdci(x, .width = 0.95, na.rm = FALSE)

mean_qi(.data, ..., .width = 0.95)

median_qi(.data, ..., .width = 0.95)

mode_qi(.data, ..., .width = 0.95)

mean_ll(.data, ..., .width = 0.95)

median_ll(.data, ..., .width = 0.95)

mode_ll(.data, ..., .width = 0.95)

mean_ul(.data, ..., .width = 0.95)

median_ul(.data, ..., .width = 0.95)

mode_ul(.data, ..., .width = 0.95)

mean_hdi(.data, ..., .width = 0.95)

median_hdi(.data, ..., .width = 0.95)

mode_hdi(.data, ..., .width = 0.95)

mean_hdci(.data, ..., .width = 0.95)

median_hdci(.data, ..., .width = 0.95)

mode_hdci(.data, ..., .width = 0.95)
}
\arguments{
\item{.data}{<\link{data.frame} | \link[dplyr:grouped_df]{grouped_df}> Data frame (or grouped
data frame as returned by \code{\link[dplyr:group_by]{dplyr::group_by()}}) that contains draws to summarize.}

\item{...}{<bare \link{language}> Column names or expressions that, when evaluated in the context of
\code{.data}, represent draws to summarize. If this is empty, then by default all
columns that are not group columns and which are not in \code{.exclude} (by default
\code{".chain"}, \code{".iteration"}, \code{".draw"}, and \code{".row"}) will be summarized.
These columns can be numeric, \pkg{distributional} objects, \code{posterior::rvar}s,
or list columns of numeric values to summarise.}

\item{.width}{<\link{numeric}> vector of probabilities to use that determine the widths of
the resulting intervals. If multiple probabilities are provided, multiple rows per
group are generated, each with a different probability interval (and value of the
corresponding \code{.width} column).}

\item{.point}{<\link{function}> Point summary function, which takes a vector and returns a single
value, e.g. \code{\link{mean}}, \code{\link{median}}, or \code{\link{Mode}}.}

\item{.interval}{<\link{function}> Interval function, which takes a vector and a probability
(\code{.width}) and returns a two-element vector representing the lower and upper
bound of an interval; e.g. \code{\link{qi}}, \code{\link{hdi}}}

\item{.simple_names}{<scalar \link{logical}> When \code{TRUE} and only a single column / vector
is to be summarized, use the name \code{.lower} for the lower end of the interval and \code{.upper} for the
upper end. If \code{.data} is a vector and this is \code{TRUE}, this will also set the column name
of the point summary to \code{.value}. When \code{FALSE} and \code{.data} is a data frame,
names the lower and upper intervals for each column \code{x} \code{x.lower} and \code{x.upper}.
When \code{FALSE} and \code{.data} is a vector, uses the naming scheme \code{y}, \code{ymin}
and \code{ymax} (for use with ggplot).}

\item{na.rm}{<scalar \link{logical}> Should \code{NA} values be stripped before the computation proceeds?
If \code{FALSE} (the default), any vectors to be summarized that contain \code{NA} will result in
point and interval summaries equal to \code{NA}.}

\item{.exclude}{<\link{character}> Vector of names of columns to be excluded from summarization
if no column names are specified to be summarized in \code{...}. Default ignores several meta-data column
names used in \pkg{ggdist} and \pkg{tidybayes}.}

\item{.prob}{Deprecated. Use \code{.width} instead.}

\item{x}{<\link{numeric}> Vector to summarize (for interval functions: \code{\link[=qi]{qi()}}, \code{\link[=hdi]{hdi()}}, etc)}

\item{density}{<\link{function} | \link[=character]{string}> For \code{\link[=hdi]{hdi()}} and \code{\link[=Mode]{Mode()}}, the kernel
density estimator to use, either as a function (e.g. \code{\link{density_bounded}}, \code{\link{density_unbounded}})
or as a string giving the suffix to a function that starts with \code{density_} (e.g. \code{"bounded"}
or \code{"unbounded"}). The default, \code{"bounded"}, uses the bounded density estimator of
\code{\link[=density_bounded]{density_bounded()}}, which itself estimates the bounds of the distribution, and tends to
work well on both bounded and unbounded data.}

\item{n}{<scalar \link{numeric}> For \code{\link[=hdi]{hdi()}} and \code{\link[=Mode]{Mode()}}, the number of points to use to estimate
highest-density intervals or modes.}

\item{weights}{<\link{numeric} | \link{NULL}> For \code{\link[=Mode]{Mode()}}, an optional vector, which (if not \code{NULL})
is of the same length as \code{x} and provides weights for each element of \code{x}.}
}
\value{
A data frame containing point summaries and intervals, with at least one column corresponding
to the point summary, one to the lower end of the interval, one to the upper end of the interval, the
width of the interval (\code{.width}), the type of point summary (\code{.point}), and the type of interval (\code{.interval}).
}
\description{
Translates draws from distributions in a (possibly grouped) data frame into point and
interval summaries (or set of point and interval summaries, if there are
multiple groups in a grouped data frame).

Supports \link[=auto_partial]{automatic partial function application}.
}
\details{
If \code{.data} is a data frame, then \code{...} is a list of bare names of
columns (or expressions derived from columns) of \code{.data}, on which
the point and interval summaries are derived. Column expressions are processed
using the tidy evaluation framework (see \code{\link[rlang:eval_tidy]{rlang::eval_tidy()}}).

For a column named \code{x}, the resulting data frame will have a column
named \code{x} containing its point summary. If there is a single
column to be summarized and \code{.simple_names} is \code{TRUE}, the output will
also contain columns \code{.lower} (the lower end of the interval),
\code{.upper} (the upper end of the interval).
Otherwise, for every summarized column \code{x}, the output will contain
\code{x.lower} (the lower end of the interval) and \code{x.upper} (the upper
end of the interval). Finally, the output will have a \code{.width} column
containing the' probability for the interval on each output row.

If \code{.data} includes groups (see e.g. \code{\link[dplyr:group_by]{dplyr::group_by()}}),
the points and intervals are calculated within the groups.

If \code{.data} is a vector, \code{...} is ignored and the result is a
data frame with one row per value of \code{.width} and three columns:
\code{y} (the point summary), \code{ymin} (the lower end of the interval),
\code{ymax} (the upper end of the interval), and \code{.width}, the probability
corresponding to the interval. This behavior allows \code{point_interval}
and its derived functions (like \code{median_qi}, \code{mean_qi}, \code{mode_hdi}, etc)
to be easily used to plot intervals in ggplot stats using methods like
\code{\link[=stat_eye]{stat_eye()}}, \code{\link[=stat_halfeye]{stat_halfeye()}}, or \code{\link[ggplot2:stat_summary]{stat_summary()}}.

\code{median_qi}, \code{mode_hdi}, etc are short forms for
\code{point_interval(..., .point = median, .interval = qi)}, etc.

\code{qi} yields the quantile interval (also known as the percentile interval or
equi-tailed interval) as a 1x2 matrix.

\code{hdi} yields the highest-density interval(s) (also known as the highest posterior
density interval). \strong{Note:} If the distribution is multimodal, \code{hdi} may return multiple
intervals for each probability level (these will be spread over rows). You may wish to use
\code{hdci} (below) instead if you want a single highest-density interval, with the caveat that when
the distribution is multimodal \code{hdci} is not a highest-density interval.

\code{hdci} yields the highest-density \emph{continuous} interval, also known as the shortest
probability interval. \strong{Note:} If the distribution is multimodal, this may not actually
be the highest-density interval (there may be a higher-density
discontinuous interval, which can be found using \code{hdi}).

\code{ll} and \code{ul} yield lower limits and upper limits, respectively (where the opposite
limit is set to either \code{Inf} or \code{-Inf}).
}
\examples{

library(dplyr)
library(ggplot2)

set.seed(123)

rnorm(1000) \%>\%
  median_qi()

data.frame(x = rnorm(1000)) \%>\%
  median_qi(x, .width = c(.50, .80, .95))

data.frame(
    x = rnorm(1000),
    y = rnorm(1000, mean = 2, sd = 2)
  ) \%>\%
  median_qi(x, y)

data.frame(
    x = rnorm(1000),
    group = "a"
  ) \%>\%
  rbind(data.frame(
    x = rnorm(1000, mean = 2, sd = 2),
    group = "b")
  ) \%>\%
  group_by(group) \%>\%
  median_qi(.width = c(.50, .80, .95))

multimodal_draws = data.frame(
    x = c(rnorm(5000, 0, 1), rnorm(2500, 4, 1))
  )

multimodal_draws \%>\%
  mode_hdi(.width = c(.66, .95))

multimodal_draws \%>\%
  ggplot(aes(x = x, y = 0)) +
  stat_halfeye(point_interval = mode_hdi, .width = c(.66, .95))

}
\author{
Matthew Kay
}
