\name{stan_model}
\alias{stan_model}
\title{Construct a Stan model}
\description{
  Construct an instance of S4 class \code{stanmodel} from a model
  specified in Stan's modeling language. A \code{stanmodel} object
  can then be used to draw samples from the model. The Stan program
  (the model expressed in the Stan modeling language) is first translated to
  C++ code and then the C++ code for the model plus other auxiliary
  code is compiled into a dynamic shared object (DSO) and then loaded.
  The loaded DSO for the model can be executed to draw samples, allowing
  inference to be performed for the model and data.
}

\usage{
  stan_model(
    file, model_name = "anon_model",
    model_code = "", stanc_ret = NULL,
    boost_lib = NULL, eigen_lib = NULL,
    save_dso = TRUE, verbose = FALSE,
    auto_write = rstan_options("auto_write"),
    obfuscate_model_name = TRUE,
    allow_undefined = isTRUE(getOption("stanc.allow_undefined", FALSE)),
    allow_optimizations = isTRUE(getOption("stanc.allow_optimizations", FALSE)),
    standalone_functions = isTRUE(getOption("stanc.standalone_functions", FALSE)),
    use_opencl = isTRUE(getOption("stanc.use_opencl", FALSE)),
    warn_pedantic = isTRUE(getOption("stanc.warn_pedantic", FALSE)),
    warn_uninitialized = isTRUE(getOption("stanc.warn_uninitialized", FALSE)),
    includes = NULL,
    isystem = c(if (!missing(file)) dirname(file), getwd()))
}

\arguments{
  \item{file}{A character string or a connection that \R supports
    specifying the Stan model specification in Stan's modeling language.
  }

  \item{model_name}{A character string naming the model; defaults
    to \code{"anon_model"}. However, the model name will be derived from
    \code{file} or \code{model_code} (if \code{model_code} is the name of a
    character string object) if \code{model_name} is not specified.}

  \item{model_code}{Either a character string containing the model
    specification or the name of a character string object in the workspace.
    This is an alternative to specifying the model via the \code{file}
    or \code{stanc_ret} arguments.
  }
  \item{stanc_ret}{A named list returned from a previous call to
    the \code{\link{stanc}} function. The list can be used to specify the model
    instead of using the \code{file} or \code{model_code} arguments.
  }
  \item{boost_lib}{The path to a version of the Boost C++ library to
    use instead of the one in the \pkg{BH} package.}
  \item{eigen_lib}{The path to a version of the Eigen C++ library to
    use instead of the one in the \pkg{RcppEigen} package.}
  \item{save_dso}{Logical, defaulting to \code{TRUE}, indicating
    whether the  dynamic shared object (DSO) compiled from the C++ code for the
    model will be saved or not. If \code{TRUE}, we can draw samples from
    the same model in another \R session using the saved DSO (i.e.,
    without compiling the C++ code again).}
  \item{verbose}{Logical, defaulting to \code{FALSE}, indicating whether
    to report additional intermediate output to the console,
    which might be helpful for debugging.}
  \item{auto_write}{Logical, defaulting to the value of
    \code{rstan_options("auto_write")}, indicating whether to write the
    object to the hard disk using \code{\link{saveRDS}}. Although this argument
    is \code{FALSE} by default, we recommend calling
    \code{rstan_options("auto_write" = TRUE)} in order to avoid unnecessary
    recompilations. If \code{file} is supplied and its \code{\link{dirname}}
    is writable, then the object will be written to that same directory,
    substituting a \code{.rds} extension for the \code{.stan} extension.
    Otherwise, the object will be written to the \code{\link{tempdir}}.}
  \item{obfuscate_model_name}{A logical scalar that is \code{TRUE} by default and
    passed to \code{\link{stanc}}.}
  \item{allow_undefined}{A logical scalar that is \code{FALSE} by default and
    passed to \code{\link{stanc}}.}
  \item{allow_optimizations}{A logical scalar that is \code{FALSE} by default and
    passed to \code{\link{stanc}}.}
  \item{standalone_functions}{A logical scalar that is \code{FALSE} by default and
    passed to \code{\link{stanc}}.}
  \item{use_opencl}{A logical scalar that is \code{FALSE} by default and
    passed to \code{\link{stanc}}.}
  \item{warn_pedantic}{A logical scalar that is \code{FALSE} by default and
    passed to \code{\link{stanc}}.}
  \item{warn_uninitialized}{A logical scalar that is \code{FALSE} by default and
    passed to \code{\link{stanc}}.}
  \item{includes}{If not \code{NULL} (the default), then a character vector of
    length one (possibly containing one or more \code{"\n"}) of the form
    \code{'#include "/full/path/to/my_header.hpp"'}, which will be inserted
    into the C++ code in the model's namespace and can be used to provide definitions
    of functions that are declared but not defined in \code{file} or
    \code{model_code} when \code{allow_undefined = TRUE}}
  \item{isystem}{A character vector naming a path to look for
    file paths in \code{file} that are to be included within the Stan program
    named by \code{file}. See the Details section below.}
}

\details{
  If a previously compiled \code{stanmodel} exists on the hard drive, its validity
  is checked and then returned without recompiling. The most common form of
  invalidity seems to be Stan code that ends with a \code{\}} rather than a blank
  line, which causes the hash checker to think that the current model is different
  than the one saved on the hard drive. To avoid reading previously
  compiled \code{stanmodel}s from the hard drive, supply the \code{stanc_ret}
  argument rather than the \code{file} or \code{model_code} arguments.

  There are three ways to specify the model's code for \code{stan_model}:
  \enumerate{
  \item parameter \code{model_code}: a character string containing the
        Stan model specification,
  \item parameter \code{file}: a file name (or a connection) from
       which to read the Stan model specification, or
  \item parameter \code{stanc_ret}: a list returned by \code{stanc}
        to be reused.
  }
}
\value{
  An instance of S4 class \code{\linkS4class{stanmodel}} that can be
  passed to the \code{\link{sampling}}, \code{\link{optimizing}}, and
  \code{\link{vb}} functions.
}
\references{
  The Stan Development Team
  \emph{Stan Modeling Language User's Guide and Reference Manual}.
  \url{https://mc-stan.org/}.
}
\seealso{
  \code{\linkS4class{stanmodel}} for details on the class.

  \code{\link{sampling}}, \code{\link{optimizing}}, and \code{\link{vb}},
  which take a \code{stanmodel} object as input, for estimating the model
  parameters.

  More details on Stan, including the full user's guide and reference
  manual, can be found at \url{https://mc-stan.org/}.
}
\examples{\dontrun{
stancode <- 'data {real y_mean;} parameters {real y;} model {y ~ normal(y_mean,1);}'
mod <- stan_model(model_code = stancode, verbose = TRUE)
fit <- sampling(mod, data = list(y_mean = 0))
fit2 <- sampling(mod, data = list(y_mean = 5))
}}
\keyword{rstan}
