Possible error in user guide and reference manual

General
1

Is it possible there are two minor errors with the use of indices in the user guide and reference manual (both version 2.25)?

In the reference manual p.32, the examples for defining g and x don’t seem mutually compatible. If x=g[2]=f[5,2], should g=f[5] rather than the stated g=f[2]?

Similarly, in the user’s guide p.203, the examples using vector ‘b’ and row vector ‘c’ at the top of the page don’t seem correct. They both pull data out of matrix array ‘a’ using indices for 4 dimensions, but ‘a’ only has 3. Could it be that both of these examples are meant to use matrix array ‘m’ instead, which does have 4 dimensions?

It is entirely possible I am wrong about both of these and have simply misunderstood something about indexing. In that case, any hints as to where I go off the road would be very welcome.

2

you seem to be misinterpreting these examples - they are just assignment statements which demonstrate how multi-dim indexing works.

f is a matrix; selecting a row of a matrix produces a row-vector.
any row of f can be assigned to a row_vector[5]; g is such a variable.

As shown, the result f[2] of supplying a single index to a matrix is the indexed row, here row 2 of matrix f.

no, again, this is an example of how multi-dim indexing works.

the index expressions with “:” pick out several elements; these examples of assignment do have matching shapes and sizes. try to write out the examples to convince yourself of this.

3

Hi Mitzi,

Thanks for your answer. I spent some extra time looking at the examples to make sure, but I still don’t quite see how they’re supposed to work.

Specifically, in the User’s guide, the declarations are these:

matrix[3, 4] m[5, 7];
matrix[3, 4] a[2];

And the examples that draw from it are the following:

vector[2] b;
b = a[1, 3, 2:3, 2];

row_vector[3] c[2];
c = a[4:5, 3, 1, 2: ];

As I currently understand it, commas separate the indices for different dimensions, so both of these definition statements (try to) access 4 different dimensions in the source array. That’s why I wondered if they were actually meant to refer to array m instead of a. In that case, I could read the first call as taking element [1,3] out of the array, yielding a matrix, and then elements [2,2] and [3,2] out of that matrix, yielding the desired 2-element column vector (and similar for c). If the calls actually do refer to array a, I don’t really know how to interpret them at all. In that case, could you give me some clue how to proceed, please?

For the Reference manual, my comment was didactic much more than syntactic. The given list is introduced as legal definitions, and that much is clear.

matrix[6, 5] d[3, 4];
matrix[6, 5] e[4];
matrix[6, 5] f;
row_vector[5] g;
real x;

e = d[1];        // result is array of matrices
f = d[1,3];      // result is matrix
f = e[3];        //   same result as above
g = d[1,3,2];    // result is row vector
g = e[3,2];      //   same result as above
g = f[2];        //   same result as above
x = d[1,3,5,2];  // result is scalar
x = e[3,5,2];    //   same result as above
x = f[5,2];      //   same result as above
x = g[2];        //   same result as above

However, it seems like the intent is to show how working down through the layers of dimensions one by one is synonymous to punching through with all desired indices in a single line. Assuming that is the case (and assuming I understand these indices correctly, of course), the three lines for g each point to the matrix in position d[1,3] and then the 2nd row out of that matrix. The first three lines for x, however, point to the 5th row (of the same matrix). I was simply wondering if the lines for g here were actually meant to read:
g = d[1,3,5];
g = e[3,5];
g = f[5];
That way the definitions for x would all be synonymous, which they currently are not (again, assuming I have not completely misunderstood indexing).

My apologies that this got so lengthy, by the way. I’ve erred on the side of precision. Hopefully it all makes at least some sense.

4

you are entirely correct - this example is both confused and confusing.

issues here

  • the Reference Guide and User’s Manual examples are too terse, also wrong
  • the Stanc3 parser thinks that expression ‘a[1, 1, 1:2, 1]’ is allowed; the generated c++ code doesn’t compile - (i.e., the C++ compiler agrees with you).

many thanks for bringing this to our attention - will file issues posthaste!

update: filed issues: use of multi-dim index operators confuse parser - generated code doesn't compile · Issue #757 · stan-dev/stanc3 · GitHub, documentation on multi-dim indexing in Reference Guide, User's Manual · Issue #295 · stan-dev/docs · GitHub

1 Like
5

Thanks for confirming. I’m glad it’s the examples that are wrong rather than my understanding. The opposite would not have boded well for model building.

1 Like