# Documenting target incrementing functions

**URL:** <https://discourse.mc-stan.org/t/documenting-target-incrementing-functions/16683>\
**Category:** Developers\
**Created:** [July 16, 2020, 8:59pm UTC](https://discourse.mc-stan.org/t/documenting-target-incrementing-functions/16683 "2020-07-16T20:59:09Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![charlesm93](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/charlesm93/32/4634_2.png) [@charlesm93](https://discourse.mc-stan.org/u/charlesm93)\
**Post date:** [July 16, 2020, 8:59pm UTC](https://discourse.mc-stan.org/t/documenting-target-incrementing-functions/16683/1 "2020-07-16T20:59:09Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![jonah](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/jonah/32/200_2.png) [@jonah](https://discourse.mc-stan.org/u/jonah)\
**Post date:** [July 27, 2020, 6:28pm UTC](https://discourse.mc-stan.org/t/documenting-target-incrementing-functions/16683/2 "2020-07-27T18:28:36Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![Bob\_Carpenter](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/bob_carpenter/32/9230_2.png) [@Bob\_Carpenter](https://discourse.mc-stan.org/u/Bob_Carpenter)\
**Post date:** [July 30, 2020, 8:42pm UTC](https://discourse.mc-stan.org/t/documenting-target-incrementing-functions/16683/3 "2020-07-30T20:42:38Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![charlesm93](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/charlesm93/32/4634_2.png) [@charlesm93](https://discourse.mc-stan.org/u/charlesm93)\
**Post date:** [July 31, 2020, 4:50pm UTC](https://discourse.mc-stan.org/t/documenting-target-incrementing-functions/16683/4 "2020-07-31T16:50:07Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![hyunji.moon](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/hyunji.moon/32/9781_2.png) [@hyunji.moon](https://discourse.mc-stan.org/u/hyunji.moon)\
**Post date:** [August 1, 2020, 6:22am UTC](https://discourse.mc-stan.org/t/documenting-target-incrementing-functions/16683/5 "2020-08-01T06:22:03Z")

</div>

> [@charlesm93](#):
>
> two functions meant to appear on the rhs of `target +=` , but which don’t behave as conventionals lpdf’s: `log_mix` and `hmm_marginal` .

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?

---

<div class="post-metadata">

**Author:** ![Bob\_Carpenter](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/bob_carpenter/32/9230_2.png) [@Bob\_Carpenter](https://discourse.mc-stan.org/u/Bob_Carpenter)\
**Post date:** [August 5, 2020, 2:06am UTC](https://discourse.mc-stan.org/t/documenting-target-incrementing-functions/16683/6 "2020-08-05T02:06:44Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![charlesm93](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/charlesm93/32/4634_2.png) [@charlesm93](https://discourse.mc-stan.org/u/charlesm93)\
**Post date:** [August 5, 2020, 7:46am UTC](https://discourse.mc-stan.org/t/documenting-target-incrementing-functions/16683/7 "2020-08-05T07:46:39Z")

</div>

@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, ...);

```

---

<div class="post-metadata">

**Author:** ![avehtari](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/avehtari/32/5935_2.png) [@avehtari](https://discourse.mc-stan.org/u/avehtari)\
**Post date:** [August 5, 2020, 7:51am UTC](https://discourse.mc-stan.org/t/documenting-target-incrementing-functions/16683/8 "2020-08-05T07:51:25Z")

</div>

> [@charlesm93](#):
>
> so that you can actually use it as a classic lpdf, so something like:
> 
> ```no-highlight
> target += laplace_marginal_poisson_log(y | n, K, ...);
> 
> ```

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

```no-highlight
target += laplace_marginal_poisson_log_lpmf(y | n, K, ...);

```

(with \_lpmf in the end of the function name)

---

<div class="post-metadata">

**Author:** ![charlesm93](https://yyz2.discourse-cdn.com/flex030/user_avatar/discourse.mc-stan.org/charlesm93/32/4634_2.png) [@charlesm93](https://discourse.mc-stan.org/u/charlesm93)\
**Post date:** [August 5, 2020, 7:54am UTC](https://discourse.mc-stan.org/t/documenting-target-incrementing-functions/16683/9 "2020-08-05T07:54:52Z")

</div>

Yes, you’re right!

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