stats._multivariate

Module Contents

Classes

_PSD(self,M,cond=None,rcond=None,lower=True,check_finite=True,allow_singular=True) Compute coordinated functions of a symmetric positive semidefinite matrix.
multi_rv_generic(self,seed=None) Class which encapsulates common functionality between all multivariate
multi_rv_frozen() Class which encapsulates common functionality between all frozen
multivariate_normal_gen(self,seed=None) r
multivariate_normal_frozen(self,mean=None,cov=1,allow_singular=False,seed=None,maxpts=None,abseps=1e-05,releps=1e-05)
matrix_normal_gen(self,seed=None) r
matrix_normal_frozen(self,mean=None,rowcov=1,colcov=1,seed=None)
dirichlet_gen(self,seed=None) r
dirichlet_frozen(self,alpha,seed=None)
wishart_gen(self,seed=None) r
wishart_frozen(self,df,scale,seed=None) Create a frozen Wishart distribution.
invwishart_gen(self,seed=None) r
invwishart_frozen(self,df,scale,seed=None)
multinomial_gen(self,seed=None) r
multinomial_frozen(self,n,p,seed=None) r
special_ortho_group_gen(self,seed=None) r
special_ortho_group_frozen(self,dim=None,seed=None)
ortho_group_gen(self,seed=None) r
random_correlation_gen(self,seed=None) r
unitary_group_gen(self,seed=None) r

Functions

_squeeze_output(out) Remove single-dimensional entries from array and convert to scalar,
_eigvalsh_to_eps(spectrum,cond=None,rcond=None) Determine which eigenvalues are “small” given the spectrum.
_pinv_1d(v,eps=1e-05) A helper function for computing the pseudoinverse.
_dirichlet_check_parameters(alpha)
_dirichlet_check_input(alpha,x)
_lnB(alpha) r
_cho_inv_batch(a,check_finite=True) Invert the matrices a_i, using a Cholesky factorization of A, where
_squeeze_output(out)

Remove single-dimensional entries from array and convert to scalar, if necessary.

_eigvalsh_to_eps(spectrum, cond=None, rcond=None)

Determine which eigenvalues are “small” given the spectrum.

This is for compatibility across various linear algebra functions that should agree about whether or not a Hermitian matrix is numerically singular and what is its numerical matrix rank. This is designed to be compatible with scipy.linalg.pinvh.

spectrum : 1d ndarray
Array of eigenvalues of a Hermitian matrix.
cond, rcond : float, optional
Cutoff for small eigenvalues. Singular values smaller than rcond * largest_eigenvalue are considered zero. If None or -1, suitable machine precision is used.
eps : float
Magnitude cutoff for numerical negligibility.
_pinv_1d(v, eps=1e-05)

A helper function for computing the pseudoinverse.

v : iterable of numbers
This may be thought of as a vector of eigenvalues or singular values.
eps : float
Values with magnitude no greater than eps are considered negligible.
v_pinv : 1d float ndarray
A vector of pseudo-inverted numbers.
class _PSD(M, cond=None, rcond=None, lower=True, check_finite=True, allow_singular=True)

Compute coordinated functions of a symmetric positive semidefinite matrix.

This class addresses two issues. Firstly it allows the pseudoinverse, the logarithm of the pseudo-determinant, and the rank of the matrix to be computed using one call to eigh instead of three. Secondly it allows these functions to be computed in a way that gives mutually compatible results. All of the functions are computed with a common understanding as to which of the eigenvalues are to be considered negligibly small. The functions are designed to coordinate with scipy.linalg.pinvh() but not necessarily with np.linalg.det() or with np.linalg.matrix_rank().

M : array_like
Symmetric positive semidefinite matrix (2-D).
cond, rcond : float, optional
Cutoff for small eigenvalues. Singular values smaller than rcond * largest_eigenvalue are considered zero. If None or -1, suitable machine precision is used.
lower : bool, optional
Whether the pertinent array data is taken from the lower or upper triangle of M. (Default: lower)
check_finite : bool, optional
Whether to check that the input matrices contain only finite numbers. Disabling may give a performance gain, but may result in problems (crashes, non-termination) if the inputs do contain infinities or NaNs.
allow_singular : bool, optional
Whether to allow a singular matrix. (Default: True)

The arguments are similar to those of scipy.linalg.pinvh().

__init__(M, cond=None, rcond=None, lower=True, check_finite=True, allow_singular=True)
pinv()
class multi_rv_generic(seed=None)

Class which encapsulates common functionality between all multivariate distributions.

__init__(seed=None)
random_state()

Get or set the RandomState object for generating random variates.

This can be either None or an existing RandomState object.

If None (or np.random), use the RandomState singleton used by np.random. If already a RandomState instance, use it. If an int, use a new RandomState instance seeded with seed.

random_state(seed)
_get_random_state(random_state)
class multi_rv_frozen

Class which encapsulates common functionality between all frozen multivariate distributions.

random_state()
random_state(seed)
class multivariate_normal_gen(seed=None)

r A multivariate normal random variable.

The mean keyword specifies the mean. The cov keyword specifies the covariance matrix.

pdf(x, mean=None, cov=1, allow_singular=False)
Probability density function.
logpdf(x, mean=None, cov=1, allow_singular=False)
Log of the probability density function.
cdf(x, mean=None, cov=1, allow_singular=False, maxpts=1000000*dim, abseps=1e-5, releps=1e-5)
Cumulative distribution function.
logcdf(x, mean=None, cov=1, allow_singular=False, maxpts=1000000*dim, abseps=1e-5, releps=1e-5)
Log of the cumulative distribution function.
rvs(mean=None, cov=1, size=1, random_state=None)
Draw random samples from a multivariate normal distribution.
entropy()
Compute the differential entropy of the multivariate normal.
x : array_like
Quantiles, with the last axis of x denoting the components.

%(_mvn_doc_default_callparams)s %(_doc_random_state)s

Alternatively, the object may be called (as a function) to fix the mean and covariance parameters, returning a “frozen” multivariate normal random variable:

rv = multivariate_normal(mean=None, cov=1, allow_singular=False)
  • Frozen object with the same methods but holding the given mean and covariance fixed.

%(_mvn_doc_callparams_note)s

