% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ppd-intervals.R
\name{PPD-intervals}
\alias{PPD-intervals}
\alias{ppd_intervals}
\alias{ppd_intervals_grouped}
\alias{ppd_ribbon}
\alias{ppd_ribbon_grouped}
\alias{ppd_intervals_data}
\alias{ppd_ribbon_data}
\title{PPD intervals}
\usage{
ppd_intervals(
  ypred,
  x = NULL,
  ...,
  prob = 0.5,
  prob_outer = 0.9,
  alpha = 0.33,
  size = 1,
  fatten = 2.5
)

ppd_intervals_grouped(
  ypred,
  x = NULL,
  group,
  ...,
  facet_args = list(),
  prob = 0.5,
  prob_outer = 0.9,
  alpha = 0.33,
  size = 1,
  fatten = 2.5
)

ppd_ribbon(
  ypred,
  x = NULL,
  ...,
  prob = 0.5,
  prob_outer = 0.9,
  alpha = 0.33,
  size = 0.25
)

ppd_ribbon_grouped(
  ypred,
  x = NULL,
  group,
  ...,
  facet_args = list(),
  prob = 0.5,
  prob_outer = 0.9,
  alpha = 0.33,
  size = 0.25
)

ppd_intervals_data(
  ypred,
  x = NULL,
  group = NULL,
  ...,
  prob = 0.5,
  prob_outer = 0.9
)

ppd_ribbon_data(
  ypred,
  x = NULL,
  group = NULL,
  ...,
  prob = 0.5,
  prob_outer = 0.9
)
}
\arguments{
\item{ypred}{An \code{S} by \code{N} matrix of draws from the posterior (or prior)
predictive distribution. The number of rows, \code{S}, is the size of the
posterior (or prior) sample used to generate \code{ypred}. The number of
columns, \code{N}, is the number of predicted observations.}

\item{x}{A numeric vector to use as the x-axis
variable. For example, \code{x} could be a predictor variable from a
regression model, a time variable for time-series models, etc. If \code{x}
is missing or \code{NULL} then the observation index is used for the x-axis.}

\item{...}{Currently unused.}

\item{prob}{Values between \code{0} and \code{1} indicating the desired
probability mass to include in the inner and outer intervals. The defaults
are \code{prob=0.5} and \code{prob_outer=0.9}.}

\item{prob_outer}{Values between \code{0} and \code{1} indicating the desired
probability mass to include in the inner and outer intervals. The defaults
are \code{prob=0.5} and \code{prob_outer=0.9}.}

\item{alpha}{Arguments passed to geoms. For ribbon plots \code{alpha}
is passed to \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_ribbon()}} to control the opacity of the outer
ribbon and \code{size} is passed to \code{\link[ggplot2:geom_path]{ggplot2::geom_line()}} to control the size
of the line representing the median prediction (\code{size=0} will remove the
line). For interval plots \code{alpha}, \code{size} and \code{fatten} are passed to
\code{\link[ggplot2:geom_linerange]{ggplot2::geom_pointrange()}} (\code{fatten=0} will remove the point estimates).}

\item{size}{Arguments passed to geoms. For ribbon plots \code{alpha}
is passed to \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_ribbon()}} to control the opacity of the outer
ribbon and \code{size} is passed to \code{\link[ggplot2:geom_path]{ggplot2::geom_line()}} to control the size
of the line representing the median prediction (\code{size=0} will remove the
line). For interval plots \code{alpha}, \code{size} and \code{fatten} are passed to
\code{\link[ggplot2:geom_linerange]{ggplot2::geom_pointrange()}} (\code{fatten=0} will remove the point estimates).}

\item{fatten}{Arguments passed to geoms. For ribbon plots \code{alpha}
is passed to \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_ribbon()}} to control the opacity of the outer
ribbon and \code{size} is passed to \code{\link[ggplot2:geom_path]{ggplot2::geom_line()}} to control the size
of the line representing the median prediction (\code{size=0} will remove the
line). For interval plots \code{alpha}, \code{size} and \code{fatten} are passed to
\code{\link[ggplot2:geom_linerange]{ggplot2::geom_pointrange()}} (\code{fatten=0} will remove the point estimates).}

\item{group}{A grouping variable of the same length as \code{y}.
Will be coerced to \link[base:factor]{factor} if not already a factor.
Each value in \code{group} is interpreted as the group level pertaining
to the corresponding observation.}

\item{facet_args}{A named list of arguments (other than \code{facets}) passed
to \code{\link[ggplot2:facet_wrap]{ggplot2::facet_wrap()}} or \code{\link[ggplot2:facet_grid]{ggplot2::facet_grid()}}
to control faceting. Note: if \code{scales} is not included in \code{facet_args}
then \strong{bayesplot} may use \code{scales="free"} as the default (depending
on the plot) instead of the \strong{ggplot2} default of \code{scales="fixed"}.}
}
\value{
The plotting functions return a ggplot object that can be further
customized using the \strong{ggplot2} package. The functions with suffix
\verb{_data()} return the data that would have been drawn by the plotting
function.
}
\description{
Medians and central interval estimates of posterior or prior predictive
distributions. Each of these functions makes the same plot as the
corresponding \code{\link[=PPC-intervals]{ppc_}} function but without plotting any
observed data \code{y}. The \strong{Plot Descriptions} section at \link{PPC-intervals} has
details on the individual plots.
}
\examples{
color_scheme_set("brightblue")
ypred <- example_yrep_draws()
x <- example_x_data()
group <- example_group_data()

ppd_intervals(ypred[, 1:50])
ppd_intervals(ypred[, 1:50], fatten = .5)
ppd_intervals(ypred[, 1:50], prob_outer = 0.75, size = 2, fatten = 0)

# put a predictor variable on the x-axis
ppd_intervals(ypred[, 1:100], x = x[1:100], size = 1, fatten = 0) +
  ggplot2::labs(y = "Prediction", x = "Some variable of interest")

# with a grouping variable too
ppd_intervals_grouped(
  ypred = ypred[, 1:100],
  x = x[1:100],
  group = group[1:100],
  size = 2,
  fatten = 0,
  facet_args = list(nrow = 2)
)

# even reducing size, ppd_intervals is too cluttered when there are many
# observations included (ppd_ribbon is better)
ppd_intervals(ypred, size = 0.5, fatten = 0.1)
ppd_ribbon(ypred)
ppd_ribbon(ypred, size = 0) # remove line showing median prediction


}
\references{
Gabry, J. , Simpson, D. , Vehtari, A. , Betancourt, M. and
Gelman, A. (2019), Visualization in Bayesian workflow.
\emph{J. R. Stat. Soc. A}, 182: 389-402. doi:10.1111/rssa.12378.
(\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version},
\href{https://arxiv.org/abs/1709.01449}{arXiv preprint},
\href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub})
}
\seealso{
Other PPDs: 
\code{\link{PPD-distributions}},
\code{\link{PPD-overview}},
\code{\link{PPD-test-statistics}}
}
\concept{PPDs}
