104 lines
3.4 KiB
ReStructuredText
104 lines
3.4 KiB
ReStructuredText
.. 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
|
|
(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.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
|