EXAMPLE_DOCSTRING.txt

.. Here follows an example docstring for a C-function.  Note that the
   signature is given.  This is done only for functions written is C,
   since Python cannot find their signature by inspection.  For all
   other functions, start with the one line description.


multivariate_normal(mean, cov[, shape])

Draw samples from a multivariate normal distribution.

The multivariate normal, multinormal or Gaussian distribution is a
generalisation of the one-dimensional normal distribution to higher
dimensions.

Such a distribution is specified by its mean and covariance matrix,
which are analogous to the mean (average or "centre") and variance
(standard deviation squared or "width") of the one-dimensional normal
distribution.

Parameters
----------
mean : (N,) ndarray
    Mean of the N-dimensional distribution.
cov : (N,N) ndarray
    Covariance matrix of the distribution.
shape : tuple of ints, optional
    Given a shape of, for example, (m,n,k), m*n*k samples are
    generated, and packed in an m-by-n-by-k arrangement.  Because each
    sample is N-dimensional, the output shape is (m,n,k,N).  If no
    shape is specified, a single sample is returned.

Returns
-------
out : ndarray
    The drawn samples, arranged according to `shape`.  If the
    shape given is (m,n,...), then the shape of `out` is is
    (m,n,...,N).

    In other words, each entry ``out[i,j,...,:]`` is an N-dimensional
    value drawn from the distribution.

See Also
--------
normal
scipy.stats.distributions.norm : Provides random variates, as well as
                                 probability density function, cumulative
                                 density function, etc.

Notes
-----
The mean is a coordinate in N-dimensional space, which represents the
location where samples are most likely to be generated.  This is
analogous to the peak of the bell curve for the one-dimensional or
univariate normal distribution.

Covariance indicates the level to which two variables vary together.
From the multivariate normal distribution, we draw N-dimensional
samples, :math:`X = [x_1, x_2, ... x_N]`.  The covariance matrix
element :math:`C_ij` is the covariance of :math:`x_i` and :math:`x_j`.
The element :math:`C_ii` is the variance of :math:`x_i` (i.e. its
"spread").

Instead of specifying the full covariance matrix, popular
approximations include:

  - Spherical covariance (`cov` is a multiple of the identity matrix)
  - Diagonal covariance (`cov` has non-negative elements, and only on
    the diagonal)

This geometrical property can be seen in two dimensions by plotting
generated data-points:

>>> mean = [0,0]
>>> cov = [[1,0],[0,100]] # diagonal covariance, points lie on x or y-axis
>>> x,y = np.random.multivariate_normal(mean,cov,5000).T

>>> import matplotlib.pyplot as plt
>>> plt.plot(x,y,'x'); plt.axis('equal'); pyplot.show()

Note that the covariance matrix must be non-negative definite.

References
----------
.. [1] A. Papoulis, "Probability, Random Variables, and Stochastic
       Processes," 3rd ed., McGraw-Hill Companies, 1991
.. [2] R.O. Duda, P.E. Hart, and D.G. Stork, "Pattern Classification,"
       2nd ed., Wiley, 2001.

Examples
--------
>>> mean = (1,2)
>>> cov = [[1,0],[1,0]]
>>> x = np.random.multivariate_normal(mean,cov,(3,3))
>>> x.shape
(3, 3, 2)

The following is probably true, given that 0.6 is roughly twice the
standard deviation:

>>> print list( (x[0,0,:] - mean) < 0.6 )
[True, True]

.. index:
   :refguide: random:distributions