next manual, 2.18(++)

[bob-carpenter]

Summary:

This is the place to record typos and brainos or suggestions for the manual. Most of the changes for 2.18 have already been merged, but we might make another round of updates before the 2.18 release. Otherwise, these will go in the release after that.

Current Version:

v2.17.1

[bob-carpenter]

• In thematrix_exp_multiply function doc, the expanded form should read \farg{t} * \farg{A}.

[jrnold]

• Figure 23.1: Update note: "cholesky_factor_cov[K] ... are only assignable to matrices of dimensions matrix[K, K]. Update to account for generalization of choleskey_factor_cov to rectangular matrices. Perhaps update the cholesky_factor_cov row in the table. I searched for choelesky_factor_cov in the manual and didn't see any other cases in which it was stated that the matrix must be square for this type.

[bob-carpenter]

cholesky_factor_cov[K] is square---it's shorthand for cholesky_factor_cov[K, K]. cholesky_factor_cov[M, N] doesn't have to be square. That's the intent, anyway.

…

On Jul 3, 2018, at 11:39 AM, Jeffrey Arnold ***@***.***> wrote: • Figure 23.1: Update note: "cholesky_factor_cov[K] ... are only assignable to matrices of dimensions matrix[K, K]. Update to account for generalization of choleskey_factor_cov to rectangular matrices. Perhaps update the cholesky_factor_cov row in the table. I searched for choelesky_factor_cov in the manual and didn't see any other cases in which it was stated that the matrix must be square for this type. — You are receiving this because you were assigned. Reply to this email directly, view it on GitHub, or mute the thread.

[jrnold]

Okay, I read it as still implying that cholesky_factor_cov itself has to be square; and the table itself doesn't have any mention of a non-square cholesky _factor_cov.

[ihincks]

• In the subsection “Correlation Matrix Inverse Transform”: It reads that tanh maps into (0,1), but I think it should read (-1,1).

[bob-carpenter]

Thanks, @ihincks. I'll fix that for 2.19, which should be out soon. 2.18 should be released in a few days, then we are targeting a mid-August release of 2.19.

[bob-carpenter]

• Remove the doc for abs because it's not vectorized (or vectorize it, but that's not a doc issue).

This came up with a post of @andrewgelman's on the forums

[bob-carpenter]

• explain why hierarchical models don't have MLEs other than when given zero-avoiding priors

[bob-carpenter]

• Qualify the statement "The Stan interfaces provide a mechanism for specifying a sequence of system paths in which to search for include files." to say "may provide".

[bob-carpenter]

From a forum question of aornugent's

The output of each mapped function is concatenated to produce the output of map_rect.

Will this be concatenated in the same order as the sharded input data, or by whichever worker terminates first?

• clarify that it's the order of the inputs

[jjramsey]