The covariance matrix cov must be a (symmetric) positive semi-definite matrix. The determinant and inverse of cov are computed as the pseudo-determinant and pseudo-inverse, respectively, so that cov does not need to have full rank.

The probability density function for multivariate_normal is

where is the mean, the covariance matrix, and is the dimension of the space where takes values.

New in version 0.14.0.

>>> import matplotlib.pyplot as plt
>>> from scipy.stats import multivariate_normal
>>> x = np.linspace(0, 5, 10, endpoint=False)
>>> y = multivariate_normal.pdf(x, mean=2.5, cov=0.5); y
array([ 0.00108914,  0.01033349,  0.05946514,  0.20755375,  0.43939129,
        0.56418958,  0.43939129,  0.20755375,  0.05946514,  0.01033349])
>>> fig1 = plt.figure()
>>> ax = fig1.add_subplot(111)
>>> ax.plot(x, y)

The input quantiles can be any shape of array, as long as the last axis labels the components. This allows us for instance to display the frozen pdf for a non-isotropic random variable in 2D as follows:

>>> x, y = np.mgrid[-1:1:.01, -1:1:.01]
>>> pos = np.dstack((x, y))
>>> rv = multivariate_normal([0.5, -0.2], [[2.0, 0.3], [0.3, 0.5]])
>>> fig2 = plt.figure()
>>> ax2 = fig2.add_subplot(111)
>>> ax2.contourf(x, y, rv.pdf(pos))
__init__(seed=None)
__call__(mean=None, cov=1, allow_singular=False, seed=None)

Create a frozen multivariate normal distribution.

See multivariate_normal_frozen for more information.

_process_parameters(dim, mean, cov)

Infer dimensionality from mean or covariance matrix, ensure that mean and covariance are full vector resp. matrix.

_process_quantiles(x, dim)

Adjust quantiles array so that last axis labels the components of each data point.

_logpdf(x, mean, prec_U, log_det_cov, rank)
x : ndarray
Points at which to evaluate the log of the probability density function
mean : ndarray
Mean of the distribution
prec_U : ndarray
A decomposition such that np.dot(prec_U, prec_U.T) is the precision matrix, i.e. inverse of the covariance matrix.
log_det_cov : float
Logarithm of the determinant of the covariance matrix
rank : int
Rank of the covariance matrix.

As this function does no argument checking, it should not be called directly; use ‘logpdf’ instead.

logpdf(x, mean=None, cov=1, allow_singular=False)

Log of the multivariate normal probability density function.

x : array_like
Quantiles, with the last axis of x denoting the components.

%(_mvn_doc_default_callparams)s

pdf : ndarray or scalar
Log of the probability density function evaluated at x

%(_mvn_doc_callparams_note)s

pdf(x, mean=None, cov=1, allow_singular=False)

Multivariate normal probability density function.

x : array_like
Quantiles, with the last axis of x denoting the components.

%(_mvn_doc_default_callparams)s

pdf : ndarray or scalar
Probability density function evaluated at x

%(_mvn_doc_callparams_note)s

_cdf(x, mean, cov, maxpts, abseps, releps)
x : ndarray
Points at which to evaluate the cumulative distribution function.
mean : ndarray
Mean of the distribution
cov : array_like
Covariance matrix of the distribution
maxpts: integer
The maximum number of points to use for integration
abseps: float
Absolute error tolerance
releps: float
Relative error tolerance

As this function does no argument checking, it should not be called directly; use ‘cdf’ instead.

New in version 1.0.0.

logcdf(x, mean=None, cov=1, allow_singular=False, maxpts=None, abseps=1e-05, releps=1e-05)

Log of the multivariate normal cumulative distribution function.

x : array_like
Quantiles, with the last axis of x denoting the components.

%(_mvn_doc_default_callparams)s maxpts: integer, optional

The maximum number of points to use for integration (default 1000000*dim)
abseps: float, optional
Absolute error tolerance (default 1e-5)
releps: float, optional
Relative error tolerance (default 1e-5)
cdf : ndarray or scalar
Log of the cumulative distribution function evaluated at x

%(_mvn_doc_callparams_note)s

New in version 1.0.0.

cdf(x, mean=None, cov=1, allow_singular=False, maxpts=None, abseps=1e-05, releps=1e-05)

Multivariate normal cumulative distribution function.

x : array_like
Quantiles, with the last axis of x denoting the components.

%(_mvn_doc_default_callparams)s maxpts: integer, optional

The maximum number of points to use for integration (default 1000000*dim)
abseps: float, optional
Absolute error tolerance (default 1e-5)
releps: float, optional
Relative error tolerance (default 1e-5)
cdf : ndarray or scalar
Cumulative distribution function evaluated at x

%(_mvn_doc_callparams_note)s

New in version 1.0.0.

rvs(mean=None, cov=1, size=1, random_state=None)

Draw random samples from a multivariate normal distribution.

%(_mvn_doc_default_callparams)s size : integer, optional

Number of samples to draw (default 1).

%(_doc_random_state)s

rvs : ndarray or scalar
Random variates of size (size, N), where N is the dimension of the random variable.

%(_mvn_doc_callparams_note)s

entropy(mean=None, cov=1)

Compute the differential entropy of the multivariate normal.

%(_mvn_doc_default_callparams)s

h : scalar
Entropy of the multivariate normal distribution

%(_mvn_doc_callparams_note)s

class multivariate_normal_frozen(mean=None, cov=1, allow_singular=False, seed=None, maxpts=None, abseps=1e-05, releps=1e-05)
__init__(mean=None, cov=1, allow_singular=False, seed=None, maxpts=None, abseps=1e-05, releps=1e-05)

Create a frozen multivariate normal distribution.

mean : array_like, optional
Mean of the distribution (default zero)
cov : array_like, optional
Covariance matrix of the distribution (default one)
allow_singular : bool, optional
If this flag is True then tolerate a singular covariance matrix (default False).
seed : None or int or np.random.RandomState instance, optional
This parameter defines the RandomState object to use for drawing random variates. If None (or np.random), the global np.random state is used. If integer, it is used to seed the local RandomState instance Default is None.
maxpts: integer, optional
The maximum number of points to use for integration of the cumulative distribution function (default 1000000*dim)
abseps: float, optional
Absolute error tolerance for the cumulative distribution function (default 1e-5)
releps: float, optional
Relative error tolerance for the cumulative distribution function (default 1e-5)

