\part{Additional Topics}


\chapter{Bayesian Data Analysis}\label{bayesian.chapter}

\noindent
\cite{GelmanCarlinSternRubin:2003} provide the following
characterization of Bayesian data analysis.
%
\begin{quote}
  By Bayesian data analysis, we mean practical methods for making
  inferences from data using probability models for quantities we
  observe and about which we wish to learn.
\end{quote}
%
They go on to describe how Bayesian statistics differs from
frequentist approaches.
%
\begin{quote}
  The essential characteristic of Bayesian methods is their explicit
  use of probability for quantifying uncertainty in inferences based
  on statistical analysis.
\end{quote}
%
Because they view probability as the limit of relative frequencies of
observations, strict frequentists forbid probability statements about
parameters.  Parameters are considered fixed, not random.  

Bayesians also treat parameters as fixed but unknown.  But unlike
frequentists, they make use of both prior distributions over
parameters and posterior distributions over parameters.  These prior
and posterior probabilities and posterior predictive probabilities are
intended to characterize knowledge about the parameters and future
observables.  Posterior distributions form the basis of Bayesian
inference, as described below.

\section{Bayesian Modeling}

\citep{GelmanCarlinSternRubin:2003} break applied Bayesian modeling
into the following three steps.
%
\begin{enumerate}
\item  Set up a full probability model for all observable and
  unobservable quantities.  This model should be consistent with
  existing knowledge of the data being modeled and how it was
  collected.
\item Calculate the posterior probability of unknown quantities
  conditioned on observed quantities.  The unknowns may include
  unobservable quantities such as parameters and potentially
  observable quantities such as predictions for future observations.
\item Evaluate the model fit to the data.  This includes evaluating
  the implications of the posterior.
\end{enumerate}
%
Typically, this cycle will be repeated until a sufficient fit is
achieved in the third step.  \Stan automates the calculations involved
in the second and third steps.

\section{Bayesian Inference}

\subsection{Basic Quantities}

The mechanics of Bayesian inference follow directly from Bayes's rule.
To fix notation, let $y$ represent observed quantities such as data
and let $\theta$ represent unknown quantities such as parameters and
future observations.  Both $y$ and $\theta$ will be modeled as random.
Let $x$ represent known, but unmodeled quantities such as constants,
hyperparameters, and predictors.

\subsection{Probability Functions}

The probability function $p(y,\theta)$ is the joint probability
function of the data $y$ and parameters $\theta$.  The constants and
predictors $x$ are implicitly understood as being part of the
conditioning.  The conditional probability function $p(y|\theta)$ of
the data $y$ given parameters $\theta$ and constants $x$ is called the
sampling probability function; it is also called the likelihood
function when viewed as a function of $\theta$ for fixed $y$ and $x$.

The probability function $p(\theta)$ over the parameters given the
constants $x$ is called the prior because it characterizes the probability
of the parameters before any data is observed.  The conditional
probability function $p(\theta|y)$ is called the posterior because
it characterizes the probability of parameters given observed data $y$
and constants $x$.  

\subsection{Bayes's Rule}

The technical apparatus of Bayesian inference hinges on the following
chain of equations, known in various forms as Bayes's rule (where
again, the constants $x$ are implicit).
%
\[
\begin{array}{rcll}
p(\theta|y)  & =  & \displaystyle \frac{p(\theta,y)}{p(y)} 
& \mbox{{} \ \ \ \ \ [definition of  conditional probability]}
\\[16pt]
& = & \displaystyle \frac{p(y|\theta) \, p(\theta)}{p(y)}
& \mbox{{} \ \ \ \ \ [chain rule]}
\\[16pt]
& = & \displaystyle \frac{p(y|\theta) \, p(\theta)}
                        {\int_{\Theta} p(y,\theta) \, d\theta}
& \mbox{{} \ \ \ \ \ [law of total probability]}
\\[16pt]
& = & \displaystyle \frac{p(y|\theta) \, p(\theta)}
                        {\int_{\Theta} p(y|\theta) \, p(\theta) \, d\theta}
& \mbox{{} \ \ \ \ \ [chain rule]}
\\[16pt]
& \propto & \displaystyle p(y|\theta) \, p(\theta)
& \mbox{{} \ \ \ \ \ [$y$ is fixed]}
\end{array}
\]
%
Bayes's rule ``inverts'' the probability of the posterior
$p(\theta|y)$, expressing it solely in terms of the likelihood
$p(y|\theta)$ and prior $p(\theta)$ (again, with constants and
predictors $x$ implicit).  The last step is important for \Stan, which
only requires probability functions to be characterized up to a
constant multiplier.

\subsection{Predictive Inference}

The uncertainty in the estimation of parameters $\theta$ from the data
$y$ (given the model) is characterized by the posterior $p(\theta|y)$.
The posterior is thus crucial for Bayesian predictive inference.

If $\tilde{y}$ is taken to represent new, perhaps as yet unknown,
observations, along with corresponding constants and predictors
$\tilde{x}$, then the posterior predictive probability function is
given by
%
\[
p(\tilde{y}|y)
= \int_{\Theta} p(\tilde{y}|\theta) 
                \, p(\theta|y) \, d\theta.
\]
Here, both the original constants and predictors $x$ and the new
constants and predictors $\tilde{x}$ are implicit.  Like the posterior
itself, predictive inference is characterized probabilistically.
Rather than using a point estimate of the parameters $\theta$,
predictions are made based on averaging the predictions over a range
of $\theta$ weighted by the posterior probability $p(\theta|y)$ of
$\theta$ given data $y$ (and constants $x$).

The posterior may also be used to estimate event probabilities.  For
instance, the probability that a parameter $\theta_k$ is greater than
zero is characterized probabilistically by
%
\[
\mbox{Pr}[\theta_k > 0]
= \int_{\Theta} \mbox{I}(\theta_k > 0) \, p(\theta|y) \, d\theta.
\]
%
The indicator function, $\mbox{I}(\phi)$, evaluates to one if the
proposition $\phi$ is true and evaluates to zero otherwise.

