% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stanvars.R
\name{stanvar}
\alias{stanvar}
\alias{stanvars}
\title{User-defined variables passed to Stan}
\usage{
stanvar(
  x = NULL,
  name = NULL,
  scode = NULL,
  block = "data",
  position = "start",
  pll_args = NULL
)
}
\arguments{
\item{x}{An \R object containing data to be passed to Stan.
Only required if \code{block = 'data'} and ignored otherwise.}

\item{name}{Optional character string providing the desired variable
name of the object in \code{x}. If \code{NULL} (the default)
the variable name is directly inferred from \code{x}.}

\item{scode}{Line of Stan code to define the variable
in Stan language. If \code{block = 'data'}, the
Stan code is inferred based on the class of \code{x} by default.}

\item{block}{Name of one of Stan's program blocks in
which the variable should be defined. Can be \code{'data'},
\code{'tdata'} (transformed data), \code{'parameters'},
\code{'tparameters'} (transformed parameters), \code{'model'},
\code{'likelihood'} (part of the model block where the likelihood is given),
\code{'genquant'} (generated quantities) or \code{'functions'}.}

\item{position}{Name of the position within the block where the
Stan code should be placed. Currently allowed are \code{'start'}
(the default) and \code{'end'} of the block.}

\item{pll_args}{Optional Stan code to be put into the header
of \code{partial_log_lik} functions. This ensures that the variables
specified in \code{scode} can be used in the likelihood even when
within-chain parallelization is activated via \code{\link{threading}}.}
}
\value{
An object of class \code{stanvars}.
}
\description{
Prepare user-defined variables to be passed to one of Stan's
program blocks. This is primarily useful for defining more complex
priors, for refitting models without recompilation despite
changing priors, or for defining custom Stan functions.
}
\details{
The \code{stanvar} function is not vectorized. Instead, multiple
\code{stanvars} objects can be added together via \code{+} (see Examples).

Special attention is necessary when using \code{stanvars} to inject
code into the \code{'likelihood'} block while having \code{\link{threading}}
activated. In this case, your custom Stan code may need adjustments to ensure
correct observation indexing. Please investigate the generated Stan code via
\code{\link[brms:stancode.default]{stancode}} to see which adjustments are necessary in your case.
}
\examples{
bprior <- prior(normal(mean_intercept, 10), class = "Intercept")
stanvars <- stanvar(5, name = "mean_intercept")
stancode(count ~ Trt, epilepsy, prior = bprior,
         stanvars = stanvars)

# define a multi-normal prior with known covariance matrix
bprior <- prior(multi_normal(M, V), class = "b")
stanvars <- stanvar(rep(0, 2), "M", scode = "  vector[K] M;") +
  stanvar(diag(2), "V", scode = "  matrix[K, K] V;")
stancode(count ~ Trt + zBase, epilepsy,
         prior = bprior, stanvars = stanvars)

# define a hierachical prior on the regression coefficients
bprior <- set_prior("normal(0, tau)", class = "b") +
  set_prior("target += normal_lpdf(tau | 0, 10)", check = FALSE)
stanvars <- stanvar(scode = "real<lower=0> tau;",
                    block = "parameters")
stancode(count ~ Trt + zBase, epilepsy,
         prior = bprior, stanvars = stanvars)

# ensure that 'tau' is passed to the likelihood of a threaded model
# not necessary for this example but may be necessary in other cases
stanvars <- stanvar(scode = "real<lower=0> tau;",
                    block = "parameters", pll_args = "real tau")
stancode(count ~ Trt + zBase, epilepsy,
         stanvars = stanvars, threads = threading(2))

}