When called with the default parameters, this will create a 1D random variable with mean 0 and covariance 1:

>>> from scipy.stats import multivariate_normal
>>> r = multivariate_normal()
>>> r.mean
array([ 0.])
>>> r.cov
array([[1.]])
logpdf(x)
pdf(x)
logcdf(x)
cdf(x)
rvs(size=1, random_state=None)
entropy()

Computes the differential entropy of the multivariate normal.

h : scalar
Entropy of the multivariate normal distribution
class matrix_normal_gen(seed=None)

r A matrix normal random variable.

The mean keyword specifies the mean. The rowcov keyword specifies the among-row covariance matrix. The ‘colcov’ keyword specifies the among-column covariance matrix.

pdf(X, mean=None, rowcov=1, colcov=1)
Probability density function.
logpdf(X, mean=None, rowcov=1, colcov=1)
Log of the probability density function.
rvs(mean=None, rowcov=1, colcov=1, size=1, random_state=None)
Draw random samples.
X : array_like
Quantiles, with the last two axes of X denoting the components.

%(_matnorm_doc_default_callparams)s %(_doc_random_state)s

Alternatively, the object may be called (as a function) to fix the mean and covariance parameters, returning a “frozen” matrix normal random variable:

rv = matrix_normal(mean=None, rowcov=1, colcov=1)
  • Frozen object with the same methods but holding the given mean and covariance fixed.

%(_matnorm_doc_callparams_note)s

The covariance matrices specified by rowcov and colcov must be (symmetric) positive definite. If the samples in X are , then rowcov must be and colcov must be . mean must be the same shape as X.

The probability density function for matrix_normal is

where is the mean, the among-row covariance matrix, the among-column covariance matrix.

The allow_singular behaviour of the multivariate_normal distribution is not currently supported. Covariance matrices must be full rank.

The matrix_normal distribution is closely related to the multivariate_normal distribution. Specifically, (the vector formed by concatenating the columns of ) has a multivariate normal distribution with mean and covariance (where is the Kronecker product). Sampling and pdf evaluation are for the matrix normal, but for the equivalent multivariate normal, making this equivalent form algorithmically inefficient.

New in version 0.17.0.

>>> from scipy.stats import matrix_normal
>>> M = np.arange(6).reshape(3,2); M
array([[0, 1],
       [2, 3],
       [4, 5]])
>>> U = np.diag([1,2,3]); U
array([[1, 0, 0],
       [0, 2, 0],
       [0, 0, 3]])
>>> V = 0.3*np.identity(2); V
array([[ 0.3,  0. ],
       [ 0. ,  0.3]])
>>> X = M + 0.1; X
array([[ 0.1,  1.1],
       [ 2.1,  3.1],
       [ 4.1,  5.1]])
>>> matrix_normal.pdf(X, mean=M, rowcov=U, colcov=V)
0.023410202050005054
>>> # Equivalent multivariate normal
>>> from scipy.stats import multivariate_normal
>>> vectorised_X = X.T.flatten()
>>> equiv_mean = M.T.flatten()
>>> equiv_cov = np.kron(V,U)
>>> multivariate_normal.pdf(vectorised_X, mean=equiv_mean, cov=equiv_cov)
0.023410202050005054
__init__(seed=None)
__call__(mean=None, rowcov=1, colcov=1, seed=None)

Create a frozen matrix normal distribution.

See matrix_normal_frozen for more information.

_process_parameters(mean, rowcov, colcov)

Infer dimensionality from mean or covariance matrices. Handle defaults. Ensure compatible dimensions.

_process_quantiles(X, dims)

Adjust quantiles array so that last two axes labels the components of each data point.

_logpdf(dims, X, mean, row_prec_rt, log_det_rowcov, col_prec_rt, log_det_colcov)
dims : tuple
Dimensions of the matrix variates
X : ndarray
Points at which to evaluate the log of the probability density function
mean : ndarray
Mean of the distribution
row_prec_rt : ndarray
A decomposition such that np.dot(row_prec_rt, row_prec_rt.T) is the inverse of the among-row covariance matrix
log_det_rowcov : float
Logarithm of the determinant of the among-row covariance matrix
col_prec_rt : ndarray
A decomposition such that np.dot(col_prec_rt, col_prec_rt.T) is the inverse of the among-column covariance matrix
log_det_colcov : float
Logarithm of the determinant of the among-column covariance matrix

As this function does no argument checking, it should not be called directly; use ‘logpdf’ instead.

logpdf(X, mean=None, rowcov=1, colcov=1)

Log of the matrix normal probability density function.

X : array_like
Quantiles, with the last two axes of X denoting the components.

%(_matnorm_doc_default_callparams)s

logpdf : ndarray
Log of the probability density function evaluated at X

%(_matnorm_doc_callparams_note)s

pdf(X, mean=None, rowcov=1, colcov=1)

Matrix normal probability density function.

X : array_like
Quantiles, with the last two axes of X denoting the components.

%(_matnorm_doc_default_callparams)s

pdf : ndarray
Probability density function evaluated at X

%(_matnorm_doc_callparams_note)s

rvs(mean=None, rowcov=1, colcov=1, size=1, random_state=None)

Draw random samples from a matrix normal distribution.

%(_matnorm_doc_default_callparams)s size : integer, optional

Number of samples to draw (default 1).

%(_doc_random_state)s

rvs : ndarray or scalar
Random variates of size (size, dims), where dims is the dimension of the random matrices.

%(_matnorm_doc_callparams_note)s

class matrix_normal_frozen(mean=None, rowcov=1, colcov=1, seed=None)
__init__(mean=None, rowcov=1, colcov=1, seed=None)

Create a frozen matrix normal distribution.

%(_matnorm_doc_default_callparams)s seed : None or int or np.random.RandomState instance, optional

If int or RandomState, use it for drawing the random variates. If None (or np.random), the global np.random state is used. Default is None.
>>> from scipy.stats import matrix_normal
>>> distn = matrix_normal(mean=np.zeros((3,3)))
>>> X = distn.rvs(); X
array([[-0.02976962,  0.93339138, -0.09663178],
       [ 0.67405524,  0.28250467, -0.93308929],
       [-0.31144782,  0.74535536,  1.30412916]])
