Better document the 'mr' parameter to 'metrop_select'.

[bangerth]

I found myself confused why metrop_select() has this comparison:

    if np.isfinite(mr) and np.log(uniform()) < mr:

If mr was just a ratio of probabilities, as one would typically see in theoretical descriptions, then it should be compared to uniform(), not the log. But mr is the logarithm of the ratio -- something not clear from the documentation, but that can be added :-)

---

📚 Documentation preview 📚: https://pymc--7160.org.readthedocs.build/en/7160/

[welcome]

]
💖 Thanks for opening this pull request! 💖 The PyMC community really appreciates your time and effort to contribute to the project. Please make sure you have read our Contributing Guidelines and filled in our pull request template to the best of your ability.

[ricardoV94]

Can this be summarized a bit more. Isn't it enough to say it's the logarithm of the ratio of probabilities?

[bangerth]

In places where it is called, the variable passed in here is typically called delta_logp. I wanted to explain the parameter in a way that explains the origin of the name.

[ricardoV94]

I understand but it's too verbose in my opinion. Logarithm of probability ratio is pretty explicit. If you look in the database you'll quickly get used to seeing everything working on log scales

[OriolAbril]

The parameter description should be (and should have been) on a different line, with only the parameter name and its type in the first line:

mr : float
    description
    which
    can be
    multiline

it looks like this class isn't on the website listed api docs so not fixing won't result in rendering errors unless/until it is added to the website.