Comparisons involving future observables may be carried out in
the same way.  For example, the probability that $\tilde{y}_n >
\tilde{y}_{n'}$ can be characterized using the posterior predictive
probability function as
\[
\mbox{Pr}[\tilde{y}_n > \tilde{y}_{n'}]
= \int_{\Theta} \int_{Y} \mbox{I}(\tilde{y}_n > \tilde{y}_{n'}) \,
p(\tilde{y}|\theta) p(\theta|y) \, d\tilde{y} \, d\theta.
\]


\subsection{Posterior Predictive Checking}

After the parameters are fit to data, they can be used to simulate a
new data set by running the model inferences in the forward
direction.  These replicated data sets can then be compared to the
original data either visually or statistically to assess model fit 
\citep[Chapter 6]{GelmanCarlinSternRubin:2003}.  

In Stan, posterior simulations can be generated in two ways.  The
first approach is to treat the predicted variables as parameters and
then define their distributions in the model block.  The second
approach, which also works for discrete variables, is to generate
replicated data using random-number generators in the generated
quantities block.



\chapter{Markov Chain Monte Carlo Sampling}\label{mcmc.chapter}

\noindent
Like \BUGS, \Stan uses Markov chain Monte Carlo (\MCMC) techniques to
generate samples from the posterior distribution for inference.  


\section{Monte Carlo Sampling}

Monte Carlo methods were developed to numerically approximate
integrals that are not tractable analytically but for which evaluation
of the function being integrated is tractable
\citep{MetropolisUlam:1949}.

For example, the mean $\mu$ of a probability density $p(\theta)$ is
defined by the integral
\[
\mu = \int_{\Theta} \, \theta \times p(\theta) \, d\theta.
\]
For even a moderately complex Bayesian model, the posterior density
$p(\theta|y)$ leads to an integral that is impossible to evaluate
analytically.  The posterior also depends on the constants and
predictors $x$, but from here, they will just be elided and taken as
given.

Now suppose it is possible to draw independent samples from
$p(\theta)$ and let $\theta^{(1)},\theta^{(2)},\ldots,\theta^{(N)}$ be
$N$ such samples.  A Monte Carlo estimate $\hat{\mu}$ of the mean
$\mu$ of $p(\theta)$ is given by the sample average,
\[
\hat{\mu} = \frac{1}{N} \sum_{n=1}^N \theta^{(n)}.
\]

If the probability function $p(\theta)$ has a finite mean and
variance, the law of large numbers ensures the Monte Carlo estimate
converges to the correct value as the number of samples increases,
\[
\lim_{N \rightarrow \infty} \hat{\mu} = \mu.
\]
Assuming finite mean and variance, estimation error is governed by the
central limit theorem, so that estimation error decreases as the
square root of $N$,
\[
|\mu - \hat{\mu}| \propto \frac{1}{\sqrt{N}}.
\]
Therefore, estimating a mean to an extra decimal place of accuracy
requires one hundred times more samples; adding two decimal places
means ten thousand times as many samples.  This makes Monte Carlo
methods more useful for rough estimates to within a few decimal places
than highly precise estimates.  In practical applications, there is no
point estimating a quantity beyond the uncertainty of the data sample
on which it is based, so this lack of many decimal places of accuracy
is rarely a problem in practice for statistical models.


\section{Markov Chain Monte Carlo Sampling}

Markov chain Monte Carlo (\MCMC) methods were developed for situations
in which it is not straightforward to draw independent samples
\citep{Metropolis:1953}.

A Markov chain is a sequence of random variables $\theta^{(1)},
\theta^{(2)},\ldots$ where each variable is conditionally independent
of all other variables given the value of the previous value.  Thus if
$\theta = \theta^{(1)}, \theta^{(2)},\ldots, \theta^{(N)}$, then
\[
p(\theta) = p(\theta^{(1)}) \prod_{n=2}^N p(\theta^{(n)}|\theta^{(n-1)}).
\]
\Stan generates a next state in a manner described in
\refsection{intro-samplers}. 

The Markov chains \Stan and other \MCMC samplers generate are ergodic
in the sense required by the Markov chain central limit theorem,
meaning roughly that there is there is a reasonable chance of reaching
one value of $\theta$ from another.  The Markov chains are also
stationary, meaning that the transition probabilities do not change at
different positions in the chain, so that for $n, n' \geq 0$, the
probability function $p(\theta^{(n+1)}|\theta^{(n)})$ is the same as
$p(\theta^{(n'+1)}|\theta^{(n')})$ (following the convention of
overloading random and bound variables and picking out a probability
function by its arguments).

Stationary Markov chains have an equilibrium distribution on states in
which each has the same marginal probability function, so that
$p(\theta^{(n)})$ is the same probability function as
$p(\theta^{(n+1)})$.  In \Stan, this equilibrium distribution
$p(\theta^{(n)})$ is the probability function $p(\theta)$ being
sampled, typically a Bayesian posterior density.

Using \MCMC methods introduces two difficulties that are not faced by
independent sample Monte Carlo methods.  The first problem is determining
when a randomly initialized Markov chain has converged to its
equilibrium distribution.  The second problem is that the draws from a
Markov chain are correlated, and thus the central limit theorem's
bound on estimation error no longer applies.  These problems are
addressed in the next two sections.


\section{Initialization and Convergence Monitoring}\label{convergence.section}

A Markov chain generates samples from the target distribution only
after it has converged to equilibrium.  Unfortunately, this is only
guaranteed in the limit in theory.  In practice, diagnostics must be
applied to monitor whether the Markov chain(s) have converged.

\subsection{Potential Scale Reduction}

One way to monitor whether a chain has converged to the equilibrium
distribution is to compare its behavior to other randomly initialized
chains.  This is the motivation for the \cite{GelmanRubin:1992}
potential scale reduction statistic, $\hat{R}$.  The $\hat{R}$
statistic measures the ratio of the average variance of samples within
each chain to the variance of the pooled samples across chains; if all
chains are at equilibrium, these will be the same and $\hat{R}$ will
be one.  If the chains have not converged to a common distribution,
the $\hat{R}$ statistic will be greater than one.

Gelman and Rubin's recommendation is that the independent Markov
chains be initialized with diffuse starting values for the parameters
and sampled until all values for $\hat{R}$ are below 1.1.  \Stan
allows users to specify initial values for parameters and it is also
able to draw diffuse random initializations itself.

The $\hat{R}$ statistic is defined for a set of $M$ Markov chains,
$\theta_m$, each of which has $N$ samples $\theta^{(n)}_m$.  The
between-sample variance estimate is
\[
B
= \frac{N}{M-1} \, \sum_{m=1}^M (\bar{\theta}^{(\bullet)}_{m} - \bar{\theta}^{(\bullet)}_{\bullet})^2,
\]
%
where
%
\[
\bar{\theta}_m^{(\bullet)}
= \frac{1}{N} \sum_{n = 1}^N \theta_m^{(n)}
\ \ \ \ \
\mbox{and}
\ \ \ \ \
\bar{\theta}^{(\bullet)}_{\bullet}
= \frac{1}{M} \, \sum_{m=1}^M \bar{\theta}_m^{(\bullet)}.
\]
%
The within-sample variance is
\[
W 
= \frac{1}{M} \, \sum_{m=1}^M s_m^2,
\]
where
\[
s_m^2 = \frac{1}{N-1} \, \sum_{n=1}^N (\theta^{(n)}_m - \bar{\theta}^{(\bullet)}_m)^2.
\]
%
The variance estimator is
\[
\widehat{\mbox{var}}^{+}\!(\theta|y)
= \frac{N-1}{N}\, W \, + \, \frac{1}{N} \, B.
\]
%
Finally, the potential scale reduction statistic is defined by
\[
\hat{R} 
\, = \,
\sqrt{\frac{\widehat{\mbox{var}}^{+}\!(\theta|y)}{W}}.
\]

\subsection{Generalized $\hat{R}$ for Ragged Chains}

Now suppose that each chain may have a different number of samples.
Let $N_m$ be the number of samples in chain $m$.  Now the formula for
the within-chain mean for chain $m$ uses the size of the chain, $N_m$,
\[
\bar{\theta}_m^{(\bullet)}
= \frac{1}{N_m} \sum_{n = 1}^N \theta^{(m)}_n,
\]
as does the within-chain variance estimate,
\[
s_m^2 = \frac{1}{N_m-1} \, \sum_{n=1}^{N_m} (\theta^{(n)}_m - \bar{\theta}^{(\bullet)}_m)^2.
\]
The terms that average over chains, such as
$\bar{\theta}^{(\bullet)}_{\bullet}$, $B$, and $W$, have the same
definition as before to ensure that each chain has the same effect on
the estimate.  If the averages were weighted by size, a single long
chain would dominate the statistics and defeat the purpose of
monitoring convergence with multiple chains.

Because it contains the term $N$, the estimate $\widehat{var}^{+}$
must be generalized.  By expanding the first term,
\[
\frac{N-1}{N}\, W \, 
\ = \ 
\frac{N-1}{N} \frac{1}{M} \, \sum_{m=1}^M
\frac{1}{N-1} \, \sum_{n=1}^N (\theta^{(n)}_m -
\bar{\theta}^{(\bullet)}_m)^2
\ = \
\frac{1}{M} 
\sum_{m=1}^M
\frac{1}{N}
\sum_{n=1}^N (\theta^{(n)}_m -
\bar{\theta}^{(\bullet)}_m)^2,
\]
and the second term,
\[
\frac{1}{N}\, B
\ = \
\frac{1}{M-1} \, \sum_{m=1}^M (\bar{\theta}^{(\bullet)}_{m} - \bar{\theta}^{(\bullet)}_{\bullet})^2.
\]
the variance estimator naturally generalizes to
\[
\widehat{\mbox{var}}^{+}\!(\theta|y)
= 
\frac{1}{M} 
\sum_{m=1}^M
\frac{1}{N_m}
\sum_{n=1}^{N_m} (\theta^{(n)}_m -
\bar{\theta}^{(\bullet)}_m)^2
+
\frac{1}{M-1} \, \sum_{m=1}^M (\bar{\theta}^{(\bullet)}_{m} -
\bar{\theta}^{(\bullet)}_{\bullet})^2.
\]
%
If the chains are all the same length, this definition is equivalent
to the one in the last section.  This generalized variance estimator
and the within-chains variance estimates may be plugged directly into
the formula for $\hat{R}$ from the previous section.


\subsection{Split $\hat{R}$ for Detecting Non-Stationarity}

Before calculating the potential-scale-reduction statistic $\hat{R}$,
each chain may be split into two halves.  This provides an additional
means to detect non-stationarity in the chains.  If one chain involves
gradually increasing values and one involves gradually decreasing
values, they have not mixed well, but they can have $\hat{R}$ values
near unity.  In this case, splitting each chain into two parts leads
to $\hat{R}$ values substantially greater than 1 because the first
half of each chain has not mixed with the second half.  

\section{Effective Sample Size}\label{effective-sample-size.section}

The second technical difficulty posed by \MCMC methods is that the
samples will typically be autocorrelated within a chain.  This
increases the uncertainty of the estimation of posterior quantities of
interest, such as means, variances or quantiles.

\subsection{Definition of Effective Sample Size}

The amount by which autocorrelation within the chains increases
uncertainty in estimates can be measured by effective sample size
({\sc ess}).  Given independent samples, the central limit theorem
bounds uncertainty in estimates based on the number of samples $N$.
Given dependent samples, the number of independent samples is replaced
with the effective sample size $N_{\mbox{\scriptsize eff}}$, which is
the number of independent samples with the same estimation power as
the $N$ autocorrelated samples.  For example, estimation error is
proportional to $1/\sqrt{N_{\mbox{\scriptsize eff}}}$ rather than
$1/\sqrt{N}$.

The effective sample size of a sequence is defined in terms of the
autocorrelations within the sequence at different lags.  The
autocorrelation $\rho_t$ at lag $t \geq 0$ for a chain with joint
probability function $p(\theta)$ with mean $\mu$ and variance
$\sigma^2$ is defined to be
\[
\rho_t 
= 
\frac{1}{\sigma^2} \, \int_{\Theta} (\theta^{(n)} - \mu)
(\theta^{(n+t)} - \mu) \, p(\theta) \, d\theta.
\]
This is just the correlation between the two chains offset by $t$
positions.  Because we know $\theta^{(n)}$ and $\theta^{(n+t)}$ have
the same marginal distribution in an \MCMC setting, multiplying the
two difference terms and reducing yields
\[
\rho_t
= 
\frac{1}{\sigma^2} \, \int_{\Theta} \theta^{(n)} \, \theta^{(n+t)} \, p(\theta) \, d\theta.
\]

The effective sample size of $N$ samples generated by a process with
autocorrelations $\rho_t$ is defined by
\[
N_{\mbox{\scriptsize eff}}
\ = \
\frac{N}{\sum_{t = -\infty}^{\infty} \rho_t}
\ = \
\frac{N}{1 + 2 \sum_{t = 1}^{\infty} \rho_t}.
\]

\subsection{Estimation of Effective Sample Size}

In practice, the probability function in question cannot be tractably
integrated and thus the autocorrelation cannot be calculated, nor the
effective sample size.  Instead, these quantities must be estimated
from the samples themselves.  The rest of this section describes a
variogram-based estimator for autocorrelations, and hence effective sample
size, based on multiple chains. For simplicity, each chain
$\theta_m$ will be assumed to be of length $N$.

One way to estimate the effective sample size is based on the
variograms $V_t$ at lag $t \in \setlist{0,1\ldots}$.  The variograms are
defined as follows for (univariate) samples $\theta_m^{(n)}$, where $m \in
\setlist{1,\ldots,M}$ is the chain, and $N_m$ is the number of samples
in chain $m$.
\[
V_t = 
\frac{1}{M}
\,
\sum_{m=1}^M 
\
\left(
\frac{1}{N_m}
\sum_{n=t+1}^{N^m}
\left(
\theta_m^{(n)} - \theta_m^{(n-t)}
\right)^2
\right).
\]
%
The variogram along with the multi-chain variance estimate
$\widehat{\mbox{var}}^{+}$ introduced in the previous section can be
used to estimate the autocorrelation at lag $t$ as
\[
\hat{\rho}_t
= 1 - \frac{\displaystyle V_t}{
            \displaystyle 2 \, \widehat{\mbox{var}}^{+}}.
\]
If the chains have not converged, the variance estimator
$\widehat{\mbox{var}}^{+}$ will overestimate variance, 
leading to an overestimate of autocorrelation and an underestimate
effective sample size.

Because of the noise in the correlation estimates $\hat{\rho}_t$ as $t$
increases, typically only the initial estimates of $\hat{\rho}_t$
where $\hat{\rho}_t < 0$ will be used.  Setting $T'$ to be the
first lag such that $\rho_{T' + 1} < 0$, 
\[
T' = \arg\min_t \ \hat{\rho}_{t+1} < 0,
\]
the effective sample size estimator is defined as
\[
\hat{N}_{\mbox{\scriptsize eff}}
= 
\frac{MN}
     {1 + \sum_{t=1}^{T'} \hat{\rho}_t}.
\]

\subsection{Thinning Samples}

In the typical situation, the autocorrelation, $\rho_t$, decreases as
the lag, $t$, increases.  When this happens, thinning the samples will
reduce the autocorrelation.  For instance, consider generating one
thousand samples in one of the following two ways.
%
\begin{enumerate}
\item Generate 1000 samples after convergence and save all of
  them.
\item Generate 10,000 samples after convergence and save every tenth
  sample.
\end{enumerate}
%
Even though both produce one thousand samples, the second approach
with thinning will produce more effective samples.  That's because the
autocorrelation $\rho_t$ for the thinned sequence is equivalent to
$\rho_{10t}$ in the unthinned samples, so the sum of the autocorrelations
will be lower and thus the effective sample size higher.  

On the other hand, if memory and data storage are no object, saving all
ten thousand samples will have a higher effective sample size than
thinning to one thousand samples.

\section{Stan's Hamiltonian Monte Carlo Samplers}\label{intro-samplers.section}

For continuous variables, \Stan uses Hamiltonian Monte Carlo (\HMC)
sampling. \HMC is a Markov chain Monte Carlo (\MCMC) method based on
simulating the Hamiltonian dynamics of a fictional physical system in
which the parameter vector $\theta$ represents the position of a
particle in $K$-dimensional space and potential energy is defined to
be the negative (unnormalized) log probability.  Each sample in the
Markov chain is generated by starting at the last sample, applying a
random momentum to determine initial kinetic energy, then simulating
the path of the particle in the field.  Standard \HMC runs the
simulation for a fixed number of discrete steps of a fixed step size,
whereas \NUTS adjusts the number of steps on each iteration and allows
varying step sizes per parameter.



\subsection{Step-Size Adaptation during Warmup}

In addition to standard \HMC, \Stan implements an adaptive version of
\HMC, the No-U-Turn Sampler (\NUTS).  By default, \NUTS automatically
tunes a step sizes during warmup.  A global step size is optimized for
a target Metropolis-Hastings reject rate using dual averaging; see
\citep{Nesterov:2009} for details of dual averaging and
\citep{Hoffman-Gelman:2011,Hoffman-Gelman:2013} 
for details of its use in \Stan.  For
information on run-time configuration of step-size adaptation, see
\refsection{stan-command-line-options}.  Then step sizes per parameter
are estimated during warmup.  

\subsection{Number of Steps}

During sampling, \NUTS adapts the number of leapfrog steps (i.e., the
simulation time), using a geometric criterion that stops a trajectory
when it begins to head back in the direction of the initial state.
Once a trajectory is stopped, \NUTS uses slice sampling to select a
state along the trajectory as the next proposal.

Although \Stan only samples continuous variables, its language is
expressive enough to allow most discrete variables to be marginalized
out; see \refchapter{mixture-modeling} for examples.

\subsection{Detailed Balance}

\HMC uses a Metropolis rejection step to ensure detailed balance of
the resulting Markovian system; for details, see \citep{Neal:2011}.
\NUTS uses a form of slice sampling which guarantees detailed balance;
for details, see \citep{Hoffman-Gelman:2011,Hoffman-Gelman:2013}.%
%
\footnote{A transition density $\phi(\omega'|\omega)$ and density
  $\pi(\omega)$ over state space $\Omega$ satisfy detailed balance if
  and only if for all $\omega, \omega' \in \Omega$,
\[
\pi(\omega) \, \phi(\omega'|\omega)
=
\pi(\omega') \, \phi(\omega | \omega').
\]
Detailed balance ensures stationarity of the transition density $\phi$
with respect to the equilibrium density $\pi$, so that
\[
\pi(\omega') = \int_{\Omega} \pi(\omega) \, \phi(\omega'|\omega) \, d\omega.
\]
} 
%
This adjustment treats the momentum term of the Hamiltonian as an
auxiliary variable, and the only reason for rejecting a sample will be
discretization error in computing the Hamiltonian.  In practice, the
possibility of rejecting a proposed update means that one or more
duplicate samples may appear in the chain; the resulting loss in
inferential power is accounted for with effective sample size
calculations as described in \refsection{effective-sample-size}.


\chapter{Transformations of Variables}\label{variable-transforms.chapter}

\noindent
To avoid having to deal with constraints while simulating the
Hamiltonian dynamics during sampling, every (multivariate) parameter
in a \Stan model is transformed to an unconstrained variable behind
the scenes by the model compiler.  The transform is based on the
constraints, if any, in the parameter's definition.  Scalars or the
scalar values in vectors, row vectors or matrices may be constrained
with lower and/or upper bounds.  Vectors may alternatively be
constrained to be ordered, positive ordered, or simplexes.  Matrices
may be constrained to be correlation matrices or covariance matrices.
This chapter provides a definition of the transforms used for each
type of variable.

\Stan converts models to \Cpp classes which define probability
functions with support on all of $\reals^K$, where $K$ is the number
of unconstrained parameters needed to define the constrained
parameters defined in the program.  The \Cpp classes also include
code to transform the parameters from unconstrained to constrained and
apply the appropriate Jacobians.


\section{Changes of Variables}\label{change-of-variables.section}

The support of a random variable $X$ with density $p_X(x)$ is that
subset of values for which it has non-zero density,
%
\[
\mbox{supp}(X) = \{ x | p_X(x) > 0 \}.
\]

If $f$ is a total function defined on the support of $X$, then $Y =
f(X)$ is a new random variable.  This section shows how to compute the
probability density function of $Y$ for well-behaved transforms $f$.
The rest of the chapter details the transforms used by \Stan.



\subsection{Univariate Changes of Variables}\label{uni-change-of-variables.section}

Suppose $X$ is one dimensional and $f: \mbox{supp}(X) \rightarrow
\reals$ is a one-to-one, monotonic function with a differentiable
inverse $f^{-1}$.  Then the density of $Y$ is given by
%
\[
p_Y(y) = p_X(f^{-1}(y))  
         \,
         \left| \, \frac{d}{dy} f^{-1}(y)\, \right|.
\]
The absolute derivative of the inverse transform measures how the
scale of the transformed variable changes with respect to the
underlying variable.


\subsection{Multivariate Changes of Variables}\label{multi-change-of-variables.section}

The multivariate generalization of an absolute derivative is a
Jacobian, or more fully the absolute value of the determinant of the
Jacobian matrix of the transform.  The Jacobian matrix measures the change of
each output variable relative to every input variable and the absolute
determinant uses that to determine the differential change in volume
at a given point in the parameter space.

Suppose $X$ is a $K$-dimensional random variable with probability
density function $p_X(x)$.  A new random variable $Y = f(X)$ may be
defined by transforming $X$ with a suitably well-behaved function $f$.
It suffices for what follows to note that if $f$ is one-to-one
and its inverse $f^{-1}$ has a well-defined Jacobian, then the
density of $Y$ is
%
\[
p_Y(y) = p_X(f^{-1}(y)) \, \left| \, \det \, J_{f^{-1}}(y) \, \right|,
\]
%
where $\det{}$ is the matrix determinant operation and $J_{f^{-1}}(y)$
is the Jacobian matrix of $f^{-1}$ evaluated at $y$.  Taking $x =
f^{-1}(y)$, the Jacobian matrix is defined by
\[
J_{f^{-1}}(y) = 
\left[
\begin{array}{ccc}\displaystyle
\frac{\partial x_1}{\partial y_1}
& \cdots
& \displaystyle \frac{\partial x_1}{\partial y_{K}}
\\[6pt]
\vdots & \vdots & \vdots
\\
\displaystyle\frac{\partial x_{K}}{\partial y_1}
& \cdots
& \displaystyle\frac{\partial x_{K}}{\partial y_{K}}
\end{array}
\right].
\]
%
If the Jacobian matrix is triangular, the determinant reduces to the
product of the diagonal entries,
%
\[
\det \, J_{f^{-1}}(y)
= \prod_{k=1}^K \frac{\partial x_k}{\partial y_k}.
\]
%
Triangular matrices naturally arise in situations where the variables
are ordered, for instance by dimension, and each variable's
transformed value depends on the previous variable's transformed
values.  Diagonal matrices, a simple form of triangular matrix, arise
if each transformed variable only depends on a single untransformed
variable.

\section{Lower Bounded Scalar}

\Stan uses a logarithmic transform for lower and upper bounds.  

\subsection{Lower Bound Transform}

If a variable $X$ is declared to have lower bound $a$, it is
transformed to an unbounded variable $Y$, where
%
\[
Y = \log(X - a).
\]

\subsection{Lower Bound Inverse Transform}
%
The inverse of the lower-bound transform maps an unbounded
variable $Y$ to a variable $X$ that is bounded below by $a$ by
%
\[
X = \exp(Y) + a.
\]

\subsection{Absolute Derivative of the Lower Bound Inverse Transform}

The absolute derivative of the inverse transform is
\[
\left| \,
\frac{d}{dy} \left( \exp(y) + a \right)
\, \right|
= \exp(y).
\]
Therefore, given the density $p_X$ of $X$, the density of $Y$ is 
%
\[
p_Y(y) 
= p_X\!\left( \exp(y) + a \right) \cdot \exp(y).
\]


\section{Upper Bounded Scalar}

\Stan uses a negated logarithmic transform for upper bounds.

\subsection{Upper Bound Transform}

If a variable $X$ is declared to have an upper bound $b$, it is
transformed to the unbounded variable $Y$ by
%
\[
Y = \log(b - X).
\]

\subsection{Upper Bound Inverse Transform}
%
The inverse of the upper bound transform converts the unbounded
variable $Y$ to the variable $X$ bounded above by $b$ through
%
\[
X = b - \exp(Y).
\]

\subsection{Absolute Derivative of the Upper Bound Inverse Transform}

The absolute derivative of the inverse of the upper bound transform is 
\[
\left| \,
\frac{d}{dy} \left( b - \exp(y) \right)
\, \right|
= \exp(y).
\]
%
Therefore, the density of the unconstrained variable $Y$ is defined in
terms of the density of the variable $X$ with an upper bound of $b$ by
%
\[
p_Y(y) 
 =   p_X \!\left( b - \exp(y) \right) \cdot \exp(y).
\]


\section{Lower and Upper Bounded Scalar}

For lower and upper-bounded variables, \Stan uses a scaled and
translated log-odds transform.

\subsection{Log Odds and the Logistic Sigmoid}

The log-odds function is defined for $u \in (0,1)$ by
%
\[
\mbox{logit}(u) = \log \frac{u}{1 - u}.
\]
% 
The inverse of the log odds function is the logistic sigmoid, defined 
for $v \in (-\infty,\infty)$ by
%
\[
\mbox{logit}^{-1}(v) = \frac{1}{1 + \exp(-v)}.
\]
% 
The derivative of the logistic sigmoid is
%
\[
\frac{d}{dy} \mbox{logit}^{-1}(y) 
= \mbox{logit}^{-1}(y) \cdot \left( 1 - \mbox{logit}^{-1}(y) \right).
\]

\subsection{Lower and Upper Bounds Transform}

For variables constrained to be in the open interval $(a,b)$, \Stan
uses a scaled and translated log-odds transform.  If variable $X$ is
declared to have lower bound $a$ and upper bound $b$, then it is
transformed to a new variable $Y$, where
%
\[
Y = \mbox{logit} \left( \frac{X - a}{b - a} \right).
\]
%

\subsection{Lower and Upper Bounds Inverse Transform}

The inverse of this transform is
%
\[
X = a + (b - a) \cdot \mbox{logit}^{-1}(Y).
\]
%

\subsection{Absolute Derivative of the Lower and Upper Bounds Inverse
  Transform}

The absolute derivative of the inverse transform is given by
\[
\left|  
  \frac{d}{dy} 
    \left( 
      a + (b - a) \cdot \mbox{logit}^{-1}(y)
    \right)
  \right|
= (b - a)
    \cdot \mbox{logit}^{-1}(y)
    \cdot \left( 1 - \mbox{logit}^{-1}(y) \right).
\]
Therefore, the density of the transformed variable $Y$ is
%
\[
p_Y(y) 
= 
 p_X \! \left( a + (b - a) \cdot \mbox{logit}^{-1}(y) \right)
    \cdot (b - a)
    \cdot \mbox{logit}^{-1}(y)
    \cdot \left( 1 - \mbox{logit}^{-1}(y) \right).
\]
%
Despite the apparent complexity of this expression, most of the terms
are repeated and thus only need to be evaluated once.  Most
importantly, $\mbox{logit}^{-1}(y)$ only needs to be evaluated once,
so there is only one call to $\exp(-y)$.


\section{Ordered Vector}

For some modeling tasks, a vector-valued random variable $X$ is
required with support on ordered sequences.  One example is the set of
cut points in ordered logistic regression (see \refsection{ordered-logistic}).

In constraint terms, an ordered $K$-vector $x \in \reals^K$ satisfies
\[
x_k < x_{k+1}
\]
%
for $k \in \setlist{1,\ldots,K-1}$.


\subsection{Ordered Transform}

\Stan's transform follows the constraint directly.  It maps an
increasing vector $x \in \reals^{K}$ to an unconstrained vector $y \in
\reals^K$ by setting
%
\[
y_k
= 
\left\{
\begin{array}{ll}
x_1 & \mbox{if } k = 1, \mbox{ and}
\\[4pt]
\log \left( x_{k} - x_{k-1} \right) & \mbox{if } 1 < k \leq K.
\end{array}
\right.
\] 

\subsection{Ordered Inverse Transform}

The inverse transform for an unconstrained $y \in \reals^K$ to an
ordered sequence $x \in \reals^K$ is defined by the recursion
%
\[
x_k
= 
\left\{
\begin{array}{ll} 
y_1 & \mbox{if } k = 1, \mbox{ and}
\\[4pt]
x_{k-1} + \exp(y_k) & \mbox{if } 1 < k \leq K.
\end{array}
\right.
\]
%
$x_k$ can also be expressed iteratively as
\[
x_k = y_1 + \sum_{k'=2}^k \exp(y_{k'}).
\]

\subsection{Absolute Jacobian Determinant of the Ordered
  Inverse Transform}

The Jacobian of the inverse transform $f^{-1}$ is lower triangular,
with diagonal elements for $1 \leq k \leq K$ of
\[
J_{k,k} = 
\left\{
\begin{array}{ll} 
1 & \mbox{if } k = 1, \mbox{ and}
\\[4pt]
\exp(y_k) & \mbox{if } 1 < k \leq K.
\end{array}
\right.
\]
%
Because $J$ is triangular, the absolute Jacobian determinant is
%
\[
\left| \, \det \, J \, \right|
\ = \ 
\left| \, \prod_{k=1}^K J_{k,k} \, \right|
\ = \ 
\prod_{k=2}^K \exp(y_k).
\]

Putting this all together, if $p_X$ is the density of $X$, then the
transformed variable $Y$ has density $p_Y$ given by
%
\[
p_Y(y)
= p_X(f^{-1}(y)) 
\
\prod_{k=2}^K \exp(y_k).
\]


\section{Unit Simplex}

Variables constrained to the unit simplex show up in multivariate
discrete models as both parameters (categorical and multinomial) and
as variates generated by their priors (Dirichlet and multivariate
logistic).

The unit $K$-simplex is the set of points $x \in \reals^K$ such that
for $1 \leq k \leq K$, 
\[ 
x_k > 0,
\] 
and
\[
\sum_{k=1}^K x_k = 1.
\]
%   
An alternative definition is to take the convex closure of the
vertices.  For instance, in 2-dimensions, the simplex vertices are the
extreme values $(0,1)$, and $(1,0)$ and the unit 2-simplex is the line
connecting these two points; values such as $(0.3,0.7)$ and
$(0.99,0.01)$ lie on the line.  In 3-dimensions, the basis is
$(0,0,1)$, $(0,1,0)$ and $(1,0,0)$ and the unit 3-simplex is the
boundary and interior of the triangle with these vertices.  Points in
the 3-simplex include $(0.5,0.5,0)$, $(0.2,0.7,0.1)$ and all other
triplets of non-negative values summing to 1.  

As these examples illustrate, the simplex always picks out a subspace
of $K-1$ dimensions from $\reals^K$.  Therefore a point $x$ in the
$K$-simplex is fully determined by its first $K-1$ elements $x_1, x_2,
\ldots, x_{K-1}$, with
%
\[
x_K = 1 - \sum_{k=1}^{K-1} x_k.
\]
%

\subsection{Unit Simplex Inverse Transform}

Stan's unit simplex inverse transform may be understood using the
following stick-breaking metaphor.%
%
\footnote{For an alternative derivation of the same transform using
  hyperspherical coordinates, see \citep{Betancourt:2010}.}
%
\begin{quote}
  Take a stick of unit length (i.e., length 1).  Break a piece off and
  label it as $x_1$, and set it aside.  Next, break a piece off what's
  left, label it $x_2$, and set it aside.  Continue doing this until
  you have broken off $K-1$ pieces labeled $(x_1,\ldots,x_{K-1})$.
  Label what's left of the original stick $x_K$.  The vector $x =
  (x_1,\ldots,x_{K})$ is obviously a unit simplex because each piece
  has non-negative length and the sum of their lengths is 1.
\end{quote}
%
This full inverse mapping requires the breaks to be represented as the
fraction in $(0,1)$ of the original stick that is broken off.  These
break ratios are themselves derived from unconstrained values in
$(-\infty,\infty)$ using the inverse logit transform as described
above for unidimensional variables with lower and upper bounds.

More formally, an intermediate vector $z \in \reals^{K-1}$, whose
coordinates $z_k$ represent the proportion of the stick broken off in
step $k$, is defined elementwise for $1 \leq k < K$ by
%
\[
z_k = \mbox{logit}^{-1} \left( y_k 
                             + \log \left( \frac{1}{K - k}
                                            \right)
                       \right).
\]
%
The logit term
$\log\left(\frac{1}{K-k}\right) (i.e., \mbox{logit}\left(\frac{1}{K-k+1}\right)$) in
the above definition adjusts the transform so that a
zero vector $y$ is mapped to the simplex $x = (1/K,\ldots,1/K)$.  For instance, if
$y_1 = 0$, then $z_1 = 1/K$; if $y_2 = 0$, then $z_2 = 1/(K-1)$; and
if $y_{K-1} = 0$, then $z_{K-1} = 1/2$.  

The break proportions $z$ are applied to determine the stick sizes and
resulting value of $x_k$ for $1 \leq k < K$ by
%
\[
x_k = 
\left( 1 - \sum_{k'=1}^{k-1} x_{k'} \right) z_k.
\]
%
The summation term represents the length of the original stick left at
stage $k$.  This is multiplied by the break proportion $z_k$ to yield
$x_k$.  Only $K-1$ unconstrained parameters are required, with
the last dimension's value $x_K$ set to the length of the remaining
piece of the original stick,
\[
x_K = 1 - \sum_{k=1}^{K-1} x_k.
\]

\subsection{Absolute Jacobian Determinant of the Unit-Simplex
  Inverse Transform}

The Jacobian $J$ of the inverse transform $f^{-1}$ is
lower-triangular, with diagonal entries
\[
J_{k,k}
=
\frac{\partial x_k}{\partial y_k}
=
\frac{\partial x_k}{\partial z_k} \,
\frac{\partial z_k}{\partial y_k},
\]
%
where
\[
\frac{\partial z_k}{\partial y_k} 
= \frac{\partial}{\partial y_k} 
   \mbox{logit}^{-1} \left(
                       y_k + \log \left( \frac{1}{K-k}
                                          \right)
                    \right)
= z_k (1 - z_k),
\]
%
and
%
\[
\frac{\partial x_k}{\partial z_k}
=
\left( 
  1 - \sum_{k' = 1}^{k-1} x_{k'}
   \right)
.
\]
%
This definition is recursive, defining $x_k$ in terms of
$x_{1},\ldots,x_{k-1}$.

Because the Jacobian $J$ of $f^{-1}$ is lower triangular and positive, its
absolute determinant reduces to
%
\[
\left| \, \det J \, \right|
\ = \
\prod_{k=1}^{K-1} J_{k,k}
\ = \
\prod_{k=1}^{K-1} 
z_k
\, 
(1 - z_k)
\
\left(
1 - \sum_{k'=1}^{k-1} x_{k'}
\right)
.
\]
%
Thus the transformed variable $Y = f(X)$ has a density given by
%
\[
p_Y(y) 
= p_X(f^{-1}(y))
\,
\prod_{k=1}^{K-1} 
z_k
\, 
(1 - z_k)
\
\left(
1 - \sum_{k'=1}^{k-1} x_{k'}
\right)
.
\]
%
Even though it is expressed in terms of intermediate values $z_k$,
this expression still looks more complex than it is. The exponential
function need only be evaluated once for each unconstrained parameter
$y_k$; everything else is just basic arithmetic that can be computed
incrementally along with the transform.

\subsection{Unit Simplex Transform}

The transform $Y = f(X)$ can be derived by reversing the stages of the
inverse transform.  Working backwards, given the break proportions
$z$, $y$ is defined elementwise by
%
\[
y_k 
= \mbox{logit}(z_k)
- \mbox{log}\left(
   \frac{1}{K-k}
   \right)
.
\]
%
The break proportions $z_k$ are defined to be the ratio of $x_k$ to
the length of stick left after the first $k-1$ pieces have been broken
off, 
%
\[
z_k 
= \frac{x_k}
       {1 - \sum_{k' = 1}^{k-1} x_{k'}}
.
\]

\section{Unit Vector}
Unit vectors show up in directional statistics.

The $n$-sphere is the set of points $x \in \reals^n$ such that 
\[
\Vert x \Vert^2 = \sum_{i=1}^n x_i^2 = 1\ .
\]

\subsection{Unit Vector Inverse Transform}

To parametrize unit length vectors, we use hyperspherical coordinates.
The unconstrained vector $y \in \reals^{n-1}$ is a set of angles which
relates to the unit vector as follows:
\begin{eqnarray*}
x_1 & = & \cos(y_1) \\
x_2 & = & \cos(y_2) \sin(y_1) \\
x_3 & = & \cos(y_3) \sin(y_1) \sin(y_2) \\
& \vdots & \\
x_i & = & \cos(y_i) \prod_{j=1}^{i-1} \sin(y_j) \\
& \vdots & \\
x_n & = & \prod_{j=1}^{n-1} \sin(y_j).
\end{eqnarray*}
Note that, in practice, we use $y_i = \hat{y}_i + \frac{\pi}{2}$ and use $\hat{y}_i$ as the unconstrained parameters to avoid a singularity at
$y_i = 0$.


\subsection{Absolute Jacobian Determinant of the Unit Vector
  Inverse Transform}
To derive the determinant of the Jacobian we first add a radius coordinate
$r=1$ which multiplies the vector $x$.
The Jacobian, $J$, can be shown to be lower triangular, so its
determinant is just the product of diagonal entries and the 
absolute value of the determinant is
\[
\left| \, \det J \, \right| = \left|r^{n-1} \sin^{n-2}(y_1) \sin^{n-3}(y_2) ... \sin(y_{n-2})\right| .
\]


\section{Correlation Matrices}

A $K \times K$ correlation matrix $x$ must be is a symmetric, so that
%
\[
x_{k,k'} = x_{k',k}
\]
for all $k,k' \in \setlist{1,\ldots,K}$, it must have a unit diagonal,
so that 
\[
x_{k,k} = 1
\]
for all $k \in \setlist{1,\ldots,K}$, and it must be positive
definite, so that for every non-zero $K$-vector $a$,
\[
a^{\top} x a > 0.
\]
To deal with this rather complicated constraint, \Stan implements the
transform of \cite{LewandowskiKurowickaJoe:2009}.  The number of free
parameters required to specify a $K \times K$ correlation matrix is $K
\choose 2$.

\subsection{Correlation Matrix Inverse Transform}

It is easiest to specify the inverse, going from its $K \choose 2$
parameter basis to a correlation matrix.  The basis will actually be
broken down into two steps.  To start, suppose $y$ is a vector
containing $K \choose 2$ unconstrained values.  These are first
transformed via the bijective function $\tanh : \reals \rightarrow
(0,1)$
%
\[
\tanh x = \frac{\exp(2x) - 1}{\exp(2x) + 1}.
\]
%
Then, define a $K \times K$ matrix $z$, the upper triangular values of
which are filled by row with the transformed values.  For example, in
the $4 \times 4$ case, there are ${4 \choose 2}$ values arranged as
%
\[
z 
=
\left[
\begin{array}{cccc}
0 & \tanh y_1 & \tanh y_2 & \tanh y_4
\\
0 & 0 & \tanh y_3 & \tanh y_5
\\
0 & 0 & 0 & \tanh y_6
\\
0 & 0 & 0 & 0
\end{array}
\right]
.
\]
%
Lewandowski et al.\ show how to bijectively map the array $z$ to a correlation
matrix $x$.  The entry $z_{i,j}$ for $i < j$ is interpreted as the
canonical partial correlation (\CPC) between $i$ and $j$, which is the
correlation between $i$'s residuals and $j$'s residuals when both $i$
and $j$ are regressed on all variables $i'$ such that $i'< i$.
In the case of $i=1$, there are no earlier variables, 
so $z_{1,j}$ is just the Pearson correlation between $i$ and $j$.

In \Stan, the \LKJ transform is reformulated in terms of a Cholesky factor $w$
of the final correlation matrix, defined for $1 \leq i,j \leq K$ by
%
\[
w_{i,j} = 
\left\{
\begin{array}{cl}
%
0 & \mbox{if } i > j,
\\[4pt]
1 & \mbox{if } 1 = i = j,
\\[12pt]
\prod_{i'=1}^{i - 1} \left( 1 - z_{i'\!,\,j}^2 \right)^{1/2}
& \mbox{if } 1 < i = j,
\\[12pt]
z_{i,j} & \mbox{if } 1 = i < j, \mbox{ and}
\\[12pt]
z_{i,j} \, \prod_{i'=1}^{i-1} \left( 1 - z_{i'\!,\,j}^2 \right)^{1/2}
& \mbox{ if } 1 < i < j.
%
\end{array}
\right.
\]
%
This does not require as much computation per matrix entry as it may appear; 
calculating the rows in terms of earlier rows yields the more
manageable expression 
%
\[
w_{i,j} = 
\left\{
\begin{array}{cl}
%
0 & \mbox{if } i > j,
\\[4pt]
1 & \mbox{if } 1 = i = j, 
\\[8pt]
z_{i,j} & \mbox{if } 1 = i < j, \mbox{ and}
\\[8pt]
z_{i,j} \ w_{i-1,j} \left( 1 - z_{i-1,j}^2 \right)^{1/2}
& \mbox{ if } 1 < i \leq j.
%
\end{array}
\right.
\]
Given the upper-triangular Cholesky factor $w$, the final correlation
matrix is
\[
x = w^{\top} w.
\]

Lewandowski et al.\ show that the determinant of the correlation
matrix can be defined in terms of the canonical partial correlations
as
%
\[
\mbox{det} \, x = \prod_{i=1}^{K-1} \ \prod_{j=i+1}^K \ (1 - z_{i,j}^2)
 = \prod_{1 \leq i < j \leq K} (1 - z_{i,j}^2),
\]

\subsection{Absolute Jacobian Determinant of the Correlation
  Matrix Inverse Transform}

The only description so far is in the \Stan transform code.

\subsection{Correlation Matrix Transform}

The correlation transform is defined by reversing the steps of the
inverse transform defined in the previous section.  

Starting with a correlation matrix $x$, the first step is to find the
unique upper triangular $w$ such that $x = w w^{\top}$.  Because $x$
is positive definite, this can be done by applying the Cholesky
decomposition,
\[
w = \mbox{chol}(x).
\]


The next step from the Cholesky factor $w$ back to the array $z$ of
{\CPC}s is simplified by the ordering of the elements in the
definition of $w$, which when inverted yields
%
\[
z_{i,j} =
\left\{
\begin{array}{cl}
0 & \mbox{if } i \leq j,
\\[8pt]
w_{i,j} & \mbox{if } 1 = i < j, \mbox{ and}
\\[8pt]
{w_{i,j}}
\
\prod_{i'=1}^{i-1} \left( 1 - z_{i'\!,j}^2 \right)^{-2}
& \mbox{if } 1 < i < j.
\end{array}
\right.
\]
The final stage of the transform reverses the hyperbolic tangent
transform, which is defined by 
\[
\tanh^{-1} v = \frac{1}{2} \log \left( \frac{1 + v}{1 - v} \right).
\]
The inverse hyperbolic tangent function, $\tanh^{-1}$, is also called
the Fisher transformation.


\section{Covariance Matrices}

A $K \times K$ matrix is a covariance matrix if it is symmetric and
positive definite (see the previous section for definitions).  It
requires $K + {K \choose 2}$ free parameters to specify a $K \times K$
covariance matrix.


\subsection{Covariance Matrix Transform}

\Stan's covariance transform is based on a Cholesky decomposition
composed with a log transform of the positive-constrained diagonal
elements.%
%
\footnote{An alternative to the transform in this section, which can
  be coded directly in \Stan, is to parameterize a covariance matrix
  as a scaled correlation matrix.  An arbitrary $K \times K$
  covariance matrix $\Sigma$ can be expressed in terms of a $K$-vector
  $\sigma$ and correlation matrix $\Omega$ as
  \[
  \Sigma = \mbox{diag}(\sigma) \times \Omega \times \mbox{diag}(\sigma),
  \]
  so that each entry is just a deviation-scaled correlation,
  \[
  \Sigma_{m,n} = \sigma_m \times \sigma_n \times \Omega_{m,n}.
  \]
}

If $x$ is a covariance matrix (i.e., a symmetric, positive definite
matrix), then there is a unique lower-triangular matrix $z =
\mbox{chol}(x)$ with positive diagonal entries, called a Cholesky
factor, such that
\[
x = z \, z^{\top}.
\]
The off-diagonal entries of the Cholesky factor $z$ are unconstrained,
but the diagonal entries $z_{k,k}$ must be positive for $1 \leq k
\leq K$.

To complete the transform, the diagonal is log-transformed to produce
a fully unconstrained lower-triangular matrix $y$ defined by
\[
y_{m,n} = 
\left\{
\begin{array}{cl}
0 & \mbox{if } m < n,
\\[4pt]
\log z_{m,m} & \mbox{if } m = n, \mbox{ and}
\\[4pt]
z_{m,n} & \mbox{if } m > n.
\end{array}
\right.
\]

\subsection{Covariance Matrix Inverse Transform}

The inverse transform reverses the two steps of the transform.
Given an unconstrained lower-triangular $K \times K$ matrix $y$, the
first step is to recover the intermediate matrix $z$ by reversing the
log transform,
\[
z_{m,n} = 
\left\{
\begin{array}{cl}
0 & \mbox{if } m < n,
\\[4pt]
\exp(y_{m,m}) & \mbox{if } m = n, \mbox{ and}
\\[4pt]
y_{m,n} & \mbox{if } m > n.
\end{array}
\right.
\]
%
The covariance matrix $x$ is recovered from its Cholesky factor $z$ by
taking
%
\[
x = z \, z^{\top}.
\]

\subsection{Absolute Jacobian Determinant of the Covariance
  Matrix Inverse Transform}

The Jacobian is the product of the Jacobians of the exponential
transform from the unconstrained lower-triangular matrix $y$ to matrix
$z$ with positive diagonals and the product transform from the
Cholesky factor $z$ to $x$.

The transform from unconstrained $y$ to Cholesky factor $z$ has a
diagonal Jacobian matrix, the absolute determinant of which is thus
%
\[
\prod_{k=1}^K  \frac{\partial}{\partial_{y_{k,k}}} \, \exp(y_{k,k})
\ = \ 
\prod_{k=1}^K \exp(y_{k,k})
\ = \
\prod_{k=1}^K z_{k,k}.
\]

The Jacobian matrix of the second transform from the Cholesky factor $z$ to
the covariance matrix $x$ is also triangular, with diagonal entries
corresponding to pairs $(m,n)$ with $m \geq n$, defined by
\[
\frac{\partial}{\partial z_{m,n}}
\left( z \, z^{\top} \right)_{m,n}
\ = \
\frac{\partial}{\partial z_{m,n}}
\left( \sum_{k=1}^K z_{m,k} \, z_{n,k} \right)
\ = \
\left\{
\begin{array}{cl}
2 \, z_{n,n} & \mbox{if } m = n \mbox{ and }
\\[4pt]
z_{n,n} & \mbox{if } m > n.
\end{array}
\right.
\]
%
The absolute Jacobian determinant of the second transform is thus
\[
2^{K} 
\
\prod_{m = 1}^{K} \ \prod_{n=1}^{m} z_{n,n}.
\]
Finally, the full absolute Jacobian determinant of the inverse
of the covariance matrix transform from the unconstrained lower-triangular 
$y$ to a symmetric, positive definite matrix $x$ is the product of the
Jacobian determinants of the exponentiation and product transforms,
\[
2^{K} 
\
\left( \prod_{k=1}^K z_{k,k} \right)
\left( \prod_{m = 1}^{K} \ \prod_{n=1}^{m} z_{n,n} \right)
\ = \
2^K
\, \prod_{k=1}^K z_{k,k}^{K-k+2}.
\]

Let $f^{-1}$ be the inverse transform from a $K + {K \choose
  2}$-vector $y$ to the $K \times K$ covariance matrix $x$.  A density
function $p_X(x)$ defined on $K \times K$ covariance matrices is
transformed to the density $p_Y(y)$ over $K + {K \choose 2}$ vectors
$y$ by
\[
p_Y(y) = p_X(f^{-1}(y)) \ 2^K \ \prod_{k=1}^K z_{k,k}^{K-k+2}.
\]

\section{Cholesky Factors of Covariance Matrices}

An $M \times N$ matrix is a Cholesky factor of a covariance matrix
if it is lower triangular, the diagonal entries are positive, and $M
\geq N$.  It requires $N + {N \choose 2} + (M - N)N$ parameters.

\subsection{Cholesky Factor of Covariance Matrix Transform}

Stan's Cholesky factor transform only requires the first step of the
covariance matrix transform, namely log transforming the positive
diagonal elements.  Suppose $x$ is an $M \times N$ Cholesky factor.
The above-diagonal entries are zero, the diagonal entries are
positive, and the below-diagonal entries are unconstrained.  The
transform required is thus
%
\[
y_{m,n} = 
\left\{
\begin{array}{cl}
0 & \mbox{if } m < n,
\\[4pt]
\log x_{m,m} & \mbox{if } m = n, \mbox{ and}
\\[4pt]
x_{m,n} & \mbox{if } m > n.
\end{array}
\right.
\]

\subsection{Cholesky Factor of Covariance Matrix Inverse Transform}

The inverse transform need only invert the logarithm with an
exponentiation.  If $y$ is the unconstrained matrix representation,
then the elements of the constrained matrix $x$ is defined by
\[
x_{m,n} =
\left\{
\begin{array}{cl}
0 & \mbox{if } m < n,
\\[4pt]
\exp(y_{m,m}) & \mbox{if } m = n, \mbox{ and}
\\[4pt]
y_{m,n} & \mbox{if } m > n.
\end{array}
\right.
\]

\subsection{Absolute Jacobian Determinant of Cholesky Factor Inverse Transform}

The transform has a diagonal Jacobian matrix, the absolute determinant
of which is
%
\[
\prod_{n=1}^N  \frac{\partial}{\partial_{y_{n,n}}} \, \exp(y_{n,n})
\ = \ 
\prod_{n=1}^N \exp(y_{n,n})
\ = \
\prod_{n=1}^N x_{n,n}.
\]

Let $x = f^{-1}(y)$ be the inverse transform from a $N + {N \choose 2}
+ (M - N)N$ vector to an $M \times N$ Cholesky factor for a covariance
matrix $x$ defined in the previous section.  A density function
$p_X(x)$ defined on $M \times N$ Cholesky factors of covariance
matrices is transformed to the density $p_Y(y)$ over $N + {N \choose
  2} + (M - N)N$ vectors $y$ by
%
\[
p_Y(y) = p_X(f^{-1}(y)) \prod_{N=1}^N x_{n,n}.
\]

% \chapter{Generated C++ Model Class}

% The \Cpp class generated by \code{stanc} for a model (see
% \refsection{stanc}) may be used in contexts other than the \Stan
% samplers.  Similarly, a model can be hand-coded in \Cpp and plugged
% into \Stan's samplers.  This chapter provides a sketch of the code
% generated for models and how to use it.

% \section{Log Probability and Gradient Base Class}

% \Stan's samplers require models that extend the abstract base class
% \code{stan::model::prob\_grad}.  The constructor for this class is as
% follows.
% %
% \begin{verbatim}
% prob_grad(size_t num_params_r);
% \end{verbatim}
% %
% The argument specifies the number of real parameters in the model.

% From the sampler's perspective, the model is just a log probability
% function and gradient, which are computed using the following method.
% %
% \begin{verbatim}
% virtual double 
% grad_log_prob(const vector<double>& params_r, 
%               vector<double>& gradient) = 0;
% \end{verbatim}
% %
% The first argument is the parameter vector at which the log
% probability function will be evaluated.  The second argument is filled
% with the gradient.  The return value is the value of the log
% probability function.  It works best for \Stan's samplers if the
% probability function has unconstrained support, so that all returned
% values are finite.%
% %
% \footnote{\Stan's samplers will not gripe if given zero probabilities
%   (i.e., negative infinity log probabilities), but the sampler may
%   not sample well depending on the shape of the probability function.}
% %
% An implementation of this class can be plugged directly into \Stan's
% samplers, standard \HMC and \NUTS.

% \section{Algorithmic Differentiation Base Class}

% \Stan provides an extension \code{stan::model::prob\_grad\_ad} of the
% abstract base class \code{stan::model::prob\_grad} that implements the
% \code{grad\_log\_prob} method using algorithmic differentiation.  It
% has the same constructor arguments as the base class,
% \begin{quote}
% \begin{Verbatim}
% prob_grad_ad(size_t num_params_r);
% \end{Verbatim}
% \end{quote}

% The gradient implementation class a pure virtual method which
% implements the log probability function in a way that allows it to be
% automatically differentiated.  This method is just the log probability
% function defined in terms of \Stan's algorithmic gradient variables,
% \code{stan::agrad::var}.  
% \begin{quote}
% \begin{Verbatim}
% virtual var
% log_prob(const vector<var>& params_r);
% \end{Verbatim}
% \end{quote}
% %
% The simplest way to implement this method is to provide a templated
% log probability function definition in the implementing class,
% %
% \begin{quote}
% \begin{Verbatim}
% template <typename T>
% virtual T
% log_prob(const vector<T>& params_r);
% \end{Verbatim}
% \end{quote}
% %

% The \code{prob\_grad\_ad} class computes gradients using accurate and
% efficient reverse-mode algorithmic differentiaton.  The cost of
% computing the gradient is a small multiple of the cost of computing
% the log probability.  The cost inovlves a bounded amount of extra
% bookkeeping for each subexpression involved in computing the log
% probability.  Unlike in the calculation of finite differences, the
% extra bookkeeping is not dependent on the dimensionality of the
% parameter vector.