>>> distn.pdf(X)
2.5160642368346784e-05
>>> distn.logpdf(X)
-10.590229595124615
logpdf(X)
pdf(X)
rvs(size=1, random_state=None)
_dirichlet_check_parameters(alpha)
_dirichlet_check_input(alpha, x)
_lnB(alpha)

r Internal helper function to compute the log of the useful quotient

%(_dirichlet_doc_default_callparams)s

B : scalar
Helper quotient, internal use only
class dirichlet_gen(seed=None)

r A Dirichlet random variable.

The alpha keyword specifies the concentration parameters of the distribution.

New in version 0.15.0.

pdf(x, alpha)
Probability density function.
logpdf(x, alpha)
Log of the probability density function.
rvs(alpha, size=1, random_state=None)
Draw random samples from a Dirichlet distribution.
mean(alpha)
The mean of the Dirichlet distribution
var(alpha)
The variance of the Dirichlet distribution
entropy(alpha)
Compute the differential entropy of the Dirichlet distribution.
x : array_like
Quantiles, with the last axis of x denoting the components.

%(_dirichlet_doc_default_callparams)s %(_doc_random_state)s

Alternatively, the object may be called (as a function) to fix concentration parameters, returning a “frozen” Dirichlet random variable:

rv = dirichlet(alpha)
  • Frozen object with the same methods but holding the given concentration parameters fixed.

Each entry must be positive. The distribution has only support on the simplex defined by

The probability density function for dirichlet is

where

and , the concentration parameters and is the dimension of the space where takes values.

Note that the dirichlet interface is somewhat inconsistent. The array returned by the rvs function is transposed with respect to the format expected by the pdf and logpdf.

__init__(seed=None)
__call__(alpha, seed=None)
_logpdf(x, alpha)
x : ndarray
Points at which to evaluate the log of the probability density function

%(_dirichlet_doc_default_callparams)s

As this function does no argument checking, it should not be called directly; use ‘logpdf’ instead.

logpdf(x, alpha)

Log of the Dirichlet probability density function.

x : array_like
Quantiles, with the last axis of x denoting the components.

%(_dirichlet_doc_default_callparams)s

pdf : ndarray or scalar
Log of the probability density function evaluated at x.
pdf(x, alpha)

The Dirichlet probability density function.

x : array_like
Quantiles, with the last axis of x denoting the components.

%(_dirichlet_doc_default_callparams)s

pdf : ndarray or scalar
The probability density function evaluated at x.
mean(alpha)

Compute the mean of the dirichlet distribution.

%(_dirichlet_doc_default_callparams)s

mu : ndarray or scalar
Mean of the Dirichlet distribution.
var(alpha)

Compute the variance of the dirichlet distribution.

%(_dirichlet_doc_default_callparams)s

v : ndarray or scalar
Variance of the Dirichlet distribution.
entropy(alpha)

Compute the differential entropy of the dirichlet distribution.

%(_dirichlet_doc_default_callparams)s

h : scalar
Entropy of the Dirichlet distribution
rvs(alpha, size=1, random_state=None)

Draw random samples from a Dirichlet distribution.

%(_dirichlet_doc_default_callparams)s size : int, optional

Number of samples to draw (default 1).

%(_doc_random_state)s

rvs : ndarray or scalar
Random variates of size (size, N), where N is the dimension of the random variable.
class dirichlet_frozen(alpha, seed=None)
__init__(alpha, seed=None)
logpdf(x)
pdf(x)
mean()
var()
entropy()
rvs(size=1, random_state=None)
class wishart_gen(seed=None)

r A Wishart random variable.

The df keyword specifies the degrees of freedom. The scale keyword specifies the scale matrix, which must be symmetric and positive definite. In this context, the scale matrix is often interpreted in terms of a multivariate normal precision matrix (the inverse of the covariance matrix).

pdf(x, df, scale)
Probability density function.
logpdf(x, df, scale)
Log of the probability density function.
rvs(df, scale, size=1, random_state=None)
Draw random samples from a Wishart distribution.
entropy()
Compute the differential entropy of the Wishart distribution.
x : array_like
Quantiles, with the last axis of x denoting the components.

%(_doc_default_callparams)s %(_doc_random_state)s

Alternatively, the object may be called (as a function) to fix the degrees of freedom and scale parameters, returning a “frozen” Wishart random variable:

rv = wishart(df=1, scale=1)
  • Frozen object with the same methods but holding the given degrees of freedom and scale fixed.

invwishart, chi2

%(_doc_callparams_note)s

The scale matrix scale must be a symmetric positive definite matrix. Singular matrices, including the symmetric positive semi-definite case, are not supported.

The Wishart distribution is often denoted

where is the degrees of freedom and is the scale matrix.

The probability density function for wishart has support over positive definite matrices ; if , then its PDF is given by:

If (Wishart) then (inverse Wishart).

If the scale matrix is 1-dimensional and equal to one, then the Wishart distribution collapses to the distribution.

New in version 0.16.0.

[1]M.L. Eaton, “Multivariate Statistics: A Vector Space Approach”, Wiley, 1983.
[2]W.B. Smith and R.R. Hocking, “Algorithm AS 53: Wishart Variate Generator”, Applied Statistics, vol. 21, pp. 341-345, 1972.
>>> import matplotlib.pyplot as plt
>>> from scipy.stats import wishart, chi2
>>> x = np.linspace(1e-5, 8, 100)
>>> w = wishart.pdf(x, df=3, scale=1); w[:5]
array([ 0.00126156,  0.10892176,  0.14793434,  0.17400548,  0.1929669 ])
>>> c = chi2.pdf(x, 3); c[:5]
array([ 0.00126156,  0.10892176,  0.14793434,  0.17400548,  0.1929669 ])
>>> plt.plot(x, w)

The input quantiles can be any shape of array, as long as the last axis labels the components.

__init__(seed=None)
__call__(df=None, scale=None, seed=None)

Create a frozen Wishart distribution.

See wishart_frozen for more information.

