Sum to zero matrix #879

spinkney · 2025-05-23T19:37:54Z

When I built it I didn't see any of the changes so not sure what's going on there. I didn't add the versions either. @WardBrian I can work with you on Tuesday to get this fixed.

Submission Checklist

Builds locally
New functions marked with <<{ since VERSION }>>
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):
Sean Pinkney

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/)

spinkney · 2025-05-28T15:07:24Z

@WardBrian you need anything else from me here? I'll have a bit of time tomorrow if so.

WardBrian · 2025-05-28T15:10:46Z

It looks pretty good to me overall, I'll see if @bob-carpenter can do a read since he tends to be a stricter editor

bob-carpenter

I can only say that @WardBrian warned you.

This is a lot of very detailed comments on grammar, typography and layout. Hope it all makes sense---if not, I'm happy to elaborate on particular requests. Don't feel you need to answer all these and make them "resolved" in the UI---I'm happy to review again.

bob-carpenter · 2025-05-28T15:18:12Z

src/bibtex/all.bib

+ number = {1},
+ pages = {4--12},
+ publisher = {Mathematical Association of America},
+ title = {The Helmert Matrices},


This needs to be {The {H}elmert Matrices} in order to keep the H capitalized through BibTeX.

bob-carpenter · 2025-05-28T15:23:13Z

src/functions-reference/transform_functions.qmd

 {{< since 2.37 >}}
+
+### Zero-sum matrices
+These functions perform the transform and inverse transform described in the


I'd try to make it clear that this is a separate doc, not a separate section of the same doc. And we want to say what things do, not just point to another document.

So how about:

The zero-sum matrix transforms map between unconstrained values and matrices whose rows and columns sum to zero; full definitions of the function and Jacobian can be found in the sum-to-zero matrix section of the Reference Manual.

git blame @WardBrian for this! Haha, I originally had it as a separate section

Oh wait this is in the functions reference, my bad Brian

Ah, I think I moved it so that it was sorted with the other matrices, rather than in the middle of vectors, but I didn’t audit the text while doing so

bob-carpenter · 2025-05-28T15:26:47Z

src/functions-reference/transform_functions.qmd

+\index{{\tt \bfseries sum\_to\_zero\_constrain }!{\tt (matrices y): matrices}|hyperpage}
+
+`matrices` **`sum_to_zero_constrain`**`(matrices y)`<br>\newline
+Takes a free matrix `y` and returns a matrix such that the rows and columns


This needs to be a complete sentence---it's missing a subject as is. It can also be reduced to a single line.

The constraining function maps an unconstrained N x M matrix to an (N + 1) x (M + 1) matrix for which the rows and columns all sum to zero.

bob-carpenter · 2025-05-28T15:30:43Z

src/functions-reference/transform_functions.qmd

 free matrix of size $N \times M$.
 {{< since 2.37 >}}
+
+### Zero-sum matrices


Rename to say "Sum-to-zero matrices". I got confused when writing programs as to whether to use sum_to_zero_matrix or zero_sum_matrix because we'd wavered on what to call it during design.

bob-carpenter · 2025-05-28T15:31:11Z

src/functions-reference/transform_functions.qmd

 {{< since 2.37 >}}
+
+### Zero-sum matrices
+These functions perform the transform and inverse transform described in the


The reference manual chapter should be renamed to also say "Sum-to-zero", though I have a feeling that will be a huge pain given how we link.

bob-carpenter · 2025-05-28T16:06:44Z

src/reference-manual/types.qmd


+### Matrices that sum to zero {-}
+
+A zero-sum matrix is constrained such that the


Keep the lines 80 characters or thereabouts and equal length. Otherwise, it's a huge pain to either read or see diffs.

bob-carpenter · 2025-05-28T16:07:13Z

src/reference-manual/types.qmd

+A zero-sum matrix is constrained such that the
+sum of rows and the sum of the columns is always $0$. These are sometimes useful
+for resolving identifiability issues in regression models.
+While the underlying vector has only $N - 1 \times M - 1$ degrees of freedom,


(N - 1) \times (M - 1)$ because $\times$ binds more tightly than $-$.

bob-carpenter · 2025-05-28T16:08:18Z

src/reference-manual/types.qmd

+for resolving identifiability issues in regression models.
+While the underlying vector has only $N - 1 \times M - 1$ degrees of freedom,
+zero sum matrices are declared with their full dimensionality.
+For instance, `beta` is declared to be a zero-sum $5 \times 4$-matrix (20 DoF) by


"sum-to-zero"

If it's 5 \times 4, isn't that 12 dof? Also, "dof" is usually written all lowercase like "pdf", but I'd just expand to "degrees of freedom" (no hyphens)

bob-carpenter · 2025-05-28T16:09:38Z

src/reference-manual/types.qmd

