What does “see docstring of the instance object fo

Question

I feel like this is a dumb question, but when I'm in an IPython notebook and I do help on some numpy/scipy function, like say stat.norm.rvs, it frequently says, about *args and **kargs, "see docstring of the instance object for more information". How do I see this docstring if not with help(stat.norm.rvs)?

Answer 1

Don't feel dumb; sometimes it is hard to find the information you are looking for, especially when starting out. Moreover, much of the docstrings in scipy.stats are autogenerated, so they are somewhat generic, not custom-tailored. The good news is, once you undestand how to manipulate on distribution, all the others are basically the same since they share the same interface.

Let's work through an example. Since you are using IPython (great!), we can also use the question mark after an object, e.g. obj?, to find out more about the object. This shows the docstring, like help(obj), plus other useful info such as its type, where it is defined, and (for callables) its call signature.

It helps to have a picture of how things are organized. scipy.stats is a module:

In [386]: from scipy import stats

The module docstring lists many kinds of distributions.

In [394]: stats?
...
Continuous distributions
========================
   ...
   alpha             -- Alpha
   anglit            -- Anglit
   arcsine           -- Arcsine
   beta              -- Beta
   betaprime         -- Beta Prime
   ...
   norm              -- Normal (Gaussian)

There are two main classes -- stats.rv_continuous and stats.rv_discrete. Each of these distributions listed in the stats docstring is an instance of one of these two classes. stats.norm for example, is an instance of stats.norm_gen which is a subclass of stats.rv_continuous:

In [14]: type(stats.norm).mro()
Out[14]: 
[scipy.stats._continuous_distns.norm_gen,
 scipy.stats._distn_infrastructure.rv_continuous,
 scipy.stats._distn_infrastructure.rv_generic,
 object]

---

Notice that stats.norms.rvs is an instancemethod :

In [387]: stats.norm.rvs?
Type:        instancemethod
String form: <bound method norm_gen.rvs of <scipy.stats._continuous_distns.norm_gen object at 0x7f1479ba2690>>

So when later it says

The shape parameter(s) for the distribution (see docstring of the instance object for more information).

it is saying there is more information in the docstring of stats.norm:

In [401]: stats.norm?
Docstring:
A normal continuous random variable.

The location (loc) keyword specifies the mean.
The scale (scale) keyword specifies the standard deviation.
...
Methods
-------
``rvs(loc=0, scale=1, size=1, random_state=None)``
    Random variates.

From this description you can see that stats.norm.rvs(loc=10, scale=2, size=5) will return 5 random variates with mean 10 and standard deviation 2:

In [402]: stats.norm.rvs(loc=10, scale=2, size=5)
Out[402]: array([  9.82454792,   8.52106712,   7.33889233,   8.73638555,  10.90927226])

Alternatively, stats.norm is also callable -- you can pass the loc and scale "shape" parameters to "freeze" those parameters into the distribution. What you get back is called a "frozen distribution". For example, you can create a normal distribution with mean 10 and standard devation 2:

In [403]: norm = stats.norm(10, 2)

and now call the frozen distribution's rvs method to obtain 5 random variates:

In [404]: norm.rvs(5)
Out[404]: array([  7.21018883,  12.98978919,  10.99418761,  11.2050962 ,   8.27780614])