gammavariate uses misleading parameter names.

[drj11]

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 alpha and beta are 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.)

Linked PRs

• gh-104337: Clarify random.gammavariate doc entry  #104410
• [3.11] gh-104337: Clarify random.gammavariate doc entry (GH-104410) #104481

[mdickinson]

• add a warning that these are not the conventional names.

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 alpha and beta (ref). The first hit I got in an arXiv search was this paper, which uses α and β.

[mdickinson]

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]

A Google Books search pulled up this book as the first hit, which also uses β as the scale.

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]

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]

You seem to have resolved most issues whilst i was asleep.

Agreed that this use of alpha and beta fall 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]

I propose that in https://github.com/python/cpython/blob/main/Doc/library/random.rst we replace

Conditions on the parameters are alpha > 0 and beta > 0.

with

The shape and scale parameters alpha and beta, must get positive values. (Confusingly, 'beta' is sometimes used instead for the rate parameter 1 / scale.)

@rhettinger ?

[rhettinger]

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:

- The shape and scale parameters alpha and beta, must get positive values.
+ The shape and scale parameters, alpha and beta, must have positive values.
- (Confusingly, 'beta' is sometimes used instead for the rate parameter 1 / scale.)
+ (Calling conventions vary and some sources define 'beta' as the inverse of the scale).

[terryjreedy]

PR with Raymond's improvements upon my draft.