+sum_to_zero_matrix[5, 4] beta;
+```
+
+Zero sum matrices are implemented as matrices and may be assigned to other


"Sum-to-zero" with hyphens

bob-carpenter · 2025-05-28T16:10:26Z

src/reference-manual/types.qmd

+Zero sum matrices are implemented as matrices and may be assigned to other
+matrices and vice-versa.  Zero sum matrix variables, like other constrained
+variables, are validated to ensure that they are indeed zero sum; for
+zero sum matrices, this is only done up to a statically specified accuracy


I'd say "internally" rather than "statically" to indicate it's not under user control. I don't think most of our users will even understand the static/dynamic distinction in C++.

Bonus points if you can say what this threshold is.

bob-carpenter · 2025-05-28T16:13:53Z

Also, this may not look so bad, but be sure to click the "hidden conversations" box to unfold the rest of my comments---there are 30+.

If you don't have time or would prefer, I'm happy to make all these changes myself and let @WardBrian do the final review.

spinkney · 2025-05-28T16:22:17Z

No worries, I want this to be understood by the reader and having consistency and this type of review is good for that. I'll make a stab at the edits.

On the 80 line length I configured vscode to automatically have 80 line length. Or I thought I did as it was 80 on my screen but maybe it was only in my console and didn't transfer over to the file itself?

bob-carpenter · 2025-05-28T16:28:06Z

You can see the long lines in the file in the branch.

WardBrian · 2025-05-28T16:32:46Z

I believe vscode only "soft" wraps lines when requested, not actually inserting newlines into the file on disc. There are extensions that provide hard wrapping, the most popular seems to be Rewrap

spinkney · 2025-05-30T18:43:47Z

@bob-carpenter this is ready for you to review again

bob-carpenter

This looks great. Thanks so much for updating.

bob-carpenter · 2025-05-30T18:46:43Z

src/reference-manual/types.qmd

+matrices (lower triangular, positive diagonal, unit-length rows). The type
+`sum_to_zero_matrix` is for matrices that sum to zero across rows and columns.
+
+Constraints provide error checking for variables defined in the `data`, `transformed data`, `transformed parameters`, and `generated quantities` blocks.  Constraints are critical for variables declared in the `parameters` block, where they determine the transformation from constrained variables (those


This line length is still a problem but I don't want to hold something up for this.

bob-carpenter · 2025-05-30T18:47:05Z

src/reference-manual/types.qmd

 vectors and vice-versa.  Zero sum vector variables, like other constrained
-variables, are validated to ensure that they are indeed unit length; for
-zero sum  vectors, this is only done up to a statically specified accuracy
+variables, are validated to ensure that they are indeed sum to zero; for


Good catch!

src/reference-manual/transforms.qmd

spinkney · 2025-06-02T18:25:21Z

@WardBrian mind taking one last look before we merge? I updated the function name by removing constrain and noting that there is no target increment in the function because it is 0.

WardBrian · 2025-06-03T13:40:20Z

Thanks @spinkney !

spinkney added 2 commits May 23, 2025 15:17

add zero-sum-matrix

66e1a56

add to types

69d452e

WardBrian linked an issue May 27, 2025 that may be closed by this pull request

document sum to zero matrix #867

Closed

WardBrian added 2 commits May 27, 2025 10:08

Add function overloads

0611803

Reordering

901f3ff

WardBrian requested a review from bob-carpenter May 28, 2025 15:08

bob-carpenter requested changes May 28, 2025

View reviewed changes

address reviewer comments

ed2c0d2

bob-carpenter approved these changes May 30, 2025

View reviewed changes

WardBrian added 2 commits May 30, 2025 14:52

Fix links

deb51b4

Reflow long lines

cd01463

spinkney commented May 31, 2025

View reviewed changes

src/reference-manual/transforms.qmd Outdated Show resolved Hide resolved

Update transforms.qmd

064900c

WardBrian merged commit aeda4ac into master Jun 3, 2025

WardBrian deleted the sum-to-zero-matrix branch June 3, 2025 13:40


		### Matrices that sum to zero {-}

		A zero-sum matrix is constrained such that the

Uh oh!

Sum to zero matrix #879

Sum to zero matrix #879

Uh oh!

Conversation

spinkney commented May 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Submission Checklist

Summary

Copyright and Licensing

Uh oh!

spinkney commented May 28, 2025

Uh oh!

WardBrian commented May 28, 2025

Uh oh!

bob-carpenter left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bob-carpenter commented May 28, 2025

Uh oh!

spinkney commented May 28, 2025

Uh oh!

bob-carpenter commented May 28, 2025

Uh oh!

WardBrian commented May 28, 2025

Uh oh!

spinkney commented May 30, 2025

Uh oh!

bob-carpenter left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

spinkney commented Jun 2, 2025

Uh oh!

WardBrian commented Jun 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

spinkney commented May 23, 2025 •

edited

Loading