Documenting target incrementing functions

Hi everyone,

We now have in Stan two functions meant to appear on the rhs of target +=, but which don’t behave as conventionals lpdf’s: log_mix and hmm_marginal. The prototype embedded Laplace approximations behave similarly.

Currently, in the documentation, log mix is under REAL-VALUED BASIC FUNCTION > Composed Functions. I could create a similar section under Matrix operations for hmm_marginal. But it might be appropriate to add an Additional Distributions or Additional log densities section, following the discrete and continuous distributions sections.


I don’t have a strong opinion on this but am responding so this doesn’t get lost because it’s worth deciding (I think I’d slightly lean towards your second option). Anyone have a preference?

1 Like

This discussion was also going on elsewhere. I’m pretty sure the conclusion was to add a new chapter that would go in with the distribution functions rather than the matrix functions. This is for the reference manual. We also need a description in the user’s guide. Or a case study.

1 Like

I can confirm what Bob says. There’s a PR for the functions reference manual. Case studies and sections for the user manual are a work in progress.


Could you be more specific on this please? Is the absence of conditional grammar ‘_lpdf(y | params)’ the only difference? Are there any conceptual differences as well?

I think we cleared this up in a hangout, but the issue is that the HMM functions take functions of the data and parametrers on the right hand side, so they’re not really distributions over the left-hand side.

That is, when we write y ~ normal(mu, sigma), we have a properly normalized density for y, namely \textrm{normal}(y \mid \mu, \sigma). There’s no way to do that with the HMMs, becuase the right-hand side arguments to the HMMs require functions of the data, namely the emission densities. So it looks more like hmm(y | f(y, alpha), beta) rather than hmm(y | alpha, beta) because they thought it’d be too hard to implement his all for generic emission density functions and generic numbers of parameters. It could be done, but it’d look a lot more like the ODE solver.

1 Like

@Bob_Carpenter is right. The data y and the model parameters, say \phi, are not explicitly passed to hmm_marginal. Rather, the user passes three arguments (\log \omega, \Gamma, and \rho) which depend on y and \phi. None of these three arguments would logically appear on the the lhs of ~. There should now be a relevant chapter in the function references manual.

For the laplace marginalization, I have per @avehtari’s request, revised the signature, so that you can actually use it as a classic lpdf, so something like:

target += laplace_marginal_poisson_log(y | n, K, ...);
1 Like

Should be:
"so that you can actually use it as a classic lpmf, so something like

target += laplace_marginal_poisson_log_lpmf(y | n, K, ...);

(with _lpmf in the end of the function name)

Yes, you’re right!

And I double-checked that this is indeed the signature used in the StanCon notebook.

1 Like