How to use include_summand

Developers
1

Hi, I have just recently started using Stan and currently I am trying to write a C++ lpdf function for the von MIses-Fisher 2D spherical distribution function. I am learning by looking at the example of writing an lpdf function of normal distribution as provided in this document (https://arxiv.org/abs/1509.07164). In the normal_lpdf.hpp source (https://github.com/stan-dev/math/blob/37f1d0916f50185601ad18aa995ef6f42bf52966/stan/math/prim/prob/normal_lpdf.hpp) I can understand that the following lines represent the log probability density function as shown by equation (1) on page 3 of the document:

    if (include_summand<propto>::value) {
      logp += NEG_LOG_SQRT_TWO_PI;
    }
    if (include_summand<propto, T_scale>::value) {
      logp -= log_sigma[n];
    }
    logp += NEGATIVE_HALF * y_minus_mu_over_sigma_squared;

I don’t understand the purpose of the following lines:

    if (include_summand<propto>::value) {
    if (include_summand<propto, T_scale>::value) {

From this page (https://mc-stan.org/math/d1/dda/structstan_1_1math_1_1include__summand.html) it says include_summand “calculates whether a summand needs to be included in a proportional (log) probability calculation.” This explanation is not very clear to me.

Can anyone explain them to me using the normal lpdf function as an example? If you can point me to a document that provides similar examples of include_summand usage, it would be great too. Thanks!

1 Like
2

propto is a template flag that indicates whether we only need to compute the lpdf up to a constant of proportionality (propto = TRUE) or whether we need to do the whole thing (propto = FALSE).

If propto is FALSE, we want to include all terms, so all of these include_summand things are true. The inverted logic there makes it a bit confusing to just read off.

If propto is TRUE, then include_summand is true only if one of the other parameters passed in (in this example T_scale but there can be multiple) is an autodiff type (not a c++ arithmetic type, not an Eigen matrices of arithmetic types, and not a std::vectors of anything that is arithmetic).

The logic is a bit weird to follow and is easy to get wrong. It makes stuff faster when we only need something up to a proportionality constant.

1 Like
3

Oh yeah currently propto = TRUE is only set to true for things using the sampling syntax. There’s a discussion over here of extending the rules so users can take advantage of the proportionality thing manually: Request for final feedback: User controlled unnormalized (propto) distribution syntax

I think this still may be an outstanding issue with propto handling: https://github.com/stan-dev/stanc3/issues/541#issuecomment-632003010

4

Thanks Ben for your detailed answer, it really helps me to understand the purpose of the template flag better. I will get back with my C++ von Mises-Fisher lpdf function in another thread.

1 Like