What does "see docstring of the instance object for more information" mean
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: 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`](https://github.com/scipy/scipy/blob/v0.16.1/scipy/stats/_continuous_distns.py#L191)
which is a [subclass of
`stats.rv_continuous`](https://github.com/scipy/scipy/blob/v0.16.1/scipy/stats/_continuous_distns.py#L108):

    
    
    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](http://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.norm.html#scipy-
stats-norm) 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])
    

