next manual, 2.3.0++

[bob-carpenter]

This is the topic for comments about changes to the next version of the manual.

• [x] add prefix, postfix and infix operators to Stan BNF grammar in reference manual

[randommm]

• [x] Fix typo (frquently) in section Model Building as Software Development:

"Finding the solution to your own problem when explaining it to someone else happens so frquently in software development"

• [x] Fix typo (and and) in section Gaussian Process Regression:

"where m(x) is an N-vector and and k(x) is an N × N covariance matrix"

• [x] Fix typo (import) in section Gaussian Process Regression:

"The addition of $\sigma^2$ on the diagonal is import to"

[HerraHuu]

• [x] Sampling statement categorical_logit() seems to be missing from the manual.

[bob-carpenter]

• [x] Remove or replace link to Lucida Console font, which is now missing

[bob-carpenter]

• [ ] replace all uniform priors on scale parameters with ??? [waiting to hear from Andrew]

[bob-carpenter]

Rick Farouni asked on stan-dev how to construct a Cholesky factor with a diagonal of ones for "hierarchical" structural constraint for the loadings matrix used in Bayesian factor analysis in:

• Aguilar, Omar, and Mike West. "Bayesian dynamic factor models and portfolio allocation." Journal of Business & Economic Statistics 18.3 (2000): 338-357.

Michael explained on the list that you use the transformed parameters to do this directly by taking the unconstrained below-diagonal elements as the parameters and then filling in a transformed parameter. Further mention that if you want a prior on the covar matrix that you'll need to add in the Jacobian manually.

• [x] provide example in manual
• [x] add citation to bib

[bob-carpenter]

• [ ] provide some advice on priors for positive_ordered and ordered vectors

I believe, but need to verify, that a simple i.i.d. normal on an ordered vector produces the same result as putting the same normal prior on an unconstrained vector, then sorting.

In general, we could also put a prior on the first element and then some positive-support prior on the differences.

[bob-carpenter]

• [x] add a section with discussion to the regression chapter on predictive modeling and use "forecasting" as a synonym to help users find it
• [x] add a simple regression example done both in model and in generated quantities
• [ ] add a time-series example
• [ ] add a generated quantities example involving discrete predictions

I responded to a stan-users group query from Sam Weiss:

There are two ways to do this. Both involve adding new data variables for the number of items to predict/forecast and any inputs necessary to do that prediction. Then you can either:

1. Define new parameters for the predictions and give these parameters predictions just like in the original model. This only works for continous predictions.
2. Define new generated quantity variables for the predictions and define them using random number generators in the generated quantities block. This method will work for discrete or continous predictions.

[bob-carpenter]

• [x] Thank G\"{o}k\c{c}en Eraslan for manual patch
• [x] Thank Patrick Snape for a code patch

[jonathan-g]

• [x] I just noticed a minor layout flaw on p. 119 (Fig. 16.1): the text of the figure caption overlaps the x-axis labels of the figures (\lambda _1, \lambda_1 and \mu), making the axis labels hard to read.
• [x] Also, it would be useful to add a cross-reference to section 11.2 suggesting that the reader consult section 16.1 for further information about label switching and multimodality.
• [x] Finally, the transition from section 11.2 to 11.3 is confusing. Section 11.2 says that it's "pretty much impossible to perform full Bayesian analysis for clustering models" and recommends using EM or variational approaches instead, but then section 11.3 jumps right into Naive Bayes without saying anything about why this doesn't contradict 11.2. More knowledgeable people may get this, but I found it very confusing.

[bob-carpenter]

Thanks for dropping into the right issue. More below.

On Jul 2, 2014, at 4:56 PM, jonathan-g notifications@github.com wrote:

I just noticed a minor layout flaw on p. 119 (Fig. 16.1): the text of the figure caption overlaps the x-axis labels of the figures (\lambda _1, \lambda_1 and \mu), making the axis labels hard to read.

I'll fix that.

Also, it would be useful to add a cross-reference to section 11.2 suggesting that the reader consult section 16.1 for further information about label switching and multimodality.

Will do.

Finally, the transition from section 11.2 to 11.3 is confusing. Section 11.2 says that it's "pretty much impossible to perform full Bayesian analysis for clustering models" and recommends using EM or variational approaches instead, but then section 11.3 jumps right into Naive Bayes without saying anything about why this doesn't contradict 11.2. More knowledgeable people may get this, but I found it very confusing.

I'll try to break out the discussion of classification (no issue with label switching) from the clustering (all the usual issues).

I tried to push them together initially to show that it's the "same model" in the BUGS sense.

[jonathan-g]

Just a sentence to say, "Now we're changing gears from clustering to classification..." would probably suffice.

[bob-carpenter]

Avi Feller reported an error in the current formulation. There's a new function that's even a better fix.

• [x] Fix multivariate priors for hierarchical models to use:

Sigma_beta <- quad_form_diag(Sigma,tau);

• [x] and explain

quad_form_diag(Sigma,tau)  =def=  diag_matrix(tau)' * Sigma * diag_matrix(tau)

[bob-carpenter]

From Herra Huu on stan-users: The manual p. 202: The base variable types are integer, real, vector, row_vector, and matrix.

• [x] change "integer" to "int" here

[randommm]

To help you start, I fixed the typos I pointed out above and some others. They are in branch feature/issue-668-next-manual.

[PeterLi2016]

• [x] add Jonathan G to acknowledgements for pointing out typo in ARM R code (issue #763 ).
• [x] add Alexey Stukalov to acknowledgements for doc patches

[randommm]

That reminded me

• [x] add Matthew Spencer for reporting bug #644 (inv_wishart_rng and wishart_rng)