Some time ago, we had a discussion on updating the text of warnings for divergent transitions, treedepth etc (https://discourse.mc-stan.org/t/text-for-warning-message/), this led me @andrewgelman , @jonah and @avehtari to attempt to update the document that currently sits at https://mc-stan.org/misc/warnings.html (the link currently leads to the old version!) The idea is that this document could then be linked from warning messages in all interfaces and provide a basic overview of what the warnings mean and what one can do about them.
We’d be very happy to get feedback from broader community before making this part of the official docs.
A potential problem is that due to our background a lot of the linked resources are R centered. If you know of good resources using Python, please link them where relevant!
Beyond hopefully helping some users to figure out the problem with their model on their own, the aim is that a) it will be easier for people to find additional resources and b) even if the user is unable to resolve the problem on their own, it will be easier to help them (e.g. here on Discourse), because they’ll provide more relevant information - that’s a big reason why “Simplify your model” is the first hint provided.
Beydon the original warnings page, the text builds on Divergent transitions - a primer
The current version can be found at:
where you can directly provide comments and/or edit the text (but comments here on Discourse are also welcome)