next manual, 2.15++

[bob-carpenter]

Summary:

Corrections and suggestions for the manual after the 2.15 release should be included as comments.

The branch for this issue is

• feature/2265-manual-2.16

Current Version:

v2.15.0

[bob-carpenter]

From @jmh530 on #2122 (comment)

In Section 8.2 on QR factorization, I feel like the paragraph that recommends you use it when you do not have an informative prior on the location of beta is mistaken (also mentioned in 8.3).

Consider a probability distribution Y ~ N(XB, sigma) with a prior B ~ N(mu_B, sd_B). Y is then re-written as Y ~ N(Q * theta, sigma). The equivalent distribution on the prior of theta would be theta ~ MVN(mu_B * R, t(R) * diag(sd_B ^ 2) * R), assuming mu_B is 1XN.

My point is that you can still include a prior on the mean of beta, you just have to do the appropriate transformation in order to express it in terms of the new beta. This raises some other questions about the reasoning in that section, but I'll leave off here.

@jgabry replied
@jmh530 yeah you're right that it's possible to use the QR approach even with a non-zero prior mean on the coefficients, so perhaps the recommendation in the manual is worded too strongly. @bgoodri should comment on this though because he wrote that section and I forget if he had a reason for discouraging this (he's definitely aware that's it's possible). One reason might just be that it is strange to have a prior belief that there is a dense covariance matrix for the MVN on theta since theta represents the coefficients on the columns of the Q matrix and those columns are orthogonal.

@jmh530 replied
True. When I was playing around with it, I had extracted the standard
deviations from the covariance matrix and just used the univariate normal
distribution.

@bgoodri : would you mind weighing in on whether this needs to be addressed?

• fix ?
• don't fix---move to longer term discussion pending feedback from @bgoodri or @jgabry

[bob-carpenter]

• discuss issue with long simplexes and optimization brought up in Optimization fails for long simplexes #2273 by Jussi Määttä
• thank Jussi in the acknowledgements

[javier-rubikloud]

Hi, this is just to report a tiny typo in stan/src/docs/stan-reference/distributions.tex.

If I am not mistaken, where it says:

\begin{eqnarray*}
\distro{BinomialLogit}(n|N,\alpha)
& = & \distro{BinomialLogit}(n|N,\mbox{logit}^{-1}(\alpha))
\\[6pt]
& = & \binom{N}{n} \left( \mbox{logit}^{-1}(\alpha) \right)^{n}
                    \left( 1 - \mbox{logit}^{-1}(\alpha) \right)^{N - n}.
\end{eqnarray*}

It should really say:

\begin{eqnarray*}
\distro{BinomialLogit}(n|N,\alpha)
& = & \distro{Binomial}(n|N,\mbox{logit}^{-1}(\alpha))
\\[6pt]
& = & \binom{N}{n} \left( \mbox{logit}^{-1}(\alpha) \right)^{n}
                    \left( 1 - \mbox{logit}^{-1}(\alpha) \right)^{N - n}.
\end{eqnarray*}

In other words, at the right side of the first equality it should be Binomial, not BinomialLogit.

I love the manual, by the way. Thanks for all the great work.

• fix

[bob-carpenter]

@javier-rubikloud

Thanks. You're right that it should be Binomial

• fix next manual, 2.15++ #2265 (comment) as suggested
• thank Javier Moreno in acknowledgements

[bbbales2]

In "User Transformed Parameters" (page 75 of 2.14, or 72 of 2.15) I think y should be declared in a parameters block rather than a data one.

I think it's trying to be the sample example as in "Change of Variables" (page 272 2.14, page 263/265 2.15) (where it is in a parameters block). With y in a data block there's not really a reason to do the Jacobian adjustment.

• fix

Also I just notice that "Change of Variables" had a section number in 2.14 and now doesn't in 2.15. That just made it harder for me to cite the location of this change. I'd rather have more numbering than less, honestly, but I assume there's a reason these got removed.

[bob-carpenter]

• Discuss varying upper bounds (and maybe lower bounds).

If you have a bunch of variables tau[n] to constrain to fall in (0, y[n]), then you have to do the transforms and Jacobians yourself.

parameters {
  vector[N] tau_raw;

transformed parameters {
  vector[N] tau = inv_logit(tau_raw) .* y;  // this could also be a local variable

The Jacobian is just

   inv_logit(tau_raw[n]) * (1 - inv_logit(tau_raw[n]) * y[n];

and you want it on the log scale, so that's

   log_inv_logit(tau_raw[n]) + log1m_inv_logit(tau_raw[n]) + log(y[n])

putting it all together, that should just be:

model {
  target += log_inv_logit(tau_raw);
  target += log1m_inv_logit(tau_raw);
  target += log(y);

[bob-carpenter]

From @stemangiola in #2302:

• remove extra close paren in

target += -2 * log(y_inv) ); // adjustme;

From @stemangiola in #2303:

• fix target += is shown in the transformed parameters, while Stan complains it should be in the model block, I believe.

transformed parameters {
real<lower=0> y;
y = 1 / y_inv; // change
target += -2 * log(y_inv) ); // adjustme;
}

• thank @stemangiola in acknowledgements

[agormp]

In the subsection "Accessing the Log Density" on p. 75 (in v. 2.15.0):

• The first part of the text seems to be repeating what was explained on previous pages (and to not be about accessing the log density but about setting it).

• fix

• The last sentence uses the deprecated get_lp() function instead of target()

• fix
• thank Anders Gorm Pedersen

[agormp]

Typo on p. 75 in subsection 4.3:

"[...] involving subexpressions y1 and theta1 through thetaN [..]"

"y1" should be "y"

• fix

[bob-carpenter]

In "Matrices with Parameters and Constants" (section 25.5), there's an illegal assignment of a vector A_raw to a matrix A[ii, jj].

• fix it
• thank J Takoua for bringing it up on our list

[zhangxiubo]

At the top of Page 160 in Section 9.1. In the example code for the vectorised model for AR(1) process, the left hand side should be y[2:N] instead of y[2:(N - 1)]?

• fix

[bob-carpenter]

Thanks, @zhangxiubo --- I'll fix that.

[zhangxiubo]

At the top of page 240, the line that increments the target likelihood seems to have an extra brace at the end of the line. Should be target += log_sum_exp(gamma); // likelihood; instead of target += log_sum_exp(gamma)); // likelihood;.

• fix

[ariddell]

Please add Ari Hartikainen (@ahartikainen) of Aalto University as a developer contributing to PyStan. He has confirmed his interest in sustaining PyStan development. (Let me know if I should just make a PR instead.)

• add

[bob-carpenter]

• add break and continue to the list of keywords

• thank Michael Clerx, who reported this on Discourse: http://discourse.mc-stan.org/t/break-keyword-is-missing-from-list-of-reserved-keywords-in-manual/857

[editorial note: They were included among the C++ keywords]

[bob-carpenter]

Copied from an issue by @stephensrmmartin at #2326:

• convert skew normal paramters from mu and sigma to xi and omega to match the standard convention (see, e.g., https://en.wikipedia.org/wiki/Skew_normal_distribution )

• thank Stephen Martin in the acknowledgements

[bob-carpenter]

From #2327:

• normal_rng(real mu | real sigma) should be normal_rng(real mu, real sigma)