next manual, 2.20++ #36

mitzimorris · 2019-03-22T19:07:33Z

Summary:

This is the place to record typos and brainos or suggestions for the Stan manuals: User's Guide, Reference Manual, Functions Reference. Please report broken links, incorrect code or math as well as questions and corrections to discussion and modeling advice.

Current Version:

v2.19.0

avehtari · 2019-05-17T20:35:22Z

In section Normal-Id Generalised Linear Model (Linear Regression)
normal_id_glm_lpmf should be normal_id_glm_lpdf
and 15.2.1 Probability Mass Function should be 15.2.1 Probability Distribution Function

jaehyunjoo · 2019-05-22T16:43:13Z

Just reporting minor things.

Stan User's Guide:
In section 9.2 Soft K-Means, need to remove a redundant close paren after soft_z[n]
// likelihood
for (n in 1:N)
target += log_sum_exp(soft_z[n]));

Stan Language Functions Reference:
In section 15.1 Normal Distribution, may need a close brace? \pitemTwo{y}
std_normal(\pitemTwo{y) and std_normal_lpdf( y | \pitemTwo{y)

bob-carpenter · 2019-05-23T18:38:59Z

Thanks, @jaehyunjoo. We'll get those fixed.

bertcarnell · 2019-06-18T19:18:12Z

docs/docs/2_19/functions-reference/multivariate-normal-distribution-precision-parameterization.html

Line 572 in 90cb5fd

for \(y \in \mathbb{R}^K\), \[ \text{MultiNormalPrecision}(y|\mu,\Omega)

docs/docs/2_19/functions-reference/multivariate-normal-distribution-precision-parameterization.html

Line 573 in 90cb5fd

= \text{MultiNormal}(y|\mu,\Sigma^{-1}) \]

I think that the above section should be changed from
MultiNormalPrecision(y|mu, Omega) = MultiNormal(y|mu, Sigma^-1)
to
MultiNormalPrecision(y|mu, Omega) = MultiNormal(y|mu, Omega^-1)

mitzimorris · 2019-06-18T19:45:56Z

~~@bertcarnell - good catch, many thanks!~~

~~revising above statement - docs are correct, not fixing~~

OK - @bertcarnell - absolutely correct - I made same mistake as whoever wrote this.
many thanks!

enbrown · 2019-06-22T04:21:42Z

This line in the Custom Probability Functions chapter of the User Manual doesn't show correctly in the HTML output

docs/src/stan-users-guide/custom-probability.Rmd

Line 118 in 90cb5fd

    
           \mbox{binormal\_cdf}(z_1, z_2, \rho) = \mbox{Pr}[Z_1 > z_1 \mbox{ and } Z_2 > z_2]

Additionally, to have a more consistent format in the LaTeX PDF output, it's possible that the use of \mbox{binormal\_cdf} would be better replaced by \mathtt{binormal\_cdf} so that the font of this Stan function name is in a monospaced font similar to the monospaced/console font used in the verbatim Stan code sections. There are many places throughout the documentation where using \mathtt in equations when referring to Stan functions would likely be more clear.

enbrown · 2019-06-22T04:32:41Z

These 4 equations don't render correctly in the LaTeX PDF version of the User Guide and all show up on the same line without linebreaks between the 4 equations

docs/src/stan-users-guide/latent-discrete.Rmd

Lines 42 to 50 in 90cb5fd

    
           $$ 
        
           e  \sim  \mathsf{Exponential}(r_e) 
        
           \\ 
        
           l  \sim  \mathsf{Exponential}(r_l) 
        
           \\ 
        
           s \sim  \mathsf{Uniform}(1, T) 
        
           \\ 
        
           D_t \sim  \mathsf{Poisson}(t < s \ ? \ e \ : \ l) 
        
           $$

This code works in LaTeX but I'm not sure how a LaTeX align environment outside of math mode would be processed into HTML by pandoc:

\begin{align*}
e   &\sim  \mathsf{Exponential}(r_e) \\
l   &\sim  \mathsf{Exponential}(r_l) \\
s   &\sim  \mathsf{Uniform}(1, T) \\
D_t &\sim  \mathsf{Poisson}(t < s \ ? \ e \ : \ l)
\end{align*}

If the align LaTeX environment is able to be used, then there are many places throughout the User Guide that could benefit. For example, a little later in the same chapter, the code

docs/src/stan-users-guide/latent-discrete.Rmd

Lines 79 to 87 in 90cb5fd

    
           $$ 
        
           p(e,l,s,D) 
        
            =  p(e) \, p(l) \, p(s) \, p(D | s, e, l) 
        
           \\ 
        
            =  
        
           \mathsf{Exponential}(e|r_e) \ \mathsf{Exponential}(l|r_l) \ 
        
           \mathsf{Uniform}(s|1, T) 
        
           \prod_{t=1}^T \mathsf{Poisson}(D_t | t < s \ ? \ e \ : \ l), 
        
           $$

produces an unreadably-long line in the PDF output because its all on one line. Replacing it with

\begin{align*}
p(e,l,s,D)
 &=  p(e) \, p(l) \, p(s) \, p(D | s, e, l) \\
 &=
\mathsf{Exponential}(e|r_e) \ \mathsf{Exponential}(l|r_l) \
\mathsf{Uniform}(s|1, T) \\
 &\qquad \prod_{t=1}^T \mathsf{Poisson}(D_t | t < s \ ? \ e \ : \ l),
\end{align*}

would help immensely with readability.

enbrown · 2019-06-22T04:40:03Z

There are scattered lines that show up in both the HTML and PDF outputs as cryptic references to something like id:foo-stuff.figure. One example is

docs/src/stan-users-guide/latent-discrete.Rmd

Line 175 in 90cb5fd

id:change-point-model.figure

mitzimorris · 2019-06-22T04:43:06Z

@enbrown - many thanks for all of the above. will investigate and try to address.

enbrown · 2019-06-22T04:45:59Z

Here's another table that's present in the LaTeX PDF output that seems to be missing from the HTML files

docs/src/stan-users-guide/latent-discrete.Rmd

Lines 534 to 556 in 90cb5fd

    
           \begin{center} 
        
           \begin{tabular}{c|ccc|c} 
        
           & \multicolumn{3}{|c|}{{\it captures}} 
        
           \\ 
        
           {\it profile} & 1 & 2 & 3 & {\it probability} 
        
           \\ \hline 
        
           {0} & - & - & - & n/a 
        
           \\ 
        
           {1} & - & - & + & n/a 
        
           \\ \hline 
        
           {2} & - & + & - & $\chi_2$ 
        
           \\ 
        
           {3} & - & + & + & $\phi_2 \, p_3$ 
        
           \\ \hline 
        
           {4} & + & - & - & $\chi_1$ 
        
           \\ 
        
           {5} & + & - & + & $\phi_1 \, (1 - p_2) \, \phi_2 \, p_3$ 
        
           \\ \hline 
        
           {6} & + & + & - & $ \phi_1 \, p_2 \, \chi_2$ 
        
           \\ 
        
           {7} & + & + & + & $\phi_1 \, p_2 \, \phi_2 \, p_3$ 
        
           \end{tabular} 
        
           \end{center}

enbrown · 2019-06-22T04:59:27Z

Here are some small typos in the latent-discrete.Rmd file:

doct@rs should be doctors in:

docs/src/stan-users-guide/latent-discrete.Rmd

Line 897 in 90cb5fd

doct@s say aboutpatient histories; the same model can be used

In a few places the LaTeX nonbreaking space ~ is used rather than the Markdown \ form. So in one, Equation~(2.7) should be Equation\ (2.7):

docs/src/stan-users-guide/latent-discrete.Rmd

Line 577 in 90cb5fd

in the Stan program using `target~+=` rather than

docs/src/stan-users-guide/latent-discrete.Rmd

Line 788 in 90cb5fd

In the inner loop, the observed capture status `y[i,~t]` for

docs/src/stan-users-guide/latent-discrete.Rmd

Line 1002 in 90cb5fd

Equation~(2.7), required for the E-step in their expectation

docs/src/stan-users-guide/latent-discrete.Rmd

Line 1064 in 90cb5fd

`log_q_z[i,~k]`.

The two figures in section 7.2 seem to result in broken links on the HTML website (possibly due to them being PDF images):

docs/src/stan-users-guide/latent-discrete.Rmd

Lines 277 to 279 in 90cb5fd

    
           ```{r include=TRUE, fig.align="center", fig.cap=c("Analytical change-point posterior"), echo=FALSE} 
        
           knitr::include_graphics("./img/change-point-posterior.pdf") 
        
           ```

docs/src/stan-users-guide/latent-discrete.Rmd

Lines 284 to 286 in 90cb5fd

    
           ```{r include=TRUE, fig.align="center", fig.cap=c("Sampled change-point posterior"), echo=FALSE} 
        
           knitr::include_graphics("./img/s-discrete-posterior.pdf") 
        
           ```

bob-carpenter · 2019-06-24T16:39:42Z

@enbrown Thanks so much for all the careful comments on doc.

Rather than \mbox{foo_cdf}, we should be using \textrm{foo\_cdf}. Not a big deal.

it's possible that the use of \mbox{binormal_cdf} would be better replaced by \mathtt{binormal_cdf}

I'm OK with this, but it would be a huge change throughout the doc.

WARNING: For words, we need to use \texttt{binormal\_cdf} rather than the mathtt version. Also, we should be using \textrm rather than \mbox as it scales size properly.

enbrown · 2019-06-30T07:18:18Z

I'm OK with this, but it would be a huge change throughout the doc.

Yup, its massive. I've forked the repository, made a ton of changes, and I hope created a pull request correctly. There were random typos, tables and pictures that were missing from the HTML version, text that was missing from the HTML version (but present in the LaTeX version), and fixes to the formatting of the equations (the vast majority.)

bob-carpenter · 2019-07-01T19:02:02Z

Thanks. It's a huge help to reviewing if you can break the pull requests into bite-sized chunks. If not, it's no big deal. I'll volunteer to review a mega-PR for any number of doc fixes.

…

On Jun 30, 2019, at 3:18 AM, Eric N. Brown ***@***.***> wrote: I'm OK with this, but it would be a huge change throughout the doc. Yup, its massive. I've forked the repository, made a ton of changes, and I hope created a pull request correctly. There were random typos, tables and pictures that were missing from the HTML version, text that was missing from the HTML version (but present in the LaTeX version), and fixes to the formatting of the equations (the vast majority.) — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.

mitzimorris · 2019-07-01T20:42:21Z

this looks totally awesome - happy to review your PR as is - many thanks for doing this!

enbrown · 2019-07-01T22:46:22Z

this looks totally awesome - happy to review your PR as is - many thanks for doing this!

No problem. Procrastinating with typography!

Is there a Stan code highlighting style that is used by other people? Its not too difficult to add syntax highlighting (4 line change to an _output.yml file, annotating all Stan code blocks with {.stan} and including two MIT-licensed style and theme files.)

mitzimorris · 2019-07-01T23:10:16Z

what kind of style and theme files? latex? css?

enbrown · 2019-07-02T00:44:04Z

what kind of style and theme files? latex? css?

Pandoc-based syntax highlighting:
https://github.com/enbrown/stan-docs/blob/format_stan_blocks/src/stan-users-guide/stan.xml
https://github.com/enbrown/stan-docs/blob/format_stan_blocks/src/stan-users-guide/stan.theme

The _output.yml file just needs to pass options to Pandoc to use these:
https://github.com/enbrown/stan-docs/blob/format_stan_blocks/src/stan-users-guide/_output.yml

Finally, Stan code blocks need to be identified:

``` {.stan}
data {
 ...
}
model {
  y ~ normal(0, 1)
}
```

bob-carpenter · 2019-07-02T16:06:54Z

I thought RMarkdown compiled Stan models when it saw them in markdown. We don't want to try to be compiling these things as a lot of them are just program fragments.

enbrown · 2019-07-02T17:29:43Z

RMarkdown shows code annotated like this without actually compiling anything, but it can highlight the syntax in them: make the different program blocks one color, control flow (if/then/for) another color, known functions a different color, and distributions bold. Its purely formatting like this:

When I annotated all Stan blocks in the user guide (375 I think), I didn't notice it take any longer to make the HTML and PDF outputs, but it could add a few seconds overall to the processing time.

bob-carpenter · 2019-07-02T19:03:50Z

Processing time's no big deal. It already takes a long time to generate HTML and PDF.

Thanks much for looking into this and pasting in an example.

I've never been crazy about this level of syntax highlighting. I turn on the lightest mode possible in anything I'm doing as I find all the colors and fonts distracting. I'm curious what others think on this, as I'm not the dictator of this thing.

Green and red won't work as color choices due to color blindness. Any idea why "normal" is set in the same color as "lower"? The block names should probably be a more distinct color, too.

I like the lighter color for ocmments, but I'm not crazy about the italic typewriter font. At least the font's fixed width.

enbrown · 2019-07-04T00:02:04Z

These were completely arbitrary choices (that I made based on the defaults which were worse) that can be modified at will. The font color and background color can be set to any RGB color. Then they can be bold or not, italicized or not, and underlined or not. These are the things that can be changed in the Pandoc theme.

It might be possible to delve deeper into the CSS and overwrite these choices (because the Stan codeblocks are actually in HTML <code class="sourceCode stan"> elements with  subelements that do the styling. But that's likely more trouble than its worth (although you could use that to do user-customizable style selections so someone could have WILD colors and others can be monochromatic.)

bob-carpenter · 2019-07-06T18:00:35Z

We shouldn't hold up this PR for color choices in Stan programs. Just please choose something relatively low contrast, with matching darknesses, and don't let users adjust it. We can fix it later, but discussing it ad nauseum now would literally be an instance of a classic bikeshed issue.

Let me outline some guidelines from standard book design practice:

contrast shouldn't be too high so that it's easy to read
darkness (what typographers call "color") should be matched and relatively dark
keep a minimal number of fonts (ideally one)
keep line-length down to 60 max

Together, these let you read the marked-up text like regular text much more easily and will make the text in code look more seamlessly like part of the rest of the book. Darkness is what typographers call "color". It has to match for things to be readable. And for them to be projectable. That's really the main consideration here---can people read them in print and on screen and when projected.

In the end, we want to move to a situation where we have code in actual functional program contexts that we can check for syntax, etc., then cut into the doc.

P.S. CSS would be problematic as none of the components have span styling.

mitzimorris · 2019-07-19T16:22:26Z

docs/docs/2_19/functions-reference/multivariate-normal-distribution-precision-parameterization.html

Line 572 in 90cb5fd

for \(y \in \mathbb{R}^K\), \[ \text{MultiNormalPrecision}(y|\mu,\Omega)

docs/docs/2_19/functions-reference/multivariate-normal-distribution-precision-parameterization.html

Line 573 in 90cb5fd

= \text{MultiNormal}(y|\mu,\Sigma^{-1}) \]

I think that the above section should be changed from
MultiNormalPrecision(y|mu, Omega) = MultiNormal(y|mu, Sigma^-1)
to
MultiNormalPrecision(y|mu, Omega) = MultiNormal(y|mu, Omega^-1)

the documentation is correct - this statement is relating the MultiNormalPrecision to the MultiNormal - the precision parameter Omega is related to the variance parameter Sigma.

mitzimorris · 2019-07-19T16:28:22Z

would like to close this for 2.20 release but would also like to get @enbrown's fixes in - where does this discussion stand?

bertcarnell · 2019-07-27T18:49:53Z

Sorry for missing your disagreement with my comment. I don't think that you are correct. Think about the mathematical statement that is being made, If K is an integer, and mu is a real vector, and Omega is a real square matrix, then for y as a real vector is distributed as multivariate normal using the Omega precision matrix, or equivalent, it is distributed as multivariate normal using the variance matrix (which is the Omega inverse). If you introduce the Sigma matrix here, then you haven't defined it. See the multivariate normal Cholesky parameterization as an equivalent.

bob-carpenter · 2019-07-29T21:57:06Z

See: #71

lukas-rokka · 2019-09-01T06:29:07Z

Typo on page 106 in the Function reference documentation 2.20:
"lognormal_rng(reals mu, reals beta)" should be "lognormal_rng(reals mu, reals sigma)"

Current Version:

v2.20.0

mitzimorris · 2019-09-01T08:09:52Z

good catch, many thanks, will fix!

asperamanka · 2019-10-29T13:41:23Z

In Stan function manual 2.20 chapter 15.1:
sampling statement of std_normal should be y ~ std_normal() instead of y ~ std_normal(y)

mitzimorris · 2019-10-29T13:46:11Z

good catch - thanks - will fix!

wesbarnett · 2019-11-25T17:15:41Z

Typo: "exit" -> "exist"
https://github.com/stan-dev/docs/blob/master/docs/2_21/stan-users-guide/index.html#L630

mitzimorris · 2020-01-10T21:00:56Z

that's funny!

mitzimorris · 2020-01-13T05:22:59Z

leaving this issue open until 2.22 release

note that changes suggested by enbrown have been incorporated via PRs #90 and #126

mitzimorris added this to the 2.19++ milestone Mar 22, 2019

avehtari mentioned this issue Jul 10, 2019

Typo in name of function for gaussian regression (is ..._lpmf, should be ..._lpdf) #67

Closed

bob-carpenter changed the title ~~next manual, 2.19++~~ next manual, 2.20++ Jul 29, 2019

mcol mentioned this issue Oct 23, 2019

Fix parameter name #101

Merged

2 tasks

mitzimorris closed this as completed Jul 1, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

next manual, 2.20++ #36

next manual, 2.20++ #36

mitzimorris commented Mar 22, 2019 •

edited

avehtari commented May 17, 2019 •

edited by mitzimorris

jaehyunjoo commented May 22, 2019 •

edited by mitzimorris

bob-carpenter commented May 23, 2019

bertcarnell commented Jun 18, 2019 •

edited by mitzimorris

mitzimorris commented Jun 18, 2019 •

edited

enbrown commented Jun 22, 2019 •

edited

enbrown commented Jun 22, 2019

enbrown commented Jun 22, 2019

mitzimorris commented Jun 22, 2019

enbrown commented Jun 22, 2019

enbrown commented Jun 22, 2019

bob-carpenter commented Jun 24, 2019

enbrown commented Jun 30, 2019

bob-carpenter commented Jul 1, 2019 via email

mitzimorris commented Jul 1, 2019

enbrown commented Jul 1, 2019

mitzimorris commented Jul 1, 2019

enbrown commented Jul 2, 2019

bob-carpenter commented Jul 2, 2019

enbrown commented Jul 2, 2019

bob-carpenter commented Jul 2, 2019

enbrown commented Jul 4, 2019

bob-carpenter commented Jul 6, 2019 •

edited

mitzimorris commented Jul 19, 2019

mitzimorris commented Jul 19, 2019

bertcarnell commented Jul 27, 2019

bob-carpenter commented Jul 29, 2019

lukas-rokka commented Sep 1, 2019 •

edited by mitzimorris

mitzimorris commented Sep 1, 2019

asperamanka commented Oct 29, 2019 •

edited by mitzimorris

mitzimorris commented Oct 29, 2019

wesbarnett commented Nov 25, 2019 •

edited by mitzimorris

mitzimorris commented Jan 10, 2020

mitzimorris commented Jan 13, 2020

next manual, 2.20++ #36

next manual, 2.20++ #36

Comments

mitzimorris commented Mar 22, 2019 • edited

Summary:

Current Version:

avehtari commented May 17, 2019 • edited by mitzimorris

jaehyunjoo commented May 22, 2019 • edited by mitzimorris

bob-carpenter commented May 23, 2019

bertcarnell commented Jun 18, 2019 • edited by mitzimorris

mitzimorris commented Jun 18, 2019 • edited

enbrown commented Jun 22, 2019 • edited

enbrown commented Jun 22, 2019

enbrown commented Jun 22, 2019

mitzimorris commented Jun 22, 2019

enbrown commented Jun 22, 2019

enbrown commented Jun 22, 2019

bob-carpenter commented Jun 24, 2019

enbrown commented Jun 30, 2019

bob-carpenter commented Jul 1, 2019 via email

mitzimorris commented Jul 1, 2019

enbrown commented Jul 1, 2019

mitzimorris commented Jul 1, 2019

enbrown commented Jul 2, 2019

bob-carpenter commented Jul 2, 2019

enbrown commented Jul 2, 2019

bob-carpenter commented Jul 2, 2019

enbrown commented Jul 4, 2019

bob-carpenter commented Jul 6, 2019 • edited

mitzimorris commented Jul 19, 2019

mitzimorris commented Jul 19, 2019

bertcarnell commented Jul 27, 2019

bob-carpenter commented Jul 29, 2019

lukas-rokka commented Sep 1, 2019 • edited by mitzimorris

Current Version:

mitzimorris commented Sep 1, 2019

asperamanka commented Oct 29, 2019 • edited by mitzimorris

mitzimorris commented Oct 29, 2019

wesbarnett commented Nov 25, 2019 • edited by mitzimorris

mitzimorris commented Jan 10, 2020

mitzimorris commented Jan 13, 2020

mitzimorris commented Mar 22, 2019 •

edited

avehtari commented May 17, 2019 •

edited by mitzimorris

jaehyunjoo commented May 22, 2019 •

edited by mitzimorris

bertcarnell commented Jun 18, 2019 •

edited by mitzimorris

mitzimorris commented Jun 18, 2019 •

edited

enbrown commented Jun 22, 2019 •

edited

bob-carpenter commented Jul 6, 2019 •

edited

lukas-rokka commented Sep 1, 2019 •

edited by mitzimorris

asperamanka commented Oct 29, 2019 •

edited by mitzimorris

wesbarnett commented Nov 25, 2019 •

edited by mitzimorris