[Numpy-discussion] Question about numpy.random, especially .poisson

[Russell E. Owen]

I stumbled across code that looks like this:

imageArr = # a 2-d array of floats
noiseArr = numpy.random.poisson(imageArr)

This works fine in numpy 1.5.1 and seems to do what I would hope: return 
an array of random ints whose "expectation of interval" is set by the 
corresponding element of the input array. Very nice!

However, I can't find any documentation supporting this usage. The 
standard help says:

   poisson(lam=1.0, size=None)
    
    Draw samples from a Poisson distribution.
    
    The Poisson distribution is the limit of the Binomial
    distribution for large N.
    
    Parameters
    ----------
    lam : float
        Expectation of interval, should be >= 0.
    size : int or tuple of ints, optional
        Output shape. If the given shape is, e.g., ``(m, n, k)``, then
        ``m * n * k`` samples are drawn.

Which suggest that Iam must be a scalar.

So... is the usage of passing in an array for Iam actually 
supported/safe to use?

And is there some general rule I could have used to predict that?

I'm not complaining -- quite the opposite. But I'd hate to code up 
something that uses an unsafe API, and I'd also like to be able to 
predict nifty features like this to get the most out of numpy.

-- Russell