_process_parameters(df, scale)
_process_quantiles(x, dim)

Adjust quantiles array so that last axis labels the components of each data point.

_process_size(size)
_logpdf(x, dim, df, scale, log_det_scale, C)
x : ndarray
Points at which to evaluate the log of the probability density function
dim : int
Dimension of the scale matrix
df : int
Degrees of freedom
scale : ndarray
Scale matrix
log_det_scale : float
Logarithm of the determinant of the scale matrix
C : ndarray
Cholesky factorization of the scale matrix, lower triagular.

As this function does no argument checking, it should not be called directly; use ‘logpdf’ instead.

logpdf(x, df, scale)

Log of the Wishart probability density function.

x : array_like
Quantiles, with the last axis of x denoting the components. Each quantile must be a symmetric positive definite matrix.

%(_doc_default_callparams)s

pdf : ndarray
Log of the probability density function evaluated at x

%(_doc_callparams_note)s

pdf(x, df, scale)

Wishart probability density function.

x : array_like
Quantiles, with the last axis of x denoting the components. Each quantile must be a symmetric positive definite matrix.

%(_doc_default_callparams)s

pdf : ndarray
Probability density function evaluated at x

%(_doc_callparams_note)s

_mean(dim, df, scale)
dim : int
Dimension of the scale matrix

%(_doc_default_callparams)s

As this function does no argument checking, it should not be called directly; use ‘mean’ instead.

mean(df, scale)

Mean of the Wishart distribution

%(_doc_default_callparams)s

mean : float
The mean of the distribution
_mode(dim, df, scale)
dim : int
Dimension of the scale matrix

%(_doc_default_callparams)s

As this function does no argument checking, it should not be called directly; use ‘mode’ instead.

mode(df, scale)

Mode of the Wishart distribution

Only valid if the degrees of freedom are greater than the dimension of the scale matrix.

%(_doc_default_callparams)s

mode : float or None
The Mode of the distribution
_var(dim, df, scale)
dim : int
Dimension of the scale matrix

%(_doc_default_callparams)s

As this function does no argument checking, it should not be called directly; use ‘var’ instead.

var(df, scale)

Variance of the Wishart distribution

%(_doc_default_callparams)s

var : float
The variance of the distribution
_standard_rvs(n, shape, dim, df, random_state)
n : integer
Number of variates to generate
shape : iterable
Shape of the variates to generate
dim : int
Dimension of the scale matrix
df : int
Degrees of freedom
random_state : np.random.RandomState instance
RandomState used for drawing the random variates.

As this function does no argument checking, it should not be called directly; use ‘rvs’ instead.

_rvs(n, shape, dim, df, C, random_state)
n : integer
Number of variates to generate
shape : iterable
Shape of the variates to generate
dim : int
Dimension of the scale matrix
df : int
Degrees of freedom
scale : ndarray
Scale matrix
C : ndarray
Cholesky factorization of the scale matrix, lower triangular.

%(_doc_random_state)s

As this function does no argument checking, it should not be called directly; use ‘rvs’ instead.

rvs(df, scale, size=1, random_state=None)

Draw random samples from a Wishart distribution.

%(_doc_default_callparams)s size : integer or iterable of integers, optional

Number of samples to draw (default 1).

%(_doc_random_state)s

