Documentation: Error in efficient alternative to diag_matrix in multi_normal?

General
1

In ‘Stan Functions Reference’ manual, version 2.29, section 6.8, it is stated that:

Although the diag_matrix function is available, it is unlikely to ever show up in an efficient Stan program. For example, rather than converting a diagonal to a full matrix for use as a covariance matrix,

 y ~ multi_normal(mu, diag_matrix(square(sigma)));

it is much more efficient to just use a univariate normal, which produces the same density,

 y ~ normal(mu, sigma);

However, the function signature in section 18.1.3 for the normal distribution, only considers reals as a possible type for the variance:

18.1.3 Stan functions

real normal_lpdf (reals y | reals mu, reals sigma)
The log of the normal density of y given location mu and scale sigma

Then, how can both functions result in “the same density”, if multi_normal allows for a vector of differing variance values for each y, while normal just accepts a single scalar?

Thanks for your help!

P.S.: Is there a proper tag for documentation or manual questions? Or a platform to submit errata?

2

Hi @tomvar -

This is a good question! The answer lies in the documentation page labelled “Conventions for probability distributions” 13.8 Vectorization | Stan Functions Reference

In summary, the term “reals” (as distinct from “real” without the “s”) is used as a shorthand for vectorization, meaning that sigma can be a real, an array[] real, a vector, or a row_vector.

This shorthand can be confusing, but normal actually has 64 unique signatures under these aliases, so listing all of them is also not ideal. We should probably link to the above page more than we do, though!

If you have a github account, issues can be filed at Issues · stan-dev/docs · GitHub. If you are unsure if there really is an error or if you simply have a question, I think this is the best place to ask.

2 Likes
3

Thank you very much for the clear swift reply!

1 Like