% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stat-smooth-draws.R
\docType{data}
\name{stat_smooth_draws}
\alias{stat_smooth_draws}
\alias{StatSmoothdraws}
\title{Generate outcome draws from a smooth fit}
\usage{
stat_smooth_draws(mapping = NULL, times = 10, data = NULL,
  geom = "smooth", position = "identity", ..., formula = y ~ s(x, bs
  = "cs"), n = 80, fullrange = FALSE, gam.args = list(method =
  "REML"), na.rm = FALSE, show.legend = NA, inherit.aes = TRUE)
}
\arguments{
\item{mapping}{Set of aesthetic mappings created by \code{\link[=aes]{aes()}} or
\code{\link[=aes_]{aes_()}}. If specified and \code{inherit.aes = TRUE} (the
default), it is combined with the default mapping at the top level of the
plot. You must supply \code{mapping} if there is no plot mapping.}

\item{times}{Number of outcomes to draw.}

\item{data}{The data to be displayed in this layer. There are three
options:

If \code{NULL}, the default, the data is inherited from the plot
data as specified in the call to \code{\link[=ggplot]{ggplot()}}.

A \code{data.frame}, or other object, will override the plot
data. All objects will be fortified to produce a data frame. See
\code{\link[=fortify]{fortify()}} for which variables will be created.

A \code{function} will be called with a single argument,
the plot data. The return value must be a \code{data.frame}, and
will be used as the layer data.}

\item{geom}{Use to override the default connection between
\code{geom_smooth()} and \code{stat_smooth()}.}

\item{position}{Position adjustment, either as a string, or the result of
a call to a position adjustment function.}

\item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}. These are
often aesthetics, used to set an aesthetic to a fixed value, like
\code{colour = "red"} or \code{size = 3}. They may also be parameters
to the paired geom/stat.}

\item{formula}{Formula to use in smoothing function. Default is
a cubic spline, \code{y ~ s(x, bs = "cs")}. To generate a linear fit,
set \code{formula = y ~ x}.}

\item{n}{Number of points at which to evaluate smoother.}

\item{fullrange}{Should the fit span the full range of the plot, or just
the data?}

\item{gam.args}{List of additional arguments passed on to the
GAM call.}

\item{na.rm}{If \code{FALSE}, the default, missing values are removed with
a warning. If \code{TRUE}, missing values are silently removed.}

\item{show.legend}{logical. Should this layer be included in the legends?
\code{NA}, the default, includes if any aesthetics are mapped.
\code{FALSE} never includes, and \code{TRUE} always includes.
It can also be a named logical vector to finely select the aesthetics to
display.}

\item{inherit.aes}{If \code{FALSE}, overrides the default aesthetics,
rather than combining with them. This is most useful for helper functions
that define both data and aesthetics and shouldn't inherit behaviour from
the default plot specification, e.g. \code{\link[=borders]{borders()}}.}
}
\description{
Generate outcome draws from a smooth fit. This stat is similar to \code{\link[=stat_smooth]{stat_smooth()}},
but there are a few important differences. First, there is no \code{method} argument.
Only smooth fits fitted via \code{\link[mgcv:gam]{mgcv::gam()}} are currently supported. If you want a
linear fit, set a linear formula via \code{formula = y ~ x}. Second, there is no \code{se}
argument. This stat cannot draw confidence bands. See \code{\link[=confidence_band]{confidence_band()}} for a
workaround if you want to add confidence bands. Internally, the stat uses the
function \code{\link[=sample_outcomes]{sample_outcomes()}} to calculate outcomes.
}
\details{
This stat fits the gam with Restricted Maximum Likelihood (REML) and uses the
smoothing parameter uncertainty corrected covariance matrix to generate outcomes
(\code{unconditional = TRUE} in \code{\link[=sample_outcomes]{sample_outcomes()}}). If you choose a different gam
fitting method the stat sets \code{unconditional = FALSE}.

Note that for static plots, you will generally have to set the \code{group}
aesthetic appropriately (e.g., \code{aes(group = stat(.draw))}). However, for
animated plots you will normally not want to set the group aesthetic in
this way. To enable animations by default, \code{stat_smooth_draws()} does not
set a group aesthetic. See examples for further details.
}
\examples{
library(ggplot2)

# static plots, need to set group aesthetic manually
ggplot(mtcars, aes(hp, mpg)) +
  geom_point() +
  stat_smooth_draws(aes(group = stat(.draw)), size = 0.5) +
  theme_bw()

# if we want to group by multiple variables, we have to use their
# mapped name (here, `colour` instead of `Species`) because we're
# creating the groups after after initial data mapping
ggplot(iris, aes(Sepal.Length, Sepal.Width, colour = Species)) +
  geom_point() +
  stat_smooth_draws(
    formula = y ~ x,
    aes(group = interaction(stat(.draw), colour)),
    size = 0.5
  ) +
  theme_bw()

\dontrun{

# animated plots
library(gganimate)

ggplot(mtcars, aes(hp, mpg)) +
  geom_point() +
  stat_smooth_draws(size = 0.5) +
  transition_states(stat(.draw), 1, 2)

ggplot(iris, aes(Sepal.Length, Sepal.Width, colour = Species)) +
  geom_point() +
  stat_smooth_draws(formula = y ~ x, times = 20, size = 0.5) +
  transition_states(stat(.draw), 1, 2)
}
}
\keyword{datasets}
