meaning of "sigmas" in documentation

[abmantz]

In multiple places in the documentation, it's said that 1 (2) sigma levels in 2 dimensions correspond to 39% (86%) confidence. In my experience, to the extent that "N sigma levels" mean anything colloquially, they always refer to 68.3%, 95.4% etc. confidence. That means that the default behavior is indeed 1 and 2 sigma contours.

In 2D, 39% would correspond to taking Delta -2*log-posterior=1.0 in the Gaussian limit, which has occasionally led to confusion in the past. I humbly submit that even having an option to turn on such behavior is a bad move, particularly as your code doesn't even rely on this limit.

[SebastianBocquet]

I completely agree with you -- as you know I always refer to 68% and 95% levels. Our paper reviewer, however, expressed a strong opinion that the other approach should at least be an option (the JOSS review process is completely public: https://joss.theoj.org/papers/10.21105/joss.00046)

[abmantz]

Thank you for the link to the review. I vaguely remembered that the default in corner was nonstandard, but hadn't realized by just how much.

My only real point here was that the use of "sigma" in defining a probability level in 2D that your reviewer adheres to (and which bled into the pygtc documentation) is at odds with the convention used by absolutely everyone else I know of.

Anyway, if it were me I would make the other approach "an option" by making the probability levels an option, so people can explicitly pass 0.39 and so on if they insist on being obtuse. Personally, I would also grandstand about what I think the right terminology is (big surprise), but, putting that aside, I do worry that the description in the documentation will lead to confusion. (My initial reaction was: WHAT? Sebastian knows better than that!) I'd urge you to at least consider removing the mention of "sigmas" entirely in favor of explicit probabilities.