New User's Guide Intro, SEM, and user-defined constrained parameters chapters

General
1

After feedback from @WardBrian and @mitzimorris, I just merged two new chapters for the User’s Guide right up front in a new introductory part.

  1. The Stan Ecosystem
  2. How Stan Works

I’m not sure what the schedule is for releasing doc after we merge, but I think it should be live before our next release.

Chapter (1) tries to explain where everything is, so it’s a rehash of a lot of what’s on our web pages, but spelled out linearly with a bit more explanation.

Chapter (2) is a short overview of how the language works, including variables, blocks, and transforms.

I’m nearly done writing two more chapters:

(n) Structure equation models
(n + 1) Custom constrained parameters

Hopefully (n) is self explanatory. I’m just going over notation and showing how to code in Stan explicitly and with soft zero constraints. I met Ken Bollen (author of the main textbook in the area) at the Modern Modeling Methods conference and have been getting clarification as to whether I correctly understand the notation (that shrinking non-linked correlations to zero still feels wrong but I don’t plan to editorialize in the chapter). Of course, I mention blavaan as the thing to use if your model fits it.

For (n + 1), I’m writing about a bunch of different constraints that we don’t talk about elsehwere.

A. Orthonormal, orthogonal, and rotation matrices
B. Matrices matching specified margins with sum-to-zero matrix (thanks, @spinkney)
C. Fun shapes (from BUGS) like discs, hollow squares, rings, paralellograms, hexagons, etc.

I plan to add Sarah Heaps’s stationarity constraints for vector autoregressive (VAR) models to (n + 1). Then once these are in the User’s Guide, we can move some of them into the language itself. The User’s Guide is like our Boost :-).

I’m open to suggestions on what else to include in both new chapters. I’m particularly looking for constraints that might be widely used or illustrate a general technique.

2

You can parameterize exact 0s in the correlation matrix. I showed this as the 2024 stancon. I can help write that if you need.

On tables with given row and column sums, an additional constraint is that the interior cells be non-negative. A sum to zero matrix doesn’t enforce that last constraint. If the marginal sums are sufficiently large then the largest negative deviation from the sum to zero matrix is typically small enough to keep the cell contained to be non-negative. Otherwise, there’s a couple ways to parameterize this additional constraint.

How much more do you want to add? There’s linear equalities, linear inequalities (you can solve Ax < b or do it telescopically if you have parameters that depend on others), and ordered matrix.

3

I mean that, sometimes one wants an additional positivity constraint.

4

Thanks for the reminder, @spinkney.

I found the video:

and the matching paper:

https://arxiv.org/pdf/2405.07286

After equation (2), it allows range based bounds, but explicitly excludes the case where the lower bound (a) is equal to the upper bound (b), -1 \leq a_{i,j} < C_{i, j} < b_{i,j} \leq 1. The paper says it handles “known zeroes”, but I don’t see where that’s done. Wouldn’t it have to reduce the dimensionality of the inputs below n \choose 2, for example, if all the off-diagonal values were constrained to zero.

5

Yes, that’s correct. I have R and Stan code for this in open-talks/structured-corr-stancon24/R/code.R at main · spinkney/open-talks · GitHub