You are viewing an older version (2.4.3). Go to latest (2.4.4)
{ } Raw JSON

bundles / numpy 2.4.3 / numpy / random / RandomState / multivariate_normal

cython_function_or_method

numpy.random:RandomState.multivariate_normal

Signature

def   multivariate_normal ( mean cov size = None check_valid = warn tol = 1e-08 )

Summary

Draw random samples from a multivariate normal distribution.

Extended Summary

The multivariate normal, multinormal or Gaussian distribution is a generalization of the one-dimensional normal distribution to higher dimensions. Such a distribution is specified by its mean and covariance matrix. These parameters are analogous to the mean (average or "center") and variance (standard deviation, or "width," squared) of the one-dimensional normal distribution.

Parameters

mean : 1-D array_like, of length N

Mean of the N-dimensional distribution.

cov : 2-D array_like, of shape (N, N)

Covariance matrix of the distribution. It must be symmetric and positive-semidefinite for proper sampling.

size : int or 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 (N-D) sample is returned.

check_valid : { 'warn', 'raise', 'ignore' }, optional

Behavior when the covariance matrix is not positive semidefinite.

tol : float, optional

Tolerance when checking the singular values in covariance matrix. cov is cast to double before the check.

Returns

out : ndarray

The drawn samples, of shape size, if that was provided. If not, the shape is (N,).

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

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, . The covariance matrix element is the covariance of and . The element is the variance of (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

Diagonal covariance means that the variables are independent, and the probability density contours have their axes aligned with the coordinate axes:

>>> import matplotlib.pyplot as plt
>>> x, y = np.random.multivariate_normal(mean, cov, 5000).T
>>> plt.plot(x, y, 'x')
>>> plt.axis('equal')
>>> plt.show()

Note that the covariance matrix must be positive semidefinite (a.k.a. nonnegative-definite). Otherwise, the behavior of this method is undefined and backwards compatibility is not guaranteed.

Examples

mean = (1, 2)
cov = [[1, 0], [0, 1]]
x = np.random.multivariate_normal(mean, cov, (3, 3))
x.shape
Here we generate 800 samples from the bivariate normal distribution with mean [0, 0] and covariance matrix [[6, -3], [-3, 3.5]]. The expected variances of the first and second components of the sample are 6 and 3.5, respectively, and the expected correlation coefficient is -3/sqrt(6*3.5) ≈ -0.65465.
cov = np.array([[6, -3], [-3, 3.5]])
pts = np.random.multivariate_normal([0, 0], cov, size=800)
Check that the mean, covariance, and correlation coefficient of the sample are close to the expected values:
pts.mean(axis=0)
np.cov(pts.T)
np.corrcoef(pts.T)[0, 1]
We can visualize this data with a scatter plot. The orientation of the point cloud illustrates the negative correlation of the components of this sample.
import matplotlib.pyplot as plt
plt.plot(pts[:, 0], pts[:, 1], '.', alpha=0.5)
plt.axis('equal')
plt.grid()
plt.show()
fig-3d41906365f3822e.png

See also

random.Generator.multivariate_normal

which should be used for new code.

Aliases

  • numpy.random.multivariate_normal
  • numpy.random.RandomState.multivariate_normal

Referenced by