rvs : ndarray
Random variates of shape (size) + (dim, dim), where `dim is the dimension of the scale matrix.

%(_doc_callparams_note)s

_entropy(dim, df, log_det_scale)
dim : int
Dimension of the scale matrix
df : int
Degrees of freedom
log_det_scale : float
Logarithm of the determinant of the scale matrix

As this function does no argument checking, it should not be called directly; use ‘entropy’ instead.

entropy(df, scale)

Compute the differential entropy of the Wishart.

%(_doc_default_callparams)s

h : scalar
Entropy of the Wishart distribution

%(_doc_callparams_note)s

_cholesky_logdet(scale)

Compute Cholesky decomposition and determine (log(det(scale)).

scale : ndarray
Scale matrix.
c_decomp : ndarray
The Cholesky decomposition of scale.
logdet : scalar
The log of the determinant of scale.

This computation of logdet is equivalent to np.linalg.slogdet(scale). It is ~2x faster though.

class wishart_frozen(df, scale, seed=None)

Create a frozen Wishart distribution.

df : array_like
Degrees of freedom of the distribution
scale : array_like
Scale matrix of the distribution
seed : None or int or np.random.RandomState instance, optional
This parameter defines the RandomState object to use for drawing random variates. If None (or np.random), the global np.random state is used. If integer, it is used to seed the local RandomState instance Default is None.
__init__(df, scale, seed=None)
logpdf(x)
pdf(x)
mean()
mode()
var()
rvs(size=1, random_state=None)
entropy()
_cho_inv_batch(a, check_finite=True)

Invert the matrices a_i, using a Cholesky factorization of A, where a_i resides in the last two dimensions of a and the other indices describe the index i.

Overwrites the data in a.

a : array
Array of matrices to invert, where the matrices themselves are stored in the last two dimensions.
check_finite : bool, optional
Whether to check that the input matrices contain only finite numbers. Disabling may give a performance gain, but may result in problems (crashes, non-termination) if the inputs do contain infinities or NaNs.
x : array
Array of inverses of the matrices a_i.

scipy.linalg.cholesky : Cholesky factorization of a matrix

class invwishart_gen(seed=None)

r An inverse Wishart random variable.

The df keyword specifies the degrees of freedom. The scale keyword specifies the scale matrix, which must be symmetric and positive definite. In this context, the scale matrix is often interpreted in terms of a multivariate normal covariance matrix.

pdf(x, df, scale)
Probability density function.
logpdf(x, df, scale)
Log of the probability density function.
rvs(df, scale, size=1, random_state=None)
Draw random samples from an inverse Wishart distribution.
x : array_like
Quantiles, with the last axis of x denoting the components.

%(_doc_default_callparams)s %(_doc_random_state)s

Alternatively, the object may be called (as a function) to fix the degrees of freedom and scale parameters, returning a “frozen” inverse Wishart random variable:

rv = invwishart(df=1, scale=1)
  • Frozen object with the same methods but holding the given degrees of freedom and scale fixed.

wishart

%(_doc_callparams_note)s

The scale matrix scale must be a symmetric positive definite matrix. Singular matrices, including the symmetric positive semi-definite case, are not supported.

The inverse Wishart distribution is often denoted

where is the degrees of freedom and is the scale matrix.

The probability density function for invwishart has support over positive definite matrices ; if , then its PDF is given by:

If (inverse Wishart) then (Wishart).

If the scale matrix is 1-dimensional and equal to one, then the inverse Wishart distribution collapses to the inverse Gamma distribution with parameters shape = and scale = .

New in version 0.16.0.

[1]M.L. Eaton, “Multivariate Statistics: A Vector Space Approach”, Wiley, 1983.
[2]M.C. Jones, “Generating Inverse Wishart Matrices”, Communications in Statistics - Simulation and Computation, vol. 14.2, pp.511-514, 1985.
>>> import matplotlib.pyplot as plt
>>> from scipy.stats import invwishart, invgamma
>>> x = np.linspace(0.01, 1, 100)
>>> iw = invwishart.pdf(x, df=6, scale=1)
>>> iw[:3]
array([  1.20546865e-15,   5.42497807e-06,   4.45813929e-03])
>>> ig = invgamma.pdf(x, 6/2., scale=1./2)
>>> ig[:3]
array([  1.20546865e-15,   5.42497807e-06,   4.45813929e-03])
>>> plt.plot(x, iw)

The input quantiles can be any shape of array, as long as the last axis labels the components.

__init__(seed=None)
__call__(df=None, scale=None, seed=None)

Create a frozen inverse Wishart distribution.

See invwishart_frozen for more information.

_logpdf(x, dim, df, scale, log_det_scale)
x : ndarray
Points at which to evaluate the log of the probability density function.
dim : int
Dimension of the scale matrix
df : int
Degrees of freedom
scale : ndarray
Scale matrix
log_det_scale : float
Logarithm of the determinant of the scale matrix

As this function does no argument checking, it should not be called directly; use ‘logpdf’ instead.

logpdf(x, df, scale)

Log of the inverse Wishart probability density function.

x : array_like
Quantiles, with the last axis of x denoting the components. Each quantile must be a symmetric positive definite matrix.

%(_doc_default_callparams)s

pdf : ndarray
Log of the probability density function evaluated at x

%(_doc_callparams_note)s

pdf(x, df, scale)

Inverse Wishart probability density function.

x : array_like
Quantiles, with the last axis of x denoting the components. Each quantile must be a symmetric positive definite matrix.

%(_doc_default_callparams)s

pdf : ndarray
Probability density function evaluated at x

%(_doc_callparams_note)s

_mean(dim, df, scale)
dim : int
Dimension of the scale matrix

%(_doc_default_callparams)s

As this function does no argument checking, it should not be called directly; use ‘mean’ instead.

mean(df, scale)

Mean of the inverse Wishart distribution

Only valid if the degrees of freedom are greater than the dimension of the scale matrix plus one.

%(_doc_default_callparams)s

mean : float or None
The mean of the distribution
_mode(dim, df, scale)
dim : int
Dimension of the scale matrix

%(_doc_default_callparams)s

As this function does no argument checking, it should not be called directly; use ‘mode’ instead.

mode(df, scale)

Mode of the inverse Wishart distribution

%(_doc_default_callparams)s

mode : float
The Mode of the distribution
_var(dim, df, scale)
dim : int
Dimension of the scale matrix

%(_doc_default_callparams)s

As this function does no argument checking, it should not be called directly; use ‘var’ instead.

var(df, scale)

Variance of the inverse Wishart distribution

Only valid if the degrees of freedom are greater than the dimension of the scale matrix plus three.

%(_doc_default_callparams)s

var : float
The variance of the distribution
_rvs(n, shape, dim, df, C, random_state)
n : integer
Number of variates to generate
shape : iterable
Shape of the variates to generate
dim : int
Dimension of the scale matrix
df : int
Degrees of freedom
C : ndarray
Cholesky factorization of the scale matrix, lower triagular.

%(_doc_random_state)s

As this function does no argument checking, it should not be called directly; use ‘rvs’ instead.

rvs(df, scale, size=1, random_state=None)

Draw random samples from an inverse Wishart distribution.

%(_doc_default_callparams)s size : integer or iterable of integers, optional

Number of samples to draw (default 1).

%(_doc_random_state)s

rvs : ndarray
Random variates of shape (size) + (dim, dim), where `dim is the dimension of the scale matrix.

%(_doc_callparams_note)s

entropy()
class invwishart_frozen(df, scale, seed=None)
__init__(df, scale, seed=None)

Create a frozen inverse Wishart distribution.

df : array_like
Degrees of freedom of the distribution
scale : array_like
Scale matrix of the distribution
seed : None or int or np.random.RandomState instance, optional
This parameter defines the RandomState object to use for drawing random variates. If None (or np.random), the global np.random state is used. If integer, it is used to seed the local RandomState instance Default is None.
logpdf(x)
pdf(x)
mean()
mode()
var()
rvs(size=1, random_state=None)
entropy()
class multinomial_gen(seed=None)

r A multinomial random variable.

pmf(x, n, p)
Probability mass function.
logpmf(x, n, p)
Log of the probability mass function.
rvs(n, p, size=1, random_state=None)
Draw random samples from a multinomial distribution.
entropy(n, p)
Compute the entropy of the multinomial distribution.
cov(n, p)
Compute the covariance matrix of the multinomial distribution.
x : array_like
Quantiles, with the last axis of x denoting the components.

%(_doc_default_callparams)s %(_doc_random_state)s

%(_doc_callparams_note)s

Alternatively, the object may be called (as a function) to fix the n and p parameters, returning a “frozen” multinomial random variable:

The probability mass function for multinomial is

supported on where each is a nonnegative integer and their sum is .

New in version 0.19.0.

>>> from scipy.stats import multinomial
>>> rv = multinomial(8, [0.3, 0.2, 0.5])
>>> rv.pmf([1, 3, 4])
0.042000000000000072

The multinomial distribution for is identical to the corresponding binomial distribution (tiny numerical differences notwithstanding):

