% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_simulated.R
\name{get_simulated}
\alias{get_simulated}
\alias{get_simulated.lm}
\alias{get_simulated.glmmTMB}
\alias{get_simulated.merMod}
\alias{get_simulated.default}
\alias{get_simulated.data.frame}
\title{Simulate values from fitted models}
\usage{
get_simulated(x, ...)

\method{get_simulated}{lm}(
  x,
  data = NULL,
  iterations = 1,
  include_data = FALSE,
  seed = NULL,
  ...
)

\method{get_simulated}{glmmTMB}(
  x,
  data = NULL,
  iterations = 1,
  include_data = FALSE,
  seed = NULL,
  centrality = NULL,
  re.form = NULL,
  ...
)

\method{get_simulated}{merMod}(
  x,
  data = NULL,
  iterations = 1,
  include_data = FALSE,
  seed = NULL,
  use.u = FALSE,
  re.form = NA,
  newparams = NULL,
  family = NULL,
  cluster.rand = stats::rnorm,
  allow.new.levels = FALSE,
  na.action = stats::na.pass,
  ...
)

\method{get_simulated}{default}(x, ...)

\method{get_simulated}{data.frame}(x, data = NULL, include_data = FALSE, ...)
}
\arguments{
\item{x}{A model.}

\item{...}{Additional arguments passed to the underlying prediction or
simulation methods.}

\item{data}{An optional data frame in which to evaluate predictions before
simulation. This can be a data grid created with \code{\link[=get_datagrid]{get_datagrid()}}.}

\item{iterations}{Number of response vectors to simulate.}

\item{include_data}{Logical, if \code{TRUE}, \code{data} is returned alongside with
the simulated draws. If \code{data = NULL}, the data used to fit the model is
included.}

\item{seed}{An optional integer random seed.}

\item{centrality}{Function, indicating how to summarize aggregated simulated
values when \code{data} is a data grid. Only applies to models from package
\code{glmmTMB}, because a special handling for the \code{data} argument is required
here. \code{simulate.glmmTMB()} always returns simulated draws for the full
data that was used to fit the model. If a data grid is passed via \code{data},
\code{get_simulated.glmmTMB()} internally, first, filters the results using
\code{datawizard::data_match()} with the model data and \code{data}. This may return
more than one row of simulated draws per group defined in \code{data}, thus, in
a second step, the filtered data are aggregated by the groups defined in
\code{data}. Resulting estimates of simulated values are summarized using
\code{centrylity}, which, by default is the mode for categorical, ordinal or
count response variables, or the mean otherwise.}

\item{re.form}{For \code{glmmTMB} and \code{merMod} models, random effects formula
passed to simulation (\code{NULL}, \code{NA} or \code{~0}).}

\item{use.u}{For \code{merMod} models, logical indicating whether to condition
on the current conditional modes of the random effects when simulating.}

\item{newparams}{For \code{merMod} models, optional list or vector of alternative
parameter values (e.g., fixed- and random-effect parameters) to be used for
simulation instead of those from the fitted model.}

\item{family}{For \code{merMod} models, optional \code{family} object or function to
override the model's family when simulating responses.}

\item{cluster.rand}{For \code{merMod} models, function used to generate random
draws for the random effects (e.g., \code{rnorm}).}

\item{allow.new.levels}{For \code{merMod} models, logical indicating whether new
levels of grouping variables are allowed in \code{data} when simulating.}

\item{na.action}{For \code{merMod} models, function specifying how to handle
missing values in \code{data} before simulation (e.g., \code{"na.pass"}).}
}
\value{
A data frame with one column per simulation (\code{iter_1}, \code{iter_2}, ...).
The attribute \code{seed} contains information about the RNG state used.
}
\description{
Simulate responses from fitted statistical models.
}
\examples{
data(mtcars)
m <- lm(mpg ~ wt + cyl, data = mtcars)

# Simulations on the original data
get_simulated(m, iterations = 2, seed = 123)

# Simulations on a data grid
dg <- get_datagrid(m, wt = c(2, 3), cyl = c(4, 6))
get_simulated(dg, m, iterations = 2, seed = 123)

}
