Nothing
#' Graphical posterior predictive checking
#'
#' @name PPC-overview
#' @aliases PPC
#' @family PPCs
#'
#' @description The **bayesplot** PPC module provides various plotting functions
#' for creating graphical displays comparing observed data to simulated data
#' from the posterior (or prior) predictive distribution. See the sections
#' below for a brief discussion of the ideas behind posterior predictive
#' checking, an overview of the available PPC plots, and tips on providing an
#' interface to **bayesplot** from another package.
#'
#' For plots of posterior (or prior) predictive distributions that do _not_
#' include observed data see [PPD-overview] instead.
#'
#' @details The idea behind posterior predictive checking is simple: if a model
#' is a good fit then we should be able to use it to generate data that looks
#' a lot like the data we observed.
#'
#' \subsection{Posterior predictive distribution}{
#' To generate the data used for posterior predictive checks we simulate from
#' the *posterior predictive distribution*. The posterior predictive
#' distribution is the distribution of the outcome variable implied by a model
#' after using the observed data \eqn{y} (a vector of outcome values), and
#' typically predictors \eqn{X}, to update our beliefs about the unknown
#' parameters \eqn{\theta} in the model. For each draw of the parameters
#' \eqn{\theta} from the posterior distribution
#' \eqn{p(\theta \,|\, y, X)}{p(\theta | y, X)}
#' we generate an entire vector of outcomes. The result is
#' an \eqn{S \times N}{S x N} matrix of simulations, where \eqn{S} is the the
#' size of the posterior sample (number of draws from the posterior
#' distribution) and \eqn{N} is the number of data points in \eqn{y}. That is,
#' each row of the matrix is an individual "replicated" dataset of \eqn{N}
#' observations.
#' }
#' \subsection{Notation}{
#' When simulating from the posterior predictive distribution we can use either
#' the same values of the predictors \eqn{X} that we used when fitting the model
#' or new observations of those predictors. When we use the same values of
#' \eqn{X} we denote the resulting simulations by \eqn{y^{rep}}{yrep} as they
#' can be thought of as *replications* of the outcome \eqn{y} rather than
#' predictions for future observations. This corresponds to the notation from
#' Gelman et. al. (2013) and is the notation used throughout the documentation
#' for this package.
#' }
#' \subsection{Graphical posterior predictive checking}{
#' Using the datasets \eqn{y^{rep}}{yrep} drawn from the posterior predictive
#' distribution, the functions in the **bayesplot** package produce various
#' graphical displays comparing the observed data \eqn{y} to the replications.
#' For a more thorough discussion of posterior predictive checking see
#' Chapter 6 of Gelman et. al. (2013).
#' }
#' \subsection{Prior predictive checking}{
#' To use **bayesplot** for *prior* predictive checks you can simply use draws
#' from the prior predictive distribution instead of the posterior predictive
#' distribution. See Gabry et al. (2019) for more on prior predictive checking
#' and when it is reasonable to compare the prior predictive distribution to the
#' observed data. If you want to avoid using the observed data for prior
#' predictive checks then you can use the **bayesplot** [PPD] plots instead,
#' which do not take a `y` argument, or you can use the PPC plots but provide
#' plausible or implausible `y` values that you want to compare to the prior
#' predictive realizations.
#' }
#'
#' @section PPC plotting functions: The plotting functions for prior and
#' posterior predictive checking all have the prefix `ppc_` and all require
#' the arguments `y`, a vector of observations, and `yrep`, a matrix of
#' replications (in-sample predictions). The plots are organized into several
#' categories, each with its own documentation:
#' * [PPC-distributions]: Histograms, kernel density estimates, boxplots, and
#' other plots comparing the empirical distribution of data `y` to the
#' distributions of individual simulated datasets (rows) in `yrep`.
#'
#' * [PPC-test-statistics]: The distribution of a statistic, or a pair of
#' statistics, over the simulated datasets (rows) in `yrep` compared to value of
#' the statistic(s) computed from `y`.
#'
#' * [PPC-intervals]: Interval estimates of `yrep` with `y`
#' overlaid. The x-axis variable can be optionally specified by the user
#' (e.g. to plot against a predictor variable or over time).
#'
#' * [PPC-errors]: Plots of predictive errors (`y - yrep`) computed from `y` and
#' each of the simulated datasets (rows) in `yrep`. For binomial models binned
#' error plots are also available.
#'
#' * [PPC-scatterplots]: Scatterplots (and similar visualizations) of the data
#' `y` vs. individual simulated datasets (rows) in `yrep`, or vs. the average
#' value of the distributions of each data point (columns) in `yrep`.
#'
#' * [PPC-discrete]: PPC functions that can only be used if `y` and `yrep` are
#' discrete. For example, rootograms for count outcomes and bar plots for
#' ordinal, categorical, and multinomial outcomes.
#'
#' * [PPC-loo]: PPC functions for predictive checks based on (approximate)
#' leave-one-out (LOO) cross-validation.
#''
#' * [PPC-censoring]: PPC functions comparing the empirical
#' distribution of censored data `y` to the distributions of individual
#' simulated datasets (rows) in `yrep`.
#'
#' @section Providing an interface for predictive checking from another package:
#'
#' In addition to the various plotting functions, the **bayesplot** package
#' provides the S3 generic [pp_check()]. Authors of \R packages for
#' Bayesian inference are encouraged to define `pp_check()` methods for the
#' fitted model objects created by their packages. See the package vignettes for
#' more details and a simple example, and see the **rstanarm** and **brms**
#' packages for full examples of `pp_check()` methods.
#'
#' @template reference-vis-paper
#' @templateVar bdaRef (Ch. 6)
#' @template reference-bda
#'
NULL
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.