>>> from scipy.stats import binom
>>> multinomial.pmf([3, 4], n=7, p=[0.4, 0.6])
0.29030399999999973
>>> binom.pmf(3, 7, 0.4)
0.29030400000000012

The functions pmf, logpmf, entropy, and cov support broadcasting, under the convention that the vector parameters (x and p) are interpreted as if each row along the last axis is a single object. For instance:

>>> multinomial.pmf([[3, 4], [3, 5]], n=[7, 8], p=[.3, .7])
array([0.2268945,  0.25412184])

Here, x.shape == (2, 2), n.shape == (2,), and p.shape == (2,), but following the rules mentioned above they behave as if the rows [3, 4] and [3, 5] in x and [.3, .7] in p were a single object, and as if we had x.shape = (2,), n.shape = (2,), and p.shape = (). To obtain the individual elements without broadcasting, we would do this:

>>> multinomial.pmf([3, 4], n=7, p=[.3, .7])
0.2268945
>>> multinomial.pmf([3, 5], 8, p=[.3, .7])
0.25412184

This broadcasting also works for cov, where the output objects are square matrices of size p.shape[-1]. For example:

>>> multinomial.cov([4, 5], [[.3, .7], [.4, .6]])
array([[[ 0.84, -0.84],
        [-0.84,  0.84]],
       [[ 1.2 , -1.2 ],
        [-1.2 ,  1.2 ]]])

In this example, n.shape == (2,) and p.shape == (2, 2), and following the rules above, these broadcast as if p.shape == (2,). Thus the result should also be of shape (2,), but since each output is a matrix, the result in fact has shape (2, 2, 2), where result[0] is equal to multinomial.cov(n=4, p=[.3, .7]) and result[1] is equal to multinomial.cov(n=5, p=[.4, .6]).

scipy.stats.binom : The binomial distribution. numpy.random.multinomial : Sampling from the multinomial distribution.

__init__(seed=None)
__call__(n, p, seed=None)

Create a frozen multinomial distribution.

See multinomial_frozen for more information.

_process_parameters(n, p)

Return: n_, p_, npcond.

n_ and p_ are arrays of the correct shape; npcond is a boolean array flagging values out of the domain.

_process_quantiles(x, n, p)

Return: x_, xcond.

x_ is an int array; xcond is a boolean array flagging values out of the domain.

_checkresult(result, cond, bad_value)
_logpmf(x, n, p)
logpmf(x, n, p)

Log of the Multinomial probability mass function.

x : array_like
Quantiles, with the last axis of x denoting the components. Each quantile must be a symmetric positive definite matrix.

%(_doc_default_callparams)s

logpmf : ndarray or scalar
Log of the probability mass function evaluated at x

%(_doc_callparams_note)s

pmf(x, n, p)

Multinomial probability mass function.

x : array_like
Quantiles, with the last axis of x denoting the components. Each quantile must be a symmetric positive definite matrix.

%(_doc_default_callparams)s

pmf : ndarray or scalar
Probability density function evaluated at x

%(_doc_callparams_note)s

mean(n, p)

Mean of the Multinomial distribution

%(_doc_default_callparams)s

mean : float
The mean of the distribution
cov(n, p)

Covariance matrix of the multinomial distribution.

%(_doc_default_callparams)s

cov : ndarray
The covariance matrix of the distribution
entropy(n, p)

r Compute the entropy of the multinomial distribution.

The entropy is computed using this expression:

%(_doc_default_callparams)s

h : scalar
Entropy of the Multinomial distribution

%(_doc_callparams_note)s

rvs(n, p, size=None, random_state=None)

Draw random samples from a Multinomial distribution.

%(_doc_default_callparams)s size : integer or iterable of integers, optional

Number of samples to draw (default 1).

%(_doc_random_state)s

rvs : ndarray or scalar
Random variates of shape (size, len(p))

%(_doc_callparams_note)s

class multinomial_frozen(n, p, seed=None)

r Create a frozen Multinomial distribution.

n : int
number of trials
p: array_like
probability of a trial falling into each category; should sum to 1
seed : None or int or np.random.RandomState instance, optional
This parameter defines the RandomState object to use for drawing random variates. If None (or np.random), the global np.random state is used. If integer, it is used to seed the local RandomState instance Default is None.
__init__(n, p, seed=None)
logpmf(x)
pmf(x)
mean()
cov()
entropy()
rvs(size=1, random_state=None)
class special_ortho_group_gen(seed=None)

r A matrix-valued SO(N) random variable.

Return a random rotation matrix, drawn from the Haar distribution (the only uniform distribution on SO(n)).

The dim keyword specifies the dimension N.

rvs(dim=None, size=1, random_state=None)
Draw random samples from SO(N).
dim : scalar
Dimension of matrices

This class is wrapping the random_rot code from the MDP Toolkit, https://github.com/mdp-toolkit/mdp-toolkit

Return a random rotation matrix, drawn from the Haar distribution (the only uniform distribution on SO(n)). The algorithm is described in the paper Stewart, G.W., “The efficient generation of random orthogonal matrices with an application to condition estimators”, SIAM Journal on Numerical Analysis, 17(3), pp. 403-409, 1980. For more information see http://en.wikipedia.org/wiki/Orthogonal_matrix#Randomization

See also the similar ortho_group.

>>> from scipy.stats import special_ortho_group
>>> x = special_ortho_group.rvs(3)
>>> np.dot(x, x.T)
array([[  1.00000000e+00,   1.13231364e-17,  -2.86852790e-16],
       [  1.13231364e-17,   1.00000000e+00,  -1.46845020e-16],
       [ -2.86852790e-16,  -1.46845020e-16,   1.00000000e+00]])
>>> import scipy.linalg
>>> scipy.linalg.det(x)
1.0

This generates one random matrix from SO(3). It is orthogonal and has a determinant of 1.

__init__(seed=None)
__call__(dim=None, seed=None)

Create a frozen SO(N) distribution.

See special_ortho_group_frozen for more information.

_process_parameters(dim)

Dimension N must be specified; it cannot be inferred.

rvs(dim, size=1, random_state=None)

Draw random samples from SO(N).

dim : integer
Dimension of rotation space (N).
size : integer, optional
Number of samples to draw (default 1).
rvs : ndarray or scalar
Random size N-dimensional matrices, dimension (size, dim, dim)
class special_ortho_group_frozen(dim=None, seed=None)
__init__(dim=None, seed=None)

