row/col stochastic matrix documentation #807

SteveBronder · 2024-08-20T20:39:47Z

Adds docs for row and column stochastic matrix types.

I tried not to repeat myself too much by doing something similar to what Eigen does for csr matrices and csc matrices. I mostly explained the column_stochastic_matrix type and noted the differences for row_stochastic_matrix when necessary. Is that alright?

Submission Checklist

Builds locally
New functions marked with <<{ since VERSION }>>
- Is there an example of this in the docs somewhere?
Declare copyright holder and open-source license: see below

Summary

Copyright and Licensing

Please list the copyright holder for the work you are submitting (this will be you or your assignee, such as a university or company): Simons Foundation

By submitting this pull request, the copyright holder is agreeing to license the submitted work under the following licenses:

Code: BSD 3-clause (https://opensource.org/licenses/BSD-3-Clause)
Documentation: CC BY-ND 4.0 (https://creativecommons.org/licenses/by-nd/4.0/)

bob-carpenter

Thanks for writing this up. I had a bajillion little detailed comments here---sorry about that in advance.

bob-carpenter · 2024-08-30T17:53:54Z

src/reference-manual/transforms.qmd

+\sum_{i=1}^N X_{ij} = 1.
+$$
+
+A row stochastic matrix is defined similarly but with the axis flipped such


Just as easy to say a row stochastic matrix is any matrix whose transpose is a column stochastic matrix.

I would also say in words that a column stochastic matrix has columns that are simplexes, whereas the row version has rows that are simplexes.

I've tried to write matrix subscripts as "i, j" rather than "ij" to allow for multiple-character subscripts.

Agree, can't believe I forgot to just say what this is in simple terms

bob-carpenter · 2024-08-30T17:54:11Z

src/reference-manual/transforms.qmd

@@ -672,6 +672,72 @@ z_k
 .
 $$

+## Stochastic Matrix {#stochastic-matrix-transform.section}
+
+The `column_stochastic_matrix[N, M]` and `row_stochastic_matrix[N, M]` type in 


We've used "col" everywhere else for column. Should this match?

discussed irl, we are wishy washy with col vs column abbreviation, but I like column here so going to keep it

bob-carpenter · 2024-08-30T17:54:45Z

src/reference-manual/transforms.qmd

+\sum_{j=1}^N X_{ij} = 1.
+$$
+
+This definition ensures that each column(row) of the matrix \(X\) lies on the 


space between column and ( --- this also appears later

Just stick to $X$ to match the rest of our doc.

Yes, I had a reason for why I did that (eigen docs did column(row)), but it looks like they fixed it in their docs so I'll fix it here as well

bob-carpenter · 2024-08-30T17:58:15Z

src/reference-manual/types.qmd

+A stochastic matrix is a matrix where each column, row, or both is a 
+unit simplex, meaning that each column(row) vector has non-negative 
+values that sum to 1. For example, a \(3 \times 4\) 
+column stochastic matrix will look like:


I'd say:

"The following example is a $3 \times 4$ column-stochastic matrix."

Note that it's a period at the end this way and doesn't assert that a column stochastic matrix will look one way or another. Also note that when you use a noun compound like "column stochastic" as an adjective (here modifying "matrix") then it should be hyphenated.

Also fixed Column-matrix below

bob-carpenter · 2024-08-30T17:59:03Z

src/reference-manual/types.qmd

+\end{bmatrix}
+$$
+
+While a row stochastic matrix will look like:


This isn't a complete sentence---it's just a free-floating clause. How about:

"An example of a row-stochastic matrix is the following."

bob-carpenter · 2024-08-30T18:04:30Z

src/reference-manual/types.qmd

+each column represents a probability distribution across a 
+set of categories, such as in multiple multinomial distributions, 
+transition matrices in Markov models, or compositional data analysis. 
+They can also be used in situations where multiple Dirichlet-distributed v


I'd drop the Dirichlet comment here. You can just say they can be used whenever you need multiple simplexes of the same dimensionality.

The other big application here is factor models, so you should definitely mention those. The rows in the row stochastic matrix in these models is, for exmaple, is something like the proportion of pollutants being emitted from a factory.

Added factor model to the examples

bob-carpenter · 2024-08-30T18:04:47Z

src/reference-manual/types.qmd

+ariables are required across different dimensions.
+
+The `column_stochastic_matrix` and `row_stochastic_matrix` types are declared 
+with full dimensionality. For instance, a matrix `theta` with 


full dimensionality ---> row and column sizes

bob-carpenter · 2024-08-30T18:04:56Z

src/reference-manual/types.qmd

+column_stochastic_matrix[3, 4] theta;
+```
+
+A matrix `theta` with 


Too many line breaks.

bob-carpenter · 2024-08-30T18:05:31Z

src/reference-manual/types.qmd

+row_stochastic_matrix[3, 4] theta;
+```
+
+As with simplexes, `column(row)_stochastic_matrix` variables are subject to 


This is too hard to parse---just repeat, we have tons of space here. That is, separate out column_stochastic_matrix and row_stochastic_matrix.

bob-carpenter · 2024-08-30T18:06:16Z

src/reference-manual/types.qmd

+
+#### Stability Considerations {-}
+
+In high-dimensional settings or when the matrix has many columns, 


It's not clear how "high-dimensional" and "has many columns" differ. Is high-dimensional the rows? I'd just say "high-dimensional" here.

bob-carpenter

Just a couple cosmetic changes and this is good to go.

bob-carpenter · 2024-09-30T16:39:38Z

src/reference-manual/transforms.qmd

+the lower-triangular Jacobian matrix. This determinant is calculated as:
+
+$$
+\left| \det J_j \right| = \prod_{i=1}^{N-1} \left( z_{i, j} (1 - z_{i, j}) \left( 1 - \sum_{i'=1}^{i-1} X_{i'j} \right) \right).


J_j is unfortunate notation. We've tried to maintain a convention of using n in 1:N for indexing with lower case matching the name of the upper case bounds. So I'd take this to be J_m for m in 1:M. And similarly, convert the earlier thing to using n.

I've also tried to use commas between indexes everywhere---you're doing this in some places (like z) but not others (like X). Please make this consistently use commas.

bob-carpenter · 2024-09-30T16:41:12Z

src/reference-manual/types.qmd

+### Stochastic Matrices {-}
+
+A stochastic matrix is a matrix where each column, row, or both is a
+unit simplex, meaning that each column (row) vector has non-negative


Please remove the "both" description here as we're not providing that functionality for users (at least not yet!).

SteveBronder added 2 commits August 20, 2024 15:57

start row/col stochastic matrix documentation

a67ed63

cleanup initial row/col stochastic matrix docs

8370bdb

SteveBronder changed the title ~~start row/col stochastic matrix documentation~~ row/col stochastic matrix documentation Aug 20, 2024

WardBrian linked an issue Aug 20, 2024 that may be closed by this pull request

Document stochastic matrix transforms #801

Open

WardBrian requested a review from bob-carpenter August 21, 2024 19:14

bob-carpenter requested changes Aug 30, 2024

View reviewed changes

update with @bob-carpenter review comments

84af3f8

SteveBronder requested a review from bob-carpenter September 18, 2024 14:13

bob-carpenter requested changes Sep 30, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

row/col stochastic matrix documentation #807

row/col stochastic matrix documentation #807

SteveBronder commented Aug 20, 2024

bob-carpenter left a comment

bob-carpenter Aug 30, 2024

SteveBronder Sep 16, 2024

bob-carpenter Aug 30, 2024

SteveBronder Sep 16, 2024

bob-carpenter Aug 30, 2024

SteveBronder Sep 16, 2024

bob-carpenter Aug 30, 2024

SteveBronder Sep 16, 2024

bob-carpenter Aug 30, 2024

bob-carpenter Aug 30, 2024

SteveBronder Sep 16, 2024

bob-carpenter Aug 30, 2024

SteveBronder Sep 16, 2024

bob-carpenter Aug 30, 2024

SteveBronder Sep 16, 2024

bob-carpenter Aug 30, 2024

bob-carpenter Aug 30, 2024

bob-carpenter left a comment

bob-carpenter Sep 30, 2024

bob-carpenter Sep 30, 2024


		#### Stability Considerations {-}

		In high-dimensional settings or when the matrix has many columns,

row/col stochastic matrix documentation #807

Are you sure you want to change the base?

row/col stochastic matrix documentation #807

Conversation

SteveBronder commented Aug 20, 2024

Submission Checklist

Summary

Copyright and Licensing

bob-carpenter left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bob-carpenter left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment