<!DOCTYPE html>
<!-- Generated by pkgdown: do not edit by hand --><html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>An Introduction to BayesHMM • BayesHMM</title>
<!-- jquery --><script src="https://code.jquery.com/jquery-3.1.0.min.js" integrity="sha384-nrOSfDHtoPMzJHjVTdCopGqIqeYETSXhZDFyniQ8ZHcVy08QesyHcnOUpMpqnmWq" crossorigin="anonymous"></script><!-- Bootstrap --><link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" crossorigin="anonymous"></script><!-- Font Awesome icons --><link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.6.3/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-T8Gy5hrqNKT+hzMclPo118YTQO6cYprQmhrYwIiQ/3axmI1hQomh7Ud2hPOy8SP1" crossorigin="anonymous">
<!-- clipboard.js --><script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/1.7.1/clipboard.min.js" integrity="sha384-cV+rhyOuRHc9Ub/91rihWcGmMmCXDeksTtCihMupQHSsi8GIIRDG0ThDc3HGQFJ3" crossorigin="anonymous"></script><!-- sticky kit --><script src="https://cdnjs.cloudflare.com/ajax/libs/sticky-kit/1.1.3/sticky-kit.min.js" integrity="sha256-c4Rlo1ZozqTPE2RLuvbusY3+SU1pQaJC0TjuhygMipw=" crossorigin="anonymous"></script><!-- pkgdown --><link href="../pkgdown.css" rel="stylesheet">
<script src="../pkgdown.js"></script><meta property="og:title" content="An Introduction to BayesHMM">
<meta property="og:description" content="">
<meta name="twitter:card" content="summary">
<!-- mathjax --><script src="https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script><!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
</head>
<body>
    <div class="container template-article">
      <header><div class="navbar navbar-default navbar-fixed-top" role="navigation">
  <div class="container">
    <div class="navbar-header">
      <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar">
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <span class="navbar-brand">
        <a class="navbar-link" href="../index.html">BayesHMM</a>
        <span class="label label-default" data-toggle="tooltip" data-placement="bottom" title="Released package">0.0.1</span>
      </span>
    </div>

    <div id="navbar" class="navbar-collapse collapse">
      <ul class="nav navbar-nav">
<li>
  <a href="../index.html">
    <span class="fa fa-home fa-lg"></span>
     
  </a>
</li>
<li>
  <a href="../reference/index.html">Reference</a>
</li>
<li class="dropdown">
  <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">
    Articles
     
    <span class="caret"></span>
  </a>
  <ul class="dropdown-menu" role="menu">
<li>
      <a href="../articles/introduction.html">An Introduction to BayesHMM</a>
    </li>
    <li>
      <a href="../articles/introduction2.html">An Introduction to BayesHMM</a>
    </li>
  </ul>
</li>
      </ul>
<ul class="nav navbar-nav navbar-right">
<li>
  <a href="https://github.com/luisdamiano/BayesHMM/">
    <span class="fa fa-github fa-lg"></span>
     
  </a>
</li>
      </ul>
</div>
<!--/.nav-collapse -->
  </div>
<!--/.container -->
</div>
<!--/.navbar -->

      
      </header><div class="row">
  <div class="col-md-9 contents">
    <div class="page-header toc-ignore">
      <h1>An Introduction to BayesHMM</h1>
                        <h4 class="author">Luis Damiano, Michael Weylandt, Brian Peterson</h4>
            
            <h4 class="date">2019-01-03</h4>
      
      <small class="dont-index">Source: <a href="https://github.com/luisdamiano/BayesHMM//blob/master/vignettes/introduction2.Rmd"><code>vignettes/introduction2.Rmd</code></a></small>
      <div class="hidden name"><code>introduction2.Rmd</code></div>

    </div>

    
    
<p>In this vignette, you will learn:</p>

