Issue/838 hmm

[charlesm93]

Submission Checklist

• Builds locally
• New functions marked with <<{ since VERSION }>>
• Declare copyright holder and open-source license: see below

Summary

Addresses issue #838 and updates user-doc on HMMs.

Copyright and Licensing

Please list the copyright holder for the work you are submitting (this will be you or your assignee, such as a university or company): Charles Margossian, Simons Foundation

By submitting this pull request, the copyright holder is agreeing to license the submitted work under the following licenses:

• Code: BSD 3-clause (https://opensource.org/licenses/BSD-3-Clause)
• Documentation: CC BY-ND 4.0 (https://creativecommons.org/licenses/by-nd/4.0/)

[bob-carpenter]

I took a look through this and while I'm in favor of minimal examples, this one's a bit too minimal. I would really like to see the model laid out in more detail than the conditional distributions. Here are some concrete suggestions:

1. Use z for latent discrete parameters. We already use x for covariates, so it's confusing to use x. I've used z elsewhere in the user manual for this in the latent discrete parameter chapter.

2. Define the complete data likelihood $p(y, z | \phi) = p(z \mid \phi) \cdot p(y \mid z, \phi)$ and then the marginalization $p(y \mid \phi)$ that we actually fit.

3. Mention that $\phi$ is actually several parameters.

4. I find the constrained version of the transition matrix where you insert zeros makes this first example too challenging. If you want to discuss that case, I'd suggest another section after this one where you talk about imposing structural zeros. Otherwise it makes the simple case seem too complicated. And then you can just define

array[3] simplex[3] gamma_arr;

matrix[3, 3] gamma;
for (n in 1:3) gamma[n] = gamma_arr[n];

5. For the doc, those mu and sigma are not just the measurement model---that's all the error terms.

6. Wherever you have repetition, use loops. It's less error prone and more clear that it's a homogeneous operation:

for (n in 1:N) {
  for (k in 1:3) {
    log_omega[k, n] = normal_lpdf(y[n] | mu[k], sigma);
  }
}

7. Given that you're tying the parameter sigma across outputs, you need to mention that. I'd recommend just keeping this simple with a vector of sigma values.

8. You can't just say "computes the relevant log marginal distribution"---you have to say what that is. I don't mean including the marginalization algorithm, I just mean as I wrote it above.

9. For more details, since -> For more details, see. Also, I wouldn't say "corresponding case study", I'd just say it's a case study on HMMs. And then you should put it in the bibtex file and cite it properly with reference to Ben (the author). And you should cite that you "borrowed" the example from Ben Bales's case study.