| % File src/library/stats/man/simulate.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2014 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{simulate} |
| \title{Simulate Responses} |
| \description{ |
| Simulate one or more responses from the distribution |
| corresponding to a fitted model object. |
| } |
| \usage{ |
| simulate(object, nsim = 1, seed = NULL, \dots) |
| } |
| \alias{simulate} |
| \arguments{ |
| \item{object}{an object representing a fitted model.} |
| \item{nsim}{number of response vectors to simulate. Defaults to \code{1}.} |
| \item{seed}{an object specifying if and how the random number |
| generator should be initialized (\sQuote{seeded}).\cr |
| 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{\link{.Random.seed}} as the |
| \code{"seed"} attribute, see \sQuote{Value}. |
| } |
| \item{\dots}{additional optional arguments.} |
| } |
| \value{ |
| Typically, a list of length \code{nsim} of simulated responses. Where |
| appropriate the result can be a data frame (which is a special type of |
| list). |
| %% a *matrix* seems very natural and is more efficient |
| %% for large-scale simulation, already for stats:::simulate.lm (in ../R/lm.R ) |
| |
| For the \code{"lm"} method, the result is a data frame with an |
| attribute \code{"seed"}. If argument \code{seed} is \code{NULL}, the |
| attribute is the value of \code{\link{.Random.seed}} before the |
| simulation was started; otherwise it is the value of the argument with |
| a \code{"kind"} attribute with value \code{as.list(\link{RNGkind}())}. |
| } |
| \details{ |
| This is a generic function. Consult the individual modeling functions |
| for details on how to use this function. |
| |
| Package \pkg{stats} has a method for \code{"lm"} objects which is used |
| for \code{\link{lm}} and \code{\link{glm}} fits. There is a method |
| for fits from \code{glm.nb} in package \CRANpkg{MASS}, and hence the |
| case of negative binomial families is not covered by the \code{"lm"} |
| method. |
| |
| The methods for linear models fitted by \code{lm} or \code{glm(family |
| = "gaussian")} assume that any weights which have been supplied are |
| inversely proportional to the error variance. For other GLMs the |
| (optional) \code{simulate} component of the \code{\link{family}} |
| object is used---there is no appropriate simulation method for |
| \sQuote{quasi} models as they are specified only up to two moments. |
| |
| For binomial and Poisson GLMs the dispersion is fixed at one. Integer |
| prior weights \eqn{w_i} can be interpreted as meaning that |
| observation \eqn{i} is an average of \eqn{w_i} observations, which is |
| natural for binomials specified as proportions but less so for a |
| Poisson, for which prior weights are ignored with a warning. |
| |
| For a gamma GLM the shape parameter is estimated by maximum likelihood |
| (using function \code{\link[MASS:gamma.shape.glm]{gamma.shape}} in package |
| \CRANpkg{MASS}). The interpretation of weights is as multipliers to a |
| basic shape parameter, since dispersion is inversely proportional to |
| shape. |
| |
| For an inverse gaussian GLM the model assumed is |
| \eqn{IG(\mu_i, \lambda w_i)} (see |
| \url{https://en.wikipedia.org/wiki/Inverse_Gaussian_distribution}) |
| where \eqn{\lambda} is estimated by the inverse of the dispersion |
| estimate for the fit. The variance is |
| \eqn{\mu_i^3/(\lambda w_i)} and |
| hence inversely proportional to the prior weights. The simulation is |
| done by function \code{\link[SuppDists:invGauss]{rinvGauss}} from the |
| \CRANpkg{SuppDists} package, which must be installed. |
| } |
| \seealso{ |
| \code{\link{RNG}} about random number generation in \R, |
| \code{\link{fitted.values}} and \code{\link{residuals}} for related methods; |
| \code{\link{glm}}, \code{\link{lm}} for model fitting. |
| |
| There are further examples in the \file{simulate.R} tests file in the |
| sources for package \pkg{stats}. |
| } |
| \examples{ |
| 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 the same as |
| 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("2.7.0") |
| ## first set the RNG kind, then simulate |
| do.call(RNGkind, attr(sseed, "kind")) |
| identical(S2, simulate(mod1, nsim = 200, seed = sseed)) |
| |
| ## Binomial GLM examples |
| yb1 <- matrix(c(4, 4, 5, 7, 8, 6, 6, 5, 3, 2), ncol = 2) |
| modb1 <- glm(yb1 ~ x, family = binomial) |
| S3 <- simulate(modb1, nsim = 4) |
| # each column of S3 is a two-column matrix. |
| |
| x2 <- sort(runif(100)) |
| yb2 <- rbinom(100, prob = plogis(2*(x2-1)), size = 1) |
| yb2 <- factor(1 + yb2, labels = c("failure", "success")) |
| modb2 <- glm(yb2 ~ x2, family = binomial) |
| S4 <- simulate(modb2, nsim = 4) |
| # each column of S4 is a factor |
| } |
| \keyword{models} |
| \keyword{datagen} |