Documentation of some distributions is confusing

[michaelosthege]

Description of your problem

Most distributions support multiple parameterizations that are hard to grasp from the little description that we have. In some cases the scipy.stats documentation is not helping either.

Proposal / Ideas for improvement

• state what the default parameterization would be
• show examples with both (equal) parameterizations
• link to the scipy.stats distribution that we use internally
• link to the PyMC3 source code of the distribution (because that's what ultimately counts)
• maybe we should insert , *, to the kwargs at some point so parameterization becomes explicit?

[svjunkie]

@michaelosthege, can you provide some examples of distributions that could use clearer documentation? I reviewed some of the continuous distributions and found the following:

• Normal distributions in the Normal family define the relationship between sd and tau; they use the mean-sd parameterization in the pdf definition
• Beta distribution uses alpha and beta parameters in its definition of the pdf, followed by formulas to convert to mean-sd parameterization
• studentT distribution accepts arguments named either sigma or sd, but if sd is given, that value is assigned to sigma as shown in source here, i.e. they're equivalent. I don't see that reflected in the documentation; are you suggesting making this explicit in the docs?

After exploring a bit, I'm curious - are you asking to make explicit which parameters take precedence if two parameters describing the same characteristic of a distribution are given?

This wasn't an exhaustive review, but it'd be helpful to understand which distributions you're referencing to help focus additional efforts

[lucianopaz]

@svjunkie, the parameter name sd is deprecated, and should be replaced by sigma everywhere. If you find places without a deprecation warning, it would be great if you added it. The deprecation was done two releases ago, I think, so this could be the last release that still hassd on the distribution's signature.

[michaelosthege]

If I remember correctly, I found the Lognormal quite confusing.

[Ahanmr]

@lucianopaz I have added deprecationWarning whenever sd is passes into Normal function or any continuous, mixture or timeseries distribution function where sd is still an argument and sd is passed instead of sigma. Please do review it and let me know if there are any changes to make. Thanks.