[Numpy-discussion] random.uniform documentation bug?

[Robert Kern]

On Tue, Feb 23, 2010 at 13:05, David Goldsmith <d.l.goldsmith at gmail.com> wrote:
> On Tue, Feb 23, 2010 at 10:29 AM, Robert Kern <robert.kern at gmail.com> wrote:
>>
>> On Tue, Feb 23, 2010 at 08:21, Alan G Isaac <aisaac at american.edu> wrote:
>> > This behavior does not match the current documentation.
>> >
>> >>>> np.random.uniform(low=0.5,high=0.5)
>> > 0.5
>> >>>> np.random.uniform(low=0.5,high=0.4)
>> > 0.48796883601707464
>> >
>> > I assume this behavior is intentional and it is
>> > the documentation that is in error (for the case
>> > when high<=low)?
>>
>> Well, the documentation just doesn't really address high<=low. In any
>> case, the claim that the results are in [low, high) is wrong thanks to
>> floating point arithmetic. It has exactly the same issues as the
>> standard library's random.uniform() and should be updated to reflect
>> that fact:
>>
>> random.uniform(a, b)
>>  Return a random floating point number N such that a <= N <= b for a
>> <= b and b <= N <= a for b < a.
>>
>>  The end-point value b may or may not be included in the range
>> depending on floating-point rounding in the equation a + (b-a) *
>> random().
>>
>>
>> We should address the high < low case in the documentation because
>> we're not going to bother raising an exception when high < low.
>
> Well, an exception isn't the only option (e.g., it could return NaN),

<shudder>

> but
> does everyone agree (or at least not block) that this is acceptable
> behavior?

It's a useful feature. Whenever there is a low/high pair of arguments,
a user frequently has to write code like so:

  low, high = min(a, b), max(a, b)

just to satisfy the argument spec of the function. This function does
not really require knowing which is which for its implementation, so
requiring them to be one way is simply arbitrariness for the sake of
arbitrariness.

> IMO, if this function is going to allow high < low, then the doc
> should _also_ be _quite_ clear that if this "feature" might mess up the
> user's program in some way, then the user will have to implement their own
> safeguard against such parameters being fed to the monster. ;-)

So do it. But please, don't use frightening terminology like you are
here. Just state the fact clearly and succinctly as in the
random.uniform() docs.

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless
enigma that is made terrible by our own mad attempt to interpret it as
though it had an underlying truth."
  -- Umberto Eco