stan-dev / docs

Documentation for the Stan language and CmdStan
https://mc-stan.org/docs/
Other
37 stars 107 forks source link

needs updating: Efficiency-tuning/standardizing-predictors-and-outputs #761

Closed rtrangucci closed 2 months ago

rtrangucci commented 4 months ago

Summary:

The section of the Users guide: Efficiency-tuning/standardizing-predictors-and-outputs needs to be updated, it is wrong right now.

Description:

The section describes standardizing predictors (this is OK), and an outcome (this is wrong) in a linear regression model with normal errors. The likelihood is wrong, the priors aren't specified correctly if this is to be a reparameterization. I think the section could be excised entirely, but if we want to keep it, the section needs to be rewritten so that the likelihood is correct. It could be a teachable moment in sufficient statistics, but that would require more work to write up.

Additional Information:

Provide any additional information here.

Current Version:

v2.34.0

mitzimorris commented 4 months ago

there's a lot in this chapter that needs to be updated. it would be nice to explain the affine transform syntax for non-centered parameterization instead of what's currently there: https://mc-stan.org/docs/stan-users-guide/efficiency-tuning.html#non-centered-parameterization

e.g - for zero-centered covariate with group-level variance:

parameters {
  ...
  real<lower=0> sigma_beta;  // group-level variance
  vector<multiplier=sigma_beta>[K] beta;  // non-centered parameterization
  ...
}
model {
 ...
 beta ~ std_normal();
 ....
}
rtrangucci commented 4 months ago

I agree with you, but what's in the "standardizing predictors and outputs" section isn't right probabilistically. I have a student who is learning Stan and used this section specifically to help him write his code, which amounted to a lot of lost time and extra effort on his part. I don't want other people to learn the wrong information from this section.

bob-carpenter commented 4 months ago

I agree the priority is to fix this. @rtrangucci: Were you planning to submit a PR for it? If not, can you do it, @mitzimorris? If not, I can update. We should do this ASAP---we really don't want to leave things that are just wrong lying around.

mitzimorris commented 4 months ago

I will do it.

mitzimorris commented 4 months ago

Move mentions of Riemannian HMC to a footnote as it's not exposed to Stan users via services layer?

avehtari commented 2 months ago

Can this issue be closed as #762 has been merged?