• I noticed that in the Stan functions reference, the documentation for the *_rng functions still says that they can only be used in the generated quantities block, even though they now can be used in the transformed data block as well (http://andrewgelman.com/2017/06/16/stan-weekly-roundup-16-june-2017/).

[bob-carpenter]

Thanks, @jjramsey --- I'll fix.

[jjramsey]

• There are some Markdown errors in the new reference manual. On page 28, after the heading "Array index style" is the text "{#array-index-style.footnote}". On page 131, instead of "Variable declarations and compound definitions" appearing in a header font, it just appears as the text "### Variable declarations and compound definitions {-}".

[jjramsey]

• There's a very minor issue with the users' guide PDF. In the section "Priors for length-scale", it reads "In this case, an inverse gamma, inv_gamma_lpdf in StanâAZs language, will work well", where the part that reads "StanâAZs language" is a bit garbled. It looks like the problem is that in the LaTeX source file examples.tex, the apostrophe in "Stan's" is represented by a Unicode "RIGHT SINGLE QUOTATION MARK" (code point U+2019) instead of an ASCII apostrophe.

[bob-carpenter]

Thanks, @jjramsey. That'll be easy to fix. I should do a general search for non-ASCII characters.

[bob-carpenter]

• Originally from @ryan-richt onn Documentation stops mid-sentence stan#2617

I'm not sure what the rest of the sentence is supposed to be, but the suspense is killing me ;-)

FYI:

https://github.com/stan-dev/stan/blob/01a09e735e2d0f880ab9219d469afce18d1b1934/src/docs/users-guide/examples.tex#L3342

PS. I tried instead to follow this link from the contributing guidelines, but it shows zero such open issues:

https://github.com/stan-dev/stan/issues?utf8=%E2%9C%93&q=is%3Aopen%20label%3ABug%20%22next%20manual%22%20label%3ADocumentation

[bob-carpenter]

• Add Ben's suggestion for truncated RNGs:

https://discourse.mc-stan.org/t/rng-for-truncated-distributions/3122/7?u=bgoodri

We could potentially generalize using the algebraic solver to compute general inverse CDFs, but I haven't tried it. There's more advice on doubly truncated things from @nschiett in:

stan-dev/math#214 (comment)

[bob-carpenter]

From @avehtari on stan-dev/stan#2639:

The reference manual reference-manual-2.18.0.pdf downloaded from
https://github.com/stan-dev/stan/releases/download/v2.18.0/reference-manual-2.18.0.pdf

• is missing some text at the end of page 153
• Figure 14.1 is on page 153, but the caption is on page 152

(these are probably due switch to bookdown, but I don't know how to fix these)

[bob-carpenter]

• create a map_rect example that has different sizes for x and y.

• write a simple version that groups by single element and deals with one output and three predictors

[bob-carpenter]

From DouglasBoubert in this discourse thread reported:

The user guide (stan-reference-2.17.0.pdf) describes the inc_beta function as being the first integral in section F.2. Stan actually implements the inc_beta function as the second integral, i.e. as the regularised incomplete beta function.

This is the same design choice made in several other languages (for instance, scipy implements it this way), but

• the documentation should make this clear!

[mitzimorris]

• could you please make the language in the reference manual w/r/t reserved words and variable names completely unambiguous - I was confused by this one:

Variable names will not conflict with the following block identifiers,

functions, model, data, parameters, quantities,
transformed, generated

I interpreted "will not conflict" in the opposite way from its intended meaning - i.e., I thought that you could name variables data and that wouldn't be a conflict. how about the following:

The following block identifiers are reserved and cannot be used as variable names:

[bob-carpenter]

• update http:// links to https:// for mc-stan.org, github.com, and discourse.mc-stan.org.

This was originally submitted by @junpenglao as PR stan-dev/stan#2624 before the docs were moved to R markdown.

[mitzimorris]

[x] Figure 23.1: Update note: "cholesky_factor_cov[K] ... are only assignable to matrices of dimensions matrix[K, K]. Update to account for generalization of choleskey_factor_cov to rectangular matrices. Perhaps update the cholesky_factor_cov row in the table. I searched for choelesky_factor_cov in the manual and didn't see any other cases in which it was stated that the matrix must be square for this type.

added explanation of use of variable K, M, and N to discussion in following paragraph.

[mitzimorris]

Originally from @ryan-richt onn stan-dev/stan#2617

I'm not sure what the rest of the sentence is supposed to be, but the suspense is killing me ;-)

FYI:

https://github.com/stan-dev/stan/blob/01a09e735e2d0f880ab9219d469afce18d1b1934/src/docs/users-guide/examples.tex#L3342

The transformed parameter Sigma could be defined as a local variable within the model block if it does not need to be included in the sampler's output.

[ryan-richt]

Summary:

• qr_R doc text has an error

Description:

Currently it reads:

matrix qr_R(matrix A)
The upper trapezoidal matrix in the fat QR decomposition of A, 
which implies that the resulting matrix will be square with the same number of rows as A

I think that the last part should say "...the resulting matrix will be rectangular with the same dimensions as A"

Additional Information:

If I run the program:

data {
  int n;
  int p;
  matrix[n,p] ss_v1;
}
model {
}
generated quantities {
  matrix[n,p] foo;
  {
    foo = qr_R(ss_v1);
  }
}

with Data:

  val matrix = Seq[Seq[Double]](Seq(17, 9, 13), Seq(9, 22, 31), Seq(13, 31, 50), Seq(1, 4, 9), Seq(8, 20, 36), Seq(21, 48, 81))

I get back the rectangular matrix:

Vector(
  Vector(32.3265, 59.5797, 97.3815), 
  Vector(-0.0, 26.3868, 45.1378), 
  Vector(-0.0, -0.0, 6.88628), 
  Vector(0.0, 0.0, 0.0), 
  Vector(0.0, 0.0, 0.0), 
  Vector(0.0, 0.0, 0.0)
)

Which seems to confirm the change. If I change the dimensions of the generated quantity to be N x N or P x P, it does not compile in CmdStan.

Current Version:

v2.18.0

[mitzimorris]

[ ] explain why hierarchical models don't have MLEs other than when given zero-avoiding priors

this would require some plots - specifically?

[mitzimorris]

• from jjramsey -

Thanks, @jjramsey. That'll be easy to fix. I should do a general search for non-ASCII characters.

searched all Rmd files for non-ASCII characters using magic find/grep incantation:

find . -name "*.Rmd" -print -exec ggrep --color='auto' -P -n "[^\x00-\x7F]" {} \;
(ggrep == homebrew's install of grep for Mac OSX)

[mitzimorris]

• from https://github.com/bbonnet

Hi! Just reporting a minor typo in time-series.Rmd

heteroscedasticity: ### they allow the scale of the noise terms

[zottelef]

• from @zottelef -

In the Multi-Logit Regression section of the Stan User's Guide
the line:

y[n] ~ categorical_logit(x_beta[n]);

should be changed in

y[n] ~ categorical_logit(x_beta[n]');

to avoid a SYNTAX ERROR.
Moreover to be coherent with the text that states a normal(0,5) prior on beta, the line

to_vector(beta) ~ normal(0, 2);

should be changed to

to_vector(beta) ~ normal(0, 5);

[bob-carpenter]

Thanks, @zottelef. We'll fix those. We're trying to figure out how to do syntax checking on all the fragments without having to write our own manual infrastructure.

[mitzimorris]

to be coherent with the text that states a normal(0,5) prior on beta

more subtle problem to address is checking recommendations for priors are up-to-date and that priors in code match recommendations

[lwiklendt]

• from @lwiklendt -

Under "Dropping uniform mixture ratios" in the "Finite Mixtures" chapter, a mixing ratio of 0.5 is modelled as negative log half. Should this be positive log half?

[bob-carpenter]

Yes, it should be positive log half. We'll fix for the next release. Thanks for reporting.

[bob-carpenter]

• from @bnicenboim on There is an error in the rng for the truncated normal #29

In https://mc-stan.org/docs/2_18/stan-users-guide/truncated-random-number-generation.html
all the examples with normal_rng should have inv_Phi instead of Phi. See also https://discourse.mc-stan.org/t/rng-for-truncated-distributions/3122/10.

[mitzimorris]

• from @VMatthijs on Broken reference in Gaussian process section of users guide #34

The hyperlink to the section Priors for Gaussian Process Parameters in the users guide for 2.18 is not working.
Search for "Priors for Gaussian Process Parameters {#priors-gp.section}" and you will see the problem. I think this is only a problem in the html version.

[mitzimorris]

closing this issue and opening a new one for 2.19.