<div id="introduction" class="section level1">
<h1 class="hasAnchor">
<a href="#introduction" class="anchor"></a>Introduction</h1>
<p>BayesHMM is an R Package to run full Bayesian inference on Hidden Markov Models (HMM) using the probabilistic programming language Stan [cite]. By providing an intuitive, expressive yet flexible input interface, we enable researchers to profit the most out of the modern Bayesian workflow. We provide the user with an expressive interface to mix and match a wide array of options for the observation and latent models, including ample choices of densities, priors, and link functions whenever covariates are present. The software enables users to fit HMM with time-homogeneous transitions as well as time-varying transition probabilities. Priors can be set for every model parameter. Implemented inference algorithms include forward (filtering), forward-backwards (smoothing), Viterbi (most likely hidden path), prior predictive sampling, and posterior predictive sampling. Graphs, tables and other convenience methods for convergence diagnosis, goodness of fit, and data analysis are provided.</p>
<p>We aspire to produce a high-quality open-source software that is able to:</p>
<ul>
<li>Compute full Bayesian inference and maximum a posteriori estimates for the unknown quantities in Hidden Markov Models and family.</li>
<li>Provide a high-performance implementation leveraging on the Stan probabilistic programming language <span class="citation">(Carpenter et al. 2017, <span class="citation">Stan Development Team (2018)</span>)</span>.</li>
<li>Adhere to the modern Bayesian methodology for Bayesian Data Analysis <span class="citation">(Betancourt 2018, <span class="citation">Gelman et al. (2013)</span>)</span> by providing built-in tools that we developed to specilize for HMM general Bayesian methodology recommendations for software validation <span class="citation">(Cook, Gelman, and Rubin 2006)</span>, model calibration <span class="citation">(Talts et al. 2018)</span>, and visualization <span class="citation">(Gabry et al. 2017)</span>. A one stop shop for Bayesian HMM.</li>
<li>Provide an intuitive, expressive and user-friendly interface to facilitate Bayesian inference, an intrinsecally complex problem from the computationally point of view, to researchers across many different fields of science.</li>
<li>Interact out of the box with other tools developed for the ever-growing Stan ecosystem, such as <span class="citation">(Gabry et al. 2018)</span>.</li>
<li>Be flexible enough in terms of model specification to accomodate for the needs of different fields where HMM are applied (compare with having only a finite set of pre-built models).</li>
</ul>
<!--
Strong motivation about HMM. Cite papers from different fields.
specialized plotting
Mix previous draft and stuff written for help lie ?specify.
--><div id="naming-convention" class="section level2">
<h2 class="hasAnchor">
<a href="#naming-convention" class="anchor"></a>Naming convention</h2>
<p>We designed the software to have a unified naming convention across programming code (both in R and Stan) and documentations (vignette, manual, and function help). Minor, and hopefully obvious, variants may be found due to different syntax restrictions in R and Stan.</p>
<p>We selected the snake case for methods and functions (e.g. <code>validate_calibration</code>), lower camel case for function arguments and variables (e.g. <code>optimizing(nRuns = 1, nCores = 1, ...</code>), and upper camel case for density functions (e.g. <code>Gaussian</code>, <code>NegativeBinomial</code>). We use verbs to reflect actions, such as <code>compile</code>, <code>explain</code>, and <code>run</code>. Exceptions include <code>sampling</code> and <code>optimizing</code> to avoid masking the base R methods <code>sample</code> and <code>optimize</code>.</p>
<p>Most of the model quantities keep their mathematical notation (e.g. <code>classify_alpha</code>, <code>extract_K</code>, <code>extract_zstar</code>). These are listed in Table .</p>
<table class="table">
<caption>Naming convention for model quantities. The time suffix <code>_t</code> is optional. </caption>
<thead><tr class="header">
<th>Constants</th>
<th></th>
</tr></thead>
<tbody>
<tr class="odd">
<td>R</td>
<td>Observation dimension</td>
</tr>
<tr class="even">
<td>K</td>
<td>Number of hidden states</td>
</tr>
<tr class="odd">
<td>M</td>
<td>Number of covariates for the observation model</td>
</tr>
<tr class="even">
<td>P</td>
<td>Number of covariates for the transition model</td>
</tr>
<tr class="odd">
<td>Q</td>
<td>Number of covariates for the initial model</td>
</tr>
<tr class="even">
<td></td>
<td></td>
</tr>
<tr class="odd">
<td>Covariates</td>
<td></td>
</tr>
<tr class="even">
<td>x_t</td>
<td>Time-varying covariates for the observation model</td>
</tr>
<tr class="odd">
<td>u_t</td>
<td>Time-varying covariates for the transition model</td>
</tr>
<tr class="even">
<td>v</td>
<td>Covariates for the initial model</td>
</tr>
<tr class="odd">
<td></td>
<td></td>
</tr>
<tr class="even">
<td>Known-stochastic quantities</td>
<td></td>
</tr>
<tr class="odd">
<td>y_t</td>
<td>Observation vector</td>
</tr>
<tr class="even">
<td></td>
<td></td>
</tr>
<tr class="odd">
<td>Model parameters</td>
<td></td>
</tr>
<tr class="even">
<td>*_kr</td>
<td>Ex. mu_11 or sigma_11 (suffixes k and r are optional)</td>
</tr>
<tr class="odd">
<td>A</td>
<td>Transition model parameters (if no covariates)</td>
</tr>
<tr class="even">
<td>pi</td>
<td>Initial distribution parameters (if no covariates)</td>
</tr>
<tr class="odd">
<td>xBeta</td>
<td>Regression parameters for the observation model</td>
</tr>
<tr class="even">
<td>uBeta</td>
<td>Regression parameters for the transition model</td>
</tr>
<tr class="odd">
<td>vBeta</td>
<td>Regression parameters for the initial model</td>
</tr>
<tr class="even">
<td></td>
<td></td>
</tr>
<tr class="odd">
<td>Estimated quantities</td>
<td></td>
</tr>
<tr class="even">
<td>z_t</td>
<td>Hidden state</td>
</tr>
<tr class="odd">
<td>alpha_t</td>
<td>Filtered probability</td>
</tr>
<tr class="even">
<td>gamma_t</td>
<td>Smoothed probability</td>
</tr>
<tr class="odd">
<td>zStar</td>
<td>Jointly most likely path (Viterbi)</td>
</tr>
<tr class="even">
<td></td>
<td></td>
</tr>
<tr class="odd">
<td>(Prior/Posterior) predictive quantities</td>
<td></td>
</tr>
<tr class="even">
<td>yPred</td>
<td>Sample of observations drawn from the predictive density</td>
</tr>
<tr class="odd">
<td>zPred</td>
<td>Sample of latent path drawn from the predictive density</td>
</tr>
</tbody>
</table>
</div>
</div>
<div id="a-walk-through-bayeshmm" class="section level1">
<h1 class="hasAnchor">
<a href="#a-walk-through-bayeshmm" class="anchor"></a>A Walk through BayesHMM</h1>
<p>The typical data analysis workflow includes the following steps:</p>
<ol style="list-style-type: decimal">
<li>
<strong>Specify</strong> a model: define the structure of the observation, transition, and initial distribution components. By structure, we mean the density function for the observation random variable, as well as the density function for each component parameters.</li>
<li>
<strong>Compile</strong> a model: translate a model specification to Stan code, which is turn translated to C++ and compiled into a dynamic shared object that can be loaded and sampled from.</li>
<li>
<strong>Validate</strong>: verify that the software is correct in that it can recover accurately the hidden quantities. This step is directly related to the concept of <em>Computational Faithfulness</em> as defined by <span class="citation">Betancourt (2018)</span>, and the built-in tools for automatically diagnosis a model are based on <span class="citation">Cook, Gelman, and Rubin (2006)</span> and <span class="citation">Talts et al. (2018)</span>.</li>
<li>
<strong>Simulate</strong>: generate data complying with the model specification by drawing samples from the prior posterior distribution (a procedure that has been informally called <em>fake data</em>).</li>
<li>
<strong>Fit</strong>: estimate the unknown quantities by either MCMC (full Bayesian estimates) or optimization procedures (maximum a posteriori point estimates).</li>
<li>
<strong>Diagnose</strong>: convergence and goodness of fit (BEWARE: reword this, don’t use goodness of fit, look for the bayesian counterpart).</li>
<li>
<strong>Visualize</strong>: use visualization tools for model evaluation. We designed HMM-specific plots that are highly influenced by the methodology described by <span class="citation">Gabry et al. (2017)</span>.</li>
<li>
<strong>Compare</strong>: develop HMM-specific tools for model comparison.</li>
</ol>
<p>At this early stage, all the steps except for 6 and 8 are implemented in our software.</p>
<div id="specify" class="section level2">
<h2 class="hasAnchor">
<a href="#specify" class="anchor"></a>1. Specify</h2>
<p>This is the stage where most modeling decisions have to be made. A HMM is completely specified when we define the structure of the observation, transition, and initial distribution components. Before delving into each of these submodels, it is important to remark why model specification is a key step in the modeling workflow: the fact that a model can be specified does not guaranteed by itself that we can make inference given reasonable time and resource constrains. BayesHMM is purposedly flexible to allow an extremely wide variety of hidden markov models, yet the user has to take care of Label switching, Using priors to center parameters. Using priors to break symmetry.</p>
<p>Programmatically, HMM are specified by calling the <code>hmm</code> function:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw"><a href="../reference/hmm.html">hmm</a></span>(
  <span class="dt">K =</span> <span class="dv">3</span>, <span class="dt">R =</span> <span class="dv">2</span>,
  <span class="dt">observation =</span> {...}
  <span class="dt">initial     =</span> {...}
  <span class="dt">transition  =</span> {...}
  <span class="dt">name =</span> <span class="st">"Model name"</span>
)</code></pre></div>
<p>where <span class="math inline">\(K\)</span> is the number of hidden states and <span class="math inline">\(R\)</span> is the number of dimensions in the observation variable. The name is a string used for model printouts.</p>
<p>The <code>observation</code>, <code>initial</code>, and <code>transition</code> arguments rely on S3 objects called <code>Density</code> that specify density form, parameter priors, and fixed values for parameters. These allow for bounds in the parameter space as well as truncation in prior densities. For instance:</p>
<ul>
<li>
<code><a href="../reference/Gaussian.html">Gaussian(mu = 0, sigma = 1)</a></code> specifies a Gaussian density with fixed parameters.</li>
<li>
<code><a href="../reference/Gaussian.html">Gaussian(mu = Gaussian(0, 10), sigma = Cauchy(0, 10, bounds = list(0, NA)))</a></code> specifies a Gaussian density with a Gaussian prior on the location parameter and a Cauchy prior on the scale parameter, whose parameter space is bounded on <span class="math inline">\([0, \infty)\)</span>.</li>
</ul>
<div id="observation-model" class="section level3">
<h3 class="hasAnchor">
<a href="#observation-model" class="anchor"></a>1.1. Observation model</h3>
<p>The structure of the observation model comprises the density function for the observation random variable (e.g. continuous versus discrete, bounded versus unbounded, symmetrical versus skewed) as well as the prior density for the observation model parameters.</p>
<p>Most <code>Density</code> objects relate directly with well-established probability density functions, in some cases providing more than one parametrization for the same distribution. For example, <code>MVGaussian</code>, <code>MVGaussianCov</code>, and <code>MVGaussianCor</code> specify a Multivariate Gaussian distribution with the location-scale parametrization, the parametrization based on the Cholesky factor of the covariance matrix, and the parametrization based on the Cholesky factor of the correlation matrix respectively. In practice, the latter proved to be the most performant parametrization in many use cases.</p>
<p>Other <code>Density</code> objects relate to regression models, and thus represent the density function of the observed random variable conditional on fixed covariates. These include <code>RegGaussian</code>, <code>RegBernoulliLogit</code> (Bernoulli regression for <span class="math inline">\(y_i \in \{0, 1\}\)</span>), <code>RegBinomialLogit</code> (Binomial regression with logit link and <span class="math inline">\(N\)</span> trials for <span class="math inline">\(y_i \in \{0, 1, \dots, N\}\)</span>), <code>RegBinomialProbit</code> (Binomial regression with probit link and <span class="math inline">\(N\)</span> trials for <span class="math inline">\(y_i \in \{0, 1, \dots, N\}\)</span>), <code>RegCategoricalSoftmax</code> (Multinomial regression with <span class="math inline">\(N\)</span> categories for <span class="math inline">\(y_i \in \{0, 1, \dots, N\}\)</span>).</p>
<p>Currently available densities are listed below. Information about the density parameterization can be accessed via the question mark operator (e.g. <code><a href="../reference/Gaussian.html">?Gaussian</a></code>).</p>
<ul>
<li>Observation density and priors:</li>
<li>Univariate: Bernoulli, Beta, Binomial, Categorical, Cauchy, Dirichlet, Gaussian, Multinomial, Negative Binomial (traditional and location parameterizations), Poisson, Student.</li>
<li>Multivariate: Multivariate Gaussian (traditional, Cholesky decomposition of covariance matrix, and Cholesky decomposition of correlation matrix parameterizations), Multivariate Student.</li>
<li>Observation density only: Bernoulli regression with logit link, Binomial regression (logit and probit links), Softmax regression, Gaussian regression.</li>
<li>Prior-only density: LKJ, Wishart.</li>
</ul>
<p><strong>MORE ON HOW TO SPECIFY. USE ?specify</strong>.</p>
</div>
<div id="transition-model" class="section level3">
<h3 class="hasAnchor">
<a href="#transition-model" class="anchor"></a>1.2. Transition model</h3>
<p><strong>MORE ON HOW TO SPECIFY. USE ?specify</strong>.</p>
</div>
<div id="initial-state-model" class="section level3">
<h3 class="hasAnchor">
<a href="#initial-state-model" class="anchor"></a>1.3. Initial state model</h3>
<p><strong>MORE ON HOW TO SPECIFY. USE ?specify</strong>.</p>
</div>
</div>
<div id="compile" class="section level2">
<h2 class="hasAnchor">
<a href="#compile" class="anchor"></a>2. Compile</h2>
<p>A model specification is simply a named nested list designed for the purpose of BayesHMM. The following step is then translate this list to Stan code, which is in turn translated to C++ and compiled into a dynamic shared object that can be loaded and sampled from.</p>
<!--
\begin{tikzpicture}
  \draw[fill = red!20, draw, double, rounded corners, align=center]
       (0, 0) node(specification){BayesHMM's\\hmm()}
  -> ++(4, 0) node(stanCode){Stan code}
  -> ++(4, 0) node(stanObject){rstan's\\stanmodel }
  -> ++(4, 0) node(fit){BayesHMM's\\fit()}
  -> ++(0, 1) node(optimizing){BayesHMM's\\optimizing()}
  -> ++(0, 1) node(sim){BayesHMM's\\sim()};
\end{tikzpicture}
-->
<p> </p>

<p><strong>Add legend to diagram.</strong></p>
<p>The reader is advised to read <span class="citation">Team (2017)</span> to learn the technical details behind compilation. As this process may be time consuming (e.g. a model may take up to a minute to compile), it is desirable to compile the model once, store the object in the memory, and reuse it to call other related methods (namely <code>sampling</code>, <code>optimizing</code>, <code>sim</code>, <code>validate_calibration</code>) one or more times. If any of these methods is only given a Specification object when called, it will compile the model, run the analysis, discard the compiled object and return the results of the analysis.</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="co"># Assume a specification object called mySpec</span>
<span class="co"># Most efficient: only compiles the model once.</span>
myModel &lt;-<span class="st"> </span><span class="kw"><a href="../reference/compile.html">compile</a></span>(mySpec)
myVal   &lt;-<span class="st"> </span><span class="kw"><a href="../reference/validate_calibration.html">validate_calibration</a></span>(myModel, <span class="dt">N =</span> <span class="dv">100</span>)
myData  &lt;-<span class="st"> </span><span class="kw"><a href="../reference/sim.html">sim</a></span>(myModel, <span class="dt">T =</span> <span class="dv">500</span>)
myFit   &lt;-<span class="st"> </span><span class="kw">sampling</span>(myModel, <span class="dt">y =</span> myData<span class="op">$</span>y)

<span class="co"># Least efficient: the model is compiled under the hood three times. </span>
myVal   &lt;-<span class="st"> </span><span class="kw"><a href="../reference/validate_calibration.html">validate_calibration</a></span>(mySpec, <span class="dt">N =</span> <span class="dv">100</span>)
myData  &lt;-<span class="st"> </span><span class="kw"><a href="../reference/sim.html">sim</a></span>(mySpec, <span class="dt">T =</span> <span class="dv">500</span>)
myFit   &lt;-<span class="st"> </span><span class="kw">sampling</span>(mySpec, <span class="dt">y =</span> myData<span class="op">$</span>y)</code></pre></div>
</div>
<div id="validate" class="section level2">
<h2 class="hasAnchor">
<a href="#validate" class="anchor"></a>3. Validate</h2>
<p>After a model is compiled, it is always best to validate the correctness of the software. This step is directly related to the concepts of <strong>computational correctness</strong> and <em>computational faithfulness</em> as defined by <span class="citation">Cook, Gelman, and Rubin (2006)</span> and <span class="citation">Betancourt (2018)</span> respectively. The built-in tools for automatically diagnosis a model are based on these ideas as well as <span class="citation">Talts et al. (2018)</span>.</p>
<p>The implementation of the core algorithms for HMM inference (namely the forward, the forward-backward and the Viterbi algorithm) are based on publicly available software <span class="citation">(Damiano, Peterson, and Weylandt 2018)</span>. Nonetheless, it is wise to validate that the specific combination of submodels and priors chosen in the specification step functions properly. Besides detecting errors in the software, the nature of these deviances may be informative about the nature and location of such errors.</p>
<p>The goal is to verify that the software recovers accurately the unknown quantities. If we know the true value of the unknown quantities that generate a dataset, we can compute the estimates and verify that they provide a good approximation. The main challenge is these results are inherently stochastic, and thus we need to account for variability even when running the software under ideal conditions.</p>
<p>In the specification stage, we defined the prior distribution of the parameter vector <span class="math inline">\(p({\mathbf{\Theta}})\)</span> and the sampling distribution of the data <span class="math inline">\(p({\mathbf{y}} | {\mathbf{\Theta}})\)</span>. These specify <strong>the model</strong>, that is the joint distribution of the observation vector <span class="math inline">\(p({\mathbf{y}}) = p({\mathbf{y}} | {\mathbf{\Theta}}) p({\mathbf{\Theta}})\)</span>. Our validation protocol is as follows:</p>
<ol style="list-style-type: decimal">
<li>Compile the prior predictive model.</li>
<li>Draw <span class="math inline">\(N\)</span> independent samples of the parameter vector from the prior distribution <span class="math inline">\({\mathbf{\Theta}}^{(n)} \sim p({\mathbf{\Theta}})\)</span> and the observation vector from prior predictive density <span class="math inline">\({\mathbf{y}}^{(n)}_t \sim p({\mathbf{y}}) = p({\mathbf{y}} | {\mathbf{\Theta}}^{(n)}) p({\mathbf{\Theta}}^{(n)}), n \in \{1, \dots, N\}\)</span>.<a href="#fn1" class="footnoteRef" id="fnref1"><sup>1</sup></a>
</li>
<li>Compile the posterior predictive model.</li>
<li>For all <span class="math inline">\(n \in \{1, \dots, N\}\)</span>:
<ol style="list-style-type: decimal">
<li>Feed <span class="math inline">\({\mathbf{y}}_t^{(n)}\)</span> to the model.</li>
<li>Draw one posterior sample of the observation vector from the posterior predictive density <span class="math inline">\({\mathbf{y_t}}^{(n)}_{\text{new}} \sim p( {\mathbf{y_t}}_{\text{new}} | {\mathbf{y}})\)</span>.</li>
<li>Collect Hamiltonian Monte Carlo diagnostics for each chain: number of divergences, number of times max tree depth is reached, maximum leapfrogs, warm up and sample times.</li>
<li>Collect posterior sampling diagnostics for each unknown quantity: posterior summary measures (mean, standard deviation, quantiles), comparison against the true value (ranks as defined by <span class="citation">Talts et al. (2018)</span>), MCMC convergence measures (Monte Carlo SE, ESS, R Hat).</li>
<li>Collect posterior predictive diagnostics for the observation vector: observation ranks, Kolmogorov-Smirnov statistic for observed sample versus posterior predictive samples.</li>
</ol>
</li>
</ol>
<p>The prior predictive model is defined as the model where the posterior density equals to the prior density, i.e. the posterior density is not informed by the sampling distribution of the data. <strong>EXPLAIN POSTERIORS AND PRIORS HERE WITH EQUATIONS</strong>.</p>
<p><strong>TABLE WITH ALL THE QUANTITIES AND THE INTERPRETATION, RULE OF THUMB, REFERENCE</strong>.</p>
</div>
<div id="simulate" class="section level2">
<h2 class="hasAnchor">
<a href="#simulate" class="anchor"></a>4. Simulate</h2>
</div>
</div>
<div id="references" class="section level1 unnumbered">
<h1 class="hasAnchor">
<a href="#references" class="anchor"></a>References</h1>
<div id="refs" class="references">
<div id="ref-Betancourt2018">
<p>Betancourt, Michael. 2018. “Towards a Principled Bayesian Workflow.” <a href="https://betanalpha.github.io/assets/case_studies/principled_bayesian_workflow.html" class="uri">https://betanalpha.github.io/assets/case_studies/principled_bayesian_workflow.html</a>.</p>
</div>
<div id="ref-Carpenter2017">
<p>Carpenter, Bob, Andrew Gelman, Matthew D. Hoffman, Daniel Lee, Ben Goodrich, Michael Betancourt, Marcus Brubaker, Jiqiang Guo, Peter Li, and Allen Riddell. 2017. “Stan: A Probabilistic Programming Language.” <em>Journal of Statistical Software</em> 76 (1). Foundation for Open Access Statistic. doi:<a href="https://doi.org/10.18637/jss.v076.i01">10.18637/jss.v076.i01</a>.</p>
</div>
<div id="ref-Cook2006">
<p>Cook, Samantha R, Andrew Gelman, and Donald B Rubin. 2006. “Validation of Software for Bayesian Models Using Posterior Quantiles.” <em>Journal of Computational and Graphical Statistics</em> 15 (3). Informa UK Limited: 675–92. doi:<a href="https://doi.org/10.1198/106186006x136976">10.1198/106186006x136976</a>.</p>
</div>
<div id="ref-Damiano2018">
<p>Damiano, Luis, Brian Peterson, and Michael Weylandt. 2018. “A Tutorial on Hidden Markov Models Using Stan.” Zenodo. doi:<a href="https://doi.org/10.5281/zenodo.1284341">10.5281/zenodo.1284341</a>.</p>
</div>
<div id="ref-gabry2018">
<p>Gabry, Jonah, Tristan Mahr, Paul-Christian Bürkner, Martin Modrák, and Malcolm Barrett. 2018. “bayesplot: Plotting for Bayesian Models.” <a href="https://CRAN.R-project.org/package=bayesplot" class="uri">https://CRAN.R-project.org/package=bayesplot</a>.</p>
</div>
<div id="ref-Gabry2017">
<p>Gabry, Jonah, Daniel Simpson, Aki Vehtari, Michael Betancourt, and Andrew Gelman. 2017. “Visualization in Bayesian Workflow,” September. <a href="http://arxiv.org/abs/1709.01449v5" class="uri">http://arxiv.org/abs/1709.01449v5</a>.</p>
</div>
<div id="ref-Gelman2013">
<p>Gelman, Andrew, John B. Carlin, Hal S. Stern, David B. Dunson, Aki Vehtari, and Donald B. Rubin. 2013. <em>Bayesian Data Analysis</em>. Taylor &amp; Francis Ltd.</p>
</div>
<div id="ref-SDT2018">
<p>Stan Development Team. 2018. “RStan: The R Interface to Stan.” <a href="http://mc-stan.org/" class="uri">http://mc-stan.org/</a>.</p>
</div>
<div id="ref-Talts2018">
<p>Talts, Sean, Michael Betancourt, Daniel Simpson, Aki Vehtari, and Andrew Gelman. 2018. “Validating Bayesian Inference Algorithms with Simulation-Based Calibration,” April. <a href="http://arxiv.org/abs/1804.06788v1" class="uri">http://arxiv.org/abs/1804.06788v1</a>.</p>
</div>
<div id="ref-Team2017">
<p>Team, Stan Development. 2017. <em>Stan Modeling Language: User’s Guideand Reference Manual. Version 2.17.0.</em> <a href="http://mc-stan.org/users/documentation/" class="uri">http://mc-stan.org/users/documentation/</a>.</p>
</div>
</div>
</div>
<div class="footnotes">
<hr>
<ol>
<li id="fn1"><p>Although <span class="citation">Cook, Gelman, and Rubin (2006)</span> state that the samples do not need to be independent nor jointly exchangeable, in our implemenetation they are generated independently. Additionally, although the second step may be more naturally thought as a substep of #4, it is more computationally efficient to produce the <span class="math inline">\(N\)</span> independent samples in one run.<a href="#fnref1">↩</a></p></li>
</ol>
</div>
  </div>

  <div class="col-md-3 hidden-xs hidden-sm" id="sidebar">
        <div id="tocnav">
      <h2 class="hasAnchor">
<a href="#tocnav" class="anchor"></a>Contents</h2>
      <ul class="nav nav-pills nav-stacked">
<li>
<a href="#introduction">Introduction</a><ul class="nav nav-pills nav-stacked">
<li><a href="#naming-convention">Naming convention</a></li>
      </ul>
</li>
      <li>
<a href="#a-walk-through-bayeshmm">A Walk through BayesHMM</a><ul class="nav nav-pills nav-stacked">
<li><a href="#specify">1. Specify</a></li>
      <li><a href="#compile">2. Compile</a></li>
      <li><a href="#validate">3. Validate</a></li>
      <li><a href="#simulate">4. Simulate</a></li>
      </ul>
</li>
      <li><a href="#references">References</a></li>
      </ul>
</div>
      </div>

</div>


      <footer><div class="copyright">
  <p>Developed by Luis Damiano, Michael Weylandt, Brian Peterson.</p>
</div>

<div class="pkgdown">
  <p>Site built with <a href="http://pkgdown.r-lib.org/">pkgdown</a>.</p>
</div>

      </footer>
</div>

  

  </body>
</html>
