gammavariate uses misleading parameter names. #104337
Description
Documentation for gammavariate
The parameters of the gammavariate function (in random module) are alpha, beta.
We can see, from the mathematical description given, that these correspond to shape and scale. Wikipedia conventionally describes these using the symbols k and theta. Wikipedia uses beta for rate, which is the reciprocal of scale: beta = 1/theta
This is a proposal to:
- explain that
alphaandbetaare also known as shape and scale; - reinforce that by adding that μ is proportional to scale;
- add a warning that these are not the conventional names.
or, more controversially, scrap all that and rename the parameters k and theta. I understand that the parameter names leak into the API, so maybe not this option.
Side note: there is some variability in naming convention. The only textbook i have to hand is Grimmett and Stirzaker "Probability and Random Process" (OUP, 1982). That uses Γ(λ, t) where lambda is rate and t is shape.
(A clear and concise description of the issue.)
Activity
mdickinson commentedon May 9, 2023
I'm curious: what's the algorithm for determining what the conventional names are? The first textbook I checked was DeGroot's "Probability and Statistics" (2nd edn, ISBN 0-201-11366-X), which uses α and β for the parameter names (p.286 onwards). The C++ std. lib. uses
alphaandbeta(ref). The first hit I got in an arXiv search was this paper, which uses α and β.mdickinson commentedon May 9, 2023
Hmm, sorry; I see - there's variation in whether β represents the scale or the inverse scale. Of the three references mentioned above, DeGroot has β being the inverse of the scale, while the C++ std. lib. and the paper referenced have β as the scale parameter. A Google Books search pulled up this book as the first hit, which also uses β as the scale.
So indeed there's variation, but Python's choice doesn't seem to be particularly unusual here. A note following your first suggestion ("explain that alpha and beta are also known as shape and scale") doesn't seem unreasonable, but I'm not seeing a case for the suggested warning (and still less for renaming).
mdickinson commentedon May 9, 2023
Hmm. Forget the book - that doesn't seem to be a good reference. It hedges its bets weirdly by presenting pdfs using β both as a scale parameter and an inverse scale parameter, and seems to interchange between the two inconsistently (e.g., in Ch III, the variance is computed as ɑβ²).
mdickinson commentedon May 9, 2023
One more data point: here's Wolfram Alpha:
And one more (though it's not one I'd give much weight to): whatever sources ChatGPT was trained on also seem to think of β as a scale parameter:
drj11 commentedon May 10, 2023
You seem to have resolved most issues whilst i was asleep.
Agreed that this use of
alphaandbetafall within existing accepted use, and therefore on not changing the names. Agreed (obviously) that adding a note relating to shape and scale would be useful.As for convention, i didn't claim any particular convention, i just deferred to Wikipedia (which of course, you are welcome to edit). Although i do claim that i was mislead.
terryjreedy commentedon May 10, 2023
I propose that in https://github.com/python/cpython/blob/main/Doc/library/random.rst we replace
with
@rhettinger ?
rhettinger commentedon May 11, 2023
One other source for comparison: https://support.microsoft.com/en-us/office/gamma-dist-function-9b6f1538-d11c-4d5f-8966-21f6a2201def The MS Excel docs are precise because they show the underlying probability density functions.
The suggested edit looks fine to me though I might have chosen different wording:
pythongh-104337: Clarify random.gammavariate doc entry
terryjreedy commentedon May 11, 2023
PR with Raymond's improvements upon my draft.
gh-104337: Clarify random.gammavariate doc entry (#104410)
pythongh-104337: Clarify random.gammavariate doc entry (pythonGH-104410)
[3.11] gh-104337: Clarify random.gammavariate doc entry (GH-104410) (#…
Merge branch 'main' into supermon
Merge branch 'main' into cached_property_docs