Create a frozen SO(N) distribution.

dim : scalar
Dimension of matrices
seed : None or int or np.random.RandomState instance, optional
This parameter defines the RandomState object to use for drawing random variates. If None (or np.random), the global np.random state is used. If integer, it is used to seed the local RandomState instance Default is None.
>>> from scipy.stats import special_ortho_group
>>> g = special_ortho_group(5)
>>> x = g.rvs()
rvs(size=1, random_state=None)
class ortho_group_gen(seed=None)

r A matrix-valued O(N) random variable.

Return a random orthogonal matrix, drawn from the O(N) Haar distribution (the only uniform distribution on O(N)).

The dim keyword specifies the dimension N.

rvs(dim=None, size=1, random_state=None)
Draw random samples from O(N).
dim : scalar
Dimension of matrices

This class is closely related to special_ortho_group.

Some care is taken to avoid numerical error, as per the paper by Mezzadri.

[1]F. Mezzadri, “How to generate random matrices from the classical compact groups”, :arXiv:`math-ph/0609050v2`.
>>> from scipy.stats import ortho_group
>>> x = ortho_group.rvs(3)
>>> np.dot(x, x.T)
array([[  1.00000000e+00,   1.13231364e-17,  -2.86852790e-16],
       [  1.13231364e-17,   1.00000000e+00,  -1.46845020e-16],
       [ -2.86852790e-16,  -1.46845020e-16,   1.00000000e+00]])
>>> import scipy.linalg
>>> np.fabs(scipy.linalg.det(x))
1.0

This generates one random matrix from O(3). It is orthogonal and has a determinant of +1 or -1.

__init__(seed=None)
_process_parameters(dim)

Dimension N must be specified; it cannot be inferred.

rvs(dim, size=1, random_state=None)

Draw random samples from O(N).

dim : integer
Dimension of rotation space (N).
size : integer, optional
Number of samples to draw (default 1).
rvs : ndarray or scalar
Random size N-dimensional matrices, dimension (size, dim, dim)
class random_correlation_gen(seed=None)

r A random correlation matrix.

Return a random correlation matrix, given a vector of eigenvalues.

The eigs keyword specifies the eigenvalues of the correlation matrix, and implies the dimension.

rvs(eigs=None, random_state=None)
Draw random correlation matrices, all with eigenvalues eigs.
eigs : 1d ndarray
Eigenvalues of correlation matrix.

Generates a random correlation matrix following a numerically stable algorithm spelled out by Davies & Higham. This algorithm uses a single O(N) similarity transformation to construct a symmetric positive semi-definite matrix, and applies a series of Givens rotations to scale it to have ones on the diagonal.

[1]Davies, Philip I; Higham, Nicholas J; “Numerically stable generation of correlation matrices and their factors”, BIT 2000, Vol. 40, No. 4, pp. 640 651
>>> from scipy.stats import random_correlation
>>> np.random.seed(514)
>>> x = random_correlation.rvs((.5, .8, 1.2, 1.5))
>>> x
array([[ 1.        , -0.20387311,  0.18366501, -0.04953711],
       [-0.20387311,  1.        , -0.24351129,  0.06703474],
       [ 0.18366501, -0.24351129,  1.        ,  0.38530195],
       [-0.04953711,  0.06703474,  0.38530195,  1.        ]])
>>> import scipy.linalg
>>> e, v = scipy.linalg.eigh(x)
>>> e
array([ 0.5,  0.8,  1.2,  1.5])
__init__(seed=None)
_process_parameters(eigs, tol)
_givens_to_1(aii, ajj, aij)

Computes a 2x2 Givens matrix to put 1’s on the diagonal for the input matrix.

The input matrix is a 2x2 symmetric matrix M = [ aii aij ; aij ajj ].

The output matrix g is a 2x2 anti-symmetric matrix of the form [ c s ; -s c ]; the elements c and s are returned.

Applying the output matrix to the input matrix (as b=g.T M g) results in a matrix with bii=1, provided tr(M) - det(M) >= 1 and floating point issues do not occur. Otherwise, some other valid rotation is returned. When tr(M)==2, also bjj=1.

_to_corr(m)

Given a psd matrix m, rotate to put one’s on the diagonal, turning it into a correlation matrix. This also requires the trace equal the dimensionality. Note: modifies input matrix

rvs(eigs, random_state=None, tol=1e-13, diag_tol=1e-07)

Draw random correlation matrices

eigs : 1d ndarray
Eigenvalues of correlation matrix
tol : float, optional
Tolerance for input parameter checks
diag_tol : float, optional
Tolerance for deviation of the diagonal of the resulting matrix. Default: 1e-7
RuntimeError
Floating point error prevented generating a valid correlation matrix.
rvs : ndarray or scalar
Random size N-dimensional matrices, dimension (size, dim, dim), each having eigenvalues eigs.
class unitary_group_gen(seed=None)

r A matrix-valued U(N) random variable.

Return a random unitary matrix.

The dim keyword specifies the dimension N.

rvs(dim=None, size=1, random_state=None)
Draw random samples from U(N).
dim : scalar
Dimension of matrices

This class is similar to ortho_group.

[1]F. Mezzadri, “How to generate random matrices from the classical compact groups”, arXiv:math-ph/0609050v2.
>>> from scipy.stats import unitary_group
>>> x = unitary_group.rvs(3)
>>> np.dot(x, x.conj().T)
array([[  1.00000000e+00,   1.13231364e-17,  -2.86852790e-16],
       [  1.13231364e-17,   1.00000000e+00,  -1.46845020e-16],
       [ -2.86852790e-16,  -1.46845020e-16,   1.00000000e+00]])

This generates one random matrix from U(3). The dot product confirms that it is unitary up to machine precision.

__init__(seed=None)
_process_parameters(dim)

Dimension N must be specified; it cannot be inferred.

rvs(dim, size=1, random_state=None)

Draw random samples from U(N).

dim : integer
Dimension of space (N).
size : integer, optional
Number of samples to draw (default 1).
rvs : ndarray or scalar
Random size N-dimensional matrices, dimension (size, dim, dim)