random integer function names are less helpful than they could be #2987

Open
njsmith opened this Issue Feb 14, 2013 · 1 comment

Comments

Projects
None yet
3 participants
Owner

njsmith commented Feb 14, 2013

np.random contains two functions to generate random integers: randint and random_integers. Anyone know what the difference is without checking the docs...?

(randint treats its range as half-open [low, high) like other ranges in python; random_integers treats it as closed like [low, high].)

The Python stdlib is not much better, with randrange and randint, but at least randrange makes its semantics obvious from the name (it has the same semantics as the standard range function), and randint is a wart that predates randrange and survives for backwards compatibility.

For extra points, the mapping is:

  • numpy randint = stdlib randrange
  • numpy random_integers = stdlib randint

Can we at least add a proper np.random.randrange function? (Extra points if we add support for the step argument at the same time; stdlib randrange supports this.) That's the key one we need to follow Python convention. And maybe we should deprecate our randint at the same time?

Contributor

anntzer commented May 7, 2015

A related issue is that the docs for these functions could probably use some improvement:

For randint:

    See Also
    --------
    random.random_integers : similar to `randint`, only for the closed
        interval [`low`, `high`], and 1 is the lowest value if `high` is
        omitted. In particular, this other one is the one to use to generate
        uniformly distributed discrete non-integers. # <--- What does that mean?

For random_integers:

    Notes
    -----
    To sample from N evenly spaced floating-point numbers between a and b,
    use::

      a + (b - a) * (np.random.random_integers(N) - 1) / (N - 1.)
    # I'm pretty sure everyone would just call `randint` instead of subtracting 1.

(followed by some example.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment