\HeaderA{simulate}{Simulate Responses}{simulate}
\keyword{models}{simulate}
\keyword{datagen}{simulate}
\begin{Description}\relax
Simulate one or more response vectors from the theoretical distribution
corresponding to a fitted model object.
\end{Description}
\begin{Usage}
\begin{verbatim}
simulate(object, nsim, seed, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] an object representing a fitted model.
\item[\code{nsim}] number of response vectors to simulate.  Defaults to 1.
\item[\code{seed}] an object specifying if and how the random number
generator should be initialized (\sQuote{seeded}).\\
For the "lm" method, either \code{NULL} or an integer that will be
used in a call to \code{set.seed} before simulating the response
vectors.  If set, the value is saved as the \code{"seed"} attribute
of the returned value.  The default, \code{NULL} will not change the
random generator state, and return \code{\LinkA{.Random.seed}{.Random.seed}} as
\code{"seed"} attribute, see below.

\item[\code{...}] additional optional arguments.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
This is a generic function with a method for \code{\LinkA{lm}{lm}} objects.
Consult the individual modeling functions
for details on how to use this function.
\end{Details}
\begin{Value}
Typically, a list of length \code{nsim} of simulated response vectors.
When appropriate the result can be a data frame (which is a special
type of list).

For the \code{"lm"} method, the result is a data frame with an
attribute \code{"seed"} containing the \code{seed} argument and
\code{as.list(\LinkA{RNGkind}{RNGkind}())} if \code{seed} was not \code{NULL},
or the value of \code{\LinkA{.Random.seed}{.Random.seed}} before the simulation was
started when \code{seed} was NULL as by default.
\end{Value}
\begin{SeeAlso}\relax
\code{\LinkA{fitted.values}{fitted.values}} and \code{\LinkA{residuals}{residuals}} for related methods;
\code{\LinkA{glm}{glm}}, \code{\LinkA{lm}{lm}} for model fitting.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
x <- 1:5
mod1 <- lm(c(1:3,7,6) ~ x)
S1 <- simulate(mod1, nsim = 4)
## repeat the simulation:
.Random.seed <- attr(S1, "seed")
identical(S1, simulate(mod1, nsim = 4))

S2 <- simulate(mod1, nsim = 200, seed = 101)
rowMeans(S2) # should be about
fitted(mod1)

## repeat identically:
(sseed <- attr(S2, "seed")) # seed; RNGkind as attribute
stopifnot(identical(S2, simulate(mod1, nsim = 200, seed = sseed)))

## To be sure about the proper RNGkind, e.g., after
RNGversion("1.0.0")
## first set the RNG kind, then simulate
do.call(RNGkind, attr(sseed, "kind"))
identical(S2, simulate(mod1, nsim = 200, seed = sseed))
\end{ExampleCode}
\end{Examples}

