[Serializable]
[DataContract]
[Quality(QualityBand.Mature)]
public class Wishart : IDistribution<PositiveDefiniteMatrix>, IDistribution, ICloneable, HasPoint<PositiveDefiniteMatrix>, CanGetLogProb<PositiveDefiniteMatrix>, SettableTo<Wishart>, SettableToProduct<Wishart>, SettableToProduct<Wishart, Wishart>, Diffable, SettableToUniform, Sampleable<PositiveDefiniteMatrix>, SettableToRatio<Wishart>, SettableToRatio<Wishart, Wishart>, SettableToPower<Wishart>, CanGetMean<PositiveDefiniteMatrix>, CanGetVariance<PositiveDefiniteMatrix>, CanGetMeanAndVariance<PositiveDefiniteMatrix, PositiveDefiniteMatrix>, CanSetMeanAndVariance<PositiveDefiniteMatrix, PositiveDefiniteMatrix>, CanGetLogAverageOf<Wishart>, CanGetLogAverageOfPower<Wishart>, SettableToWeightedSum<Wishart>, CanGetAverageLog<Wishart>, CanGetLogNormalizer, CanGetMode<PositiveDefiniteMatrix>

Remarks

In the matrix case, the distribution is p(X) = |X|^(a-(d+1)/2)*exp(-tr(X*B))*|B|^a/Gamma_d(a). In this code, the a parameter is called the "Shape" and the B parameter is called the "Rate". The distribution is uniform when B=0 and a=(d+1)/2. The mean of the distribution is a/B and the diagonal variance is var(X_ii) = a*C_ii^2 where C=inv(B). The non-diagonal variances are var(X_ij) = a*0.5*(C_ij^2 + C_ii*C_jj) where C=inv(B).

The distribution is represented by a double for a and a PositiveDefiniteMatrix for B.

Constructors

Wishart()

Parameterless constructor needed for serialization

Declaration

protected Wishart()

Wishart(Double, PositiveDefiniteMatrix)

Constructs a multi-dimensional Wishart with given shape and scale matrix

Declaration

public Wishart(double shape, PositiveDefiniteMatrix scale)

Parameters

Type	Name	Description
Double	shape	The shape parameter
PositiveDefiniteMatrix	scale	The scale matrix

Wishart(Double, Double)

Creates a one-dimensional Wishart with given shape and scale

Declaration

public Wishart(double shape, double scale)

Parameters

Type	Name	Description
Double	shape	The shape parameter
Double	scale	The one-dimesional scale

Wishart(Int32)

Constructs a uniform Wishart distribution of the given dimension

Declaration

public Wishart(int dimension)

Parameters

Type	Name	Description
Int32	dimension	The dimension

Wishart(Int32, Double, Double)

Constructs a multi-dimensional Wishart with given shape and with a scale matrix which is set to a scaled identity matrix

Declaration

public Wishart(int dimension, double shape, double scale)

Parameters

Type	Name	Description
Int32	dimension	The dimension
Double	shape	The shape parameter
Double	scale	Used to scale the identity matrix

Properties

Dimension

Dimension of this distribution

Declaration

[IgnoreDataMember]
public int Dimension { get; }

Property Value

Type	Description
Int32

IsPointMass

Asks whether the instance is a point mass

Declaration

[IgnoreDataMember]
public bool IsPointMass { get; }

Property Value

Type	Description
Boolean

Point

Sets/gets this instance as a point-mass

Declaration

[IgnoreDataMember]
public PositiveDefiniteMatrix Point { get; set; }

Property Value

Type	Description
PositiveDefiniteMatrix

Rate

Sets/gets the rate matrix

Declaration

public PositiveDefiniteMatrix Rate { get; set; }

Property Value

Type	Description
PositiveDefiniteMatrix

Shape

Sets/gets the shape value

Declaration

public double Shape { get; set; }

Property Value

Type	Description
Double

Methods

Clone()

Clones this Wishart.

Declaration

public object Clone()

Returns

Type	Description
Object	An object which is a clone of the current instance. This must be cast if you want to assign the result to a Wishart type

Equals(Object)

Override of the Equals method

Declaration

public override bool Equals(object thatd)

Parameters

Type	Name	Description
Object	thatd	The instance to compare to

Returns

Type	Description
Boolean	True if the two distributions are the same in value, false otherwise

Overrides

Object.Equals(Object)

FromMeanAndMeanLogDeterminant(PositiveDefiniteMatrix, Double, Wishart)

Constructs a Wishart distribution with the given mean and mean log determinant.

Declaration

public static Wishart FromMeanAndMeanLogDeterminant(PositiveDefiniteMatrix mean, double meanLogDet, Wishart result = null)

Parameters

Type	Name	Description
PositiveDefiniteMatrix	mean	Desired expected value.
Double	meanLogDet	Desired expected log determinant.
Wishart	result

Returns

Type	Description
Wishart	A new Wishart distribution.

Remarks

This function is equivalent to maximum-likelihood estimation of a Wishart distribution from data given by sufficient statistics. This function is significantly slower than the other constructors since it involves nonlinear optimization. The algorithm is a generalized Newton iteration, described in "Estimating a Gamma distribution" by T. Minka, 2002.

FromShapeAndRate(Double, PositiveDefiniteMatrix)

Creates a multi-dimensional Wishart with given shape and rate matrix

Declaration

[Construction(new string[]{"Shape", "Rate"})]
public static Wishart FromShapeAndRate(double shape, PositiveDefiniteMatrix rate)

Parameters

Type	Name	Description
Double	shape	The shape parameter
PositiveDefiniteMatrix	rate	The rate matrix

Returns

Type	Description
Wishart	A new Wishart distribution

FromShapeAndRate(Int32, Double, Double)

Creates a multi-dimensional Wishart with given shape and with a rate matrix which is set to a scaled identity matrix

Declaration

public static Wishart FromShapeAndRate(int dimension, double shape, double rate)

Parameters

Type	Name	Description
Int32	dimension	The dimension
Double	shape	The shape parameter
Double	rate	Used to scale the identity matrix

Returns

Type	Description
Wishart	A new Wishart distribution

FromShapeAndScale(Double, PositiveDefiniteMatrix)

Creates a new multi-dimensional Wishart with given shape and scale matrix

Declaration

public static Wishart FromShapeAndScale(double shape, PositiveDefiniteMatrix scale)

Parameters

Type	Name	Description
Double	shape	The shape parameter
PositiveDefiniteMatrix	scale	The scale matrix

Returns

Type	Description
Wishart	A new Wishart distribution

FromShapeAndScale(Int32, Double, Double)

Creates a multi-dimensional Wishart with given shape and with a scale matrix which is set to a scaled identity matrix

Declaration

public static Wishart FromShapeAndScale(int dimension, double shape, double scale)

Parameters

Type	Name	Description
Int32	dimension	The dimension
Double	shape	The shape parameter
Double	scale	Used to scale the identity matrix

Returns

Type	Description
Wishart	A new Wishart distribution

GetAverageLog(Wishart)

The expected logarithm of that distribution under this distribution.

Declaration

public double GetAverageLog(Wishart that)

Parameters

Type	Name	Description
Wishart	that	The distribution to take the logarithm of.

Returns

Type	Description
Double	`sum_x this.Evaluate(x)*Math.Log(that.Evaluate(x))`

Remarks

This is also known as the cross entropy.

GetHashCode()

Override of GetHashCode method

Declaration

public override int GetHashCode()

Returns

Type	Description
Int32	The hash code for this instance

Overrides

Object.GetHashCode()

GetLogAverageOf(Wishart)

Gets the log-integral of the product of this Wishart with another Wishart

Declaration

public double GetLogAverageOf(Wishart that)

Parameters

Type	Name	Description
Wishart	that	The other Wishart

Returns

Type	Description
Double	The log inner product

GetLogAverageOfPower(Wishart, Double)

Get the integral of this distribution times another distribution raised to a power.

Declaration

public double GetLogAverageOfPower(Wishart that, double power)

Parameters

Type	Name	Description
Wishart	that
Double	power

Returns

Type	Description
Double

GetLogNormalizer()

Gets the normalizer for the density function of this Wishart distribution

Declaration

public double GetLogNormalizer()

Returns

Type	Description
Double

GetLogNormalizer(Double, PositiveDefiniteMatrix)

Gets the normalizer for a Wishart density function specified by shape and rate matrix

Declaration

public static double GetLogNormalizer(double shape, PositiveDefiniteMatrix rate)

Parameters

Type	Name	Description
Double	shape	Shape parameter
PositiveDefiniteMatrix	rate	rate matrix

Returns

Type	Description
Double

GetLogProb(PositiveDefiniteMatrix)

Evaluates the logarithm of this Wishart density function at a given point

Declaration

public double GetLogProb(PositiveDefiniteMatrix X)

Parameters

Type	Name	Description
PositiveDefiniteMatrix	X	Where to evaluate the density

Returns

Type	Description
Double	The log density

GetLogProb(PositiveDefiniteMatrix, Double, PositiveDefiniteMatrix)

Evaluates the logarithm of a Wishart density function at a given point

Declaration

public static double GetLogProb(PositiveDefiniteMatrix x, double shape, PositiveDefiniteMatrix rate)

Parameters

Type	Name	Description
PositiveDefiniteMatrix	x	Where to evaluate the density
Double	shape	Shape parameter
PositiveDefiniteMatrix	rate	Rate matrix

Returns

Type	Description
Double	The log density

Remarks

The distribution is p(X) = |X|^(a-(d+1)/2)exp(-tr(XB))*|B|^a/Gamma_d(a). When a <= (d-1)/2 the Gamma_d(a) term is dropped. When B <= 0 the |B|^a term is dropped. Thus if shape = (d+1)/2 and rate = 0 the density is 1.

GetMean()

Gets the mean of the distribution.

Declaration

public PositiveDefiniteMatrix GetMean()

Returns

Type	Description
PositiveDefiniteMatrix	A new PositiveDefiniteMatrix.

GetMean(PositiveDefiniteMatrix)

Gets the mean of the distribution.

Declaration

public PositiveDefiniteMatrix GetMean(PositiveDefiniteMatrix mean)

Parameters

Type	Name	Description
PositiveDefiniteMatrix	mean	Where to put the mean matrix

Returns

Type	Description
PositiveDefiniteMatrix	The mean matrix

GetMeanAndVariance(PositiveDefiniteMatrix, PositiveDefiniteMatrix)

Gets the mean and variance matrices.

Declaration

public void GetMeanAndVariance(PositiveDefiniteMatrix mean, PositiveDefiniteMatrix variance)

Parameters

Type	Name	Description
PositiveDefiniteMatrix	mean	Where to put the mean - assumed to be of the correct size
PositiveDefiniteMatrix	variance	Where to put the variance - assumed to be of the correct size

GetMeanLogDeterminant()

Gets the mean log determinant

Declaration

public double GetMeanLogDeterminant()

Returns

Type	Description
Double	The mean log determinant

GetMode()

Declaration

public PositiveDefiniteMatrix GetMode()

Returns

Type	Description
PositiveDefiniteMatrix

GetMode(PositiveDefiniteMatrix)

Declaration

public PositiveDefiniteMatrix GetMode(PositiveDefiniteMatrix result)

Parameters

Type	Name	Description
PositiveDefiniteMatrix	result

Returns

Type	Description
PositiveDefiniteMatrix

GetScale()

Gets the scale matrix

Declaration

public PositiveDefiniteMatrix GetScale()

Returns

Type	Description
PositiveDefiniteMatrix	A new PositiveDefiniteMatrix.

GetVariance()

Gets the variance of the distribution

Declaration

public PositiveDefiniteMatrix GetVariance()

Returns

Type	Description
PositiveDefiniteMatrix	The variance matrix

GetVariance(PositiveDefiniteMatrix)

Gets the variance of the distribution

Declaration

public PositiveDefiniteMatrix GetVariance(PositiveDefiniteMatrix variance)

Parameters

Type	Name	Description
PositiveDefiniteMatrix	variance	Where to put the variance

Returns

Type	Description
PositiveDefiniteMatrix	The variance matrix

IsProper()

Asks whether this instance is proper

Declaration

public bool IsProper()

Returns

Type	Description
Boolean	True if proper, false otherwise

IsProper(Double, PositiveDefiniteMatrix)

Asks whether a Wishart distribution of the specified shape and rate is proper

Declaration

public static bool IsProper(double shape, PositiveDefiniteMatrix rate)

Parameters

Type	Name	Description
Double	shape	Shape parameter
PositiveDefiniteMatrix	rate	Rate matrix

Returns

Type	Description
Boolean	True if proper, false otherwise

IsUniform()

Asks whether this instance is uniform

Declaration

public bool IsUniform()

Returns

Type	Description
Boolean

MaxDiff(Object)

The maximum difference between the parameters of this Wishart and that Wishart

Declaration

public double MaxDiff(object thatd)

Parameters

Type	Name	Description
Object	thatd	That Wishart

Returns

Type	Description
Double	The maximum difference

PointMass(PositiveDefiniteMatrix)

Creates a Wishart point mass at the specified location

Declaration

[Construction(new string[]{"Point"}, UseWhen = "IsPointMass")]
public static Wishart PointMass(PositiveDefiniteMatrix mean)

Parameters

Type	Name	Description
PositiveDefiniteMatrix	mean	The location of the point-mass

Returns

Type	Description
Wishart	A new point mass Wishart distribution

PointMass(Double)

Creates a Wishart point mass at the specified location

Declaration

public static Wishart PointMass(double mean)

Parameters

Type	Name	Description
Double	mean	The location of the point-mass is a vector where every element equals this value

Returns

Type	Description
Wishart	A new point mass Wishart distribution

Sample()

Samples this Wishart distribution. Workspaces and sample matrix are allocated behind the scenes

Declaration

public PositiveDefiniteMatrix Sample()

Returns

Type	Description
PositiveDefiniteMatrix	The sample

Sample(PositiveDefiniteMatrix)

Samples this Wishart distribution. Workspaces are allocated behind the scenes

Declaration

public PositiveDefiniteMatrix Sample(PositiveDefiniteMatrix result)

Parameters

Type	Name	Description
PositiveDefiniteMatrix	result	Where to put the sample

Returns

Type	Description
PositiveDefiniteMatrix	The sample

Sample(PositiveDefiniteMatrix, LowerTriangularMatrix, LowerTriangularMatrix, Matrix)

Samples this Wishart distribution

Declaration

public PositiveDefiniteMatrix Sample(PositiveDefiniteMatrix result, LowerTriangularMatrix cholB, LowerTriangularMatrix cholX, Matrix cholXt)

Parameters

Type	Name	Description
PositiveDefiniteMatrix	result	Where to put the sample
LowerTriangularMatrix	cholB	A workspace matrix of the same dimension as the distribution
LowerTriangularMatrix	cholX	A workspace matrix of the same dimension as the distribution
Matrix	cholXt	A workspace matrix of the same dimension as the distribution

Returns

Type	Description
PositiveDefiniteMatrix	The sample

Sample(Double, PositiveDefiniteMatrix, PositiveDefiniteMatrix)

Samples a Wishart distribution of specified shape and rate. Workspaces are allocated behind the scenes

Declaration

public static PositiveDefiniteMatrix Sample(double shape, PositiveDefiniteMatrix scale, PositiveDefiniteMatrix result)

Parameters

Type	Name	Description
Double	shape	The shape parameter
PositiveDefiniteMatrix	scale	The scale matrix
PositiveDefiniteMatrix	result	Where to put the sample

Returns

Type	Description
PositiveDefiniteMatrix	The sample

SampleFromShapeAndRate(Double, PositiveDefiniteMatrix)

Samples a Wishart distribution of specified shape and rate. Workspaces are allocated behind the scenes

Declaration

[ParameterNames(new string[]{"sample", "shape", "rate"})]
public static PositiveDefiniteMatrix SampleFromShapeAndRate(double shape, PositiveDefiniteMatrix rate)

Parameters

Type	Name	Description
Double	shape	The shape parameter
PositiveDefiniteMatrix	rate	The rate matrix

Returns

Type	Description
PositiveDefiniteMatrix	The sample

SampleFromShapeAndRate(Double, PositiveDefiniteMatrix, PositiveDefiniteMatrix)

Samples a Wishart distribution of specified shape and rate. Workspaces are allocated behind the scenes

Declaration

public static PositiveDefiniteMatrix SampleFromShapeAndRate(double shape, PositiveDefiniteMatrix rate, PositiveDefiniteMatrix result)

Parameters

Type	Name	Description
Double	shape	The shape parameter
PositiveDefiniteMatrix	rate	The rate matrix
PositiveDefiniteMatrix	result	Receives the sample

Returns

Type	Description
PositiveDefiniteMatrix	`result`

SampleFromShapeAndScale(Double, PositiveDefiniteMatrix)

Samples a Wishart distribution of specified shape and scale. Workspaces are allocated behind the scenes

Declaration

[ParameterNames(new string[]{"sample", "shape", "scale"})]
public static PositiveDefiniteMatrix SampleFromShapeAndScale(double shape, PositiveDefiniteMatrix scale)

Parameters

Type	Name	Description
Double	shape	The shape parameter
PositiveDefiniteMatrix	scale	The scale matrix

Returns

Type	Description
PositiveDefiniteMatrix	The sample

SetDerivatives(LowerTriangularMatrix, PositiveDefiniteMatrix, PositiveDefiniteMatrix, Double, Boolean, Double)

Modify the parameters so that the pdf has the given derivatives at a point.

Declaration

public void SetDerivatives(LowerTriangularMatrix xChol, PositiveDefiniteMatrix invX, PositiveDefiniteMatrix dlogp, double xxddlogp, bool forceProper, double shapeOffset = 0)

Parameters

Type	Name	Description
LowerTriangularMatrix	xChol	Cholesky factor of the point X
PositiveDefiniteMatrix	invX	Inverse of X. Can be the same object as `this.Rate`
PositiveDefiniteMatrix	dlogp	Desired derivative. Can be the same object as `this.Rate`
Double	xxddlogp	tr(x tr(x dlogp')/dx)
Boolean	forceProper	If true and both derivatives cannot be matched, match only the first.
Double	shapeOffset

SetMeanAndVariance(PositiveDefiniteMatrix, PositiveDefiniteMatrix)

Sets the parameters to produce a given mean and variance.

Declaration

public void SetMeanAndVariance(PositiveDefiniteMatrix mean, PositiveDefiniteMatrix variance)

Parameters

Type	Name	Description
PositiveDefiniteMatrix	mean	Mean
PositiveDefiniteMatrix	variance	Variance

Remarks

The mean is always matched, but the variance may not match exactly, since the distribution has only one scalar parameter for variance.

SetShapeAndRate(Double, PositiveDefiniteMatrix)

Sets the shape parameter and the rate matrix parameter for this instance

Declaration

public void SetShapeAndRate(double shape, PositiveDefiniteMatrix rate)

Parameters

Type	Name	Description
Double	shape	The shape parameter
PositiveDefiniteMatrix	rate	The rate matrix

SetShapeAndScale(Double, PositiveDefiniteMatrix)

Sets the shape parameter and the scale matrix parameter for this instance

Declaration

public void SetShapeAndScale(double shape, PositiveDefiniteMatrix scale)

Parameters

Type	Name	Description
Double	shape	The shape parameter
PositiveDefiniteMatrix	scale	The scale matrix

SetTo(Wishart)

Sets this Wishart instance to have the parameter values of another Wishart instance

Declaration

public void SetTo(Wishart that)

Parameters

Type	Name	Description
Wishart	that	The other Wishart

SetToPointMass()

Sets this instance to a point mass. The location of the point mass is the existing rate matrix

Declaration

protected void SetToPointMass()

SetToPower(Wishart, Double)

Sets the parameters to represent the power of a source Wishart to some exponent.

Declaration

public void SetToPower(Wishart dist, double exponent)

Parameters

Type	Name	Description
Wishart	dist	The source Wishart
Double	exponent	The exponent

SetToProduct(Wishart, Wishart)

Sets the parameters to represent the product of two Wisharts.

Declaration

public void SetToProduct(Wishart g1, Wishart g2)

Parameters

Type	Name	Description
Wishart	g1	The first Wishart. May refer to `this`.
Wishart	g2	The second Wishart. May refer to `this`.

Remarks

The result may not be proper. No error is thrown in this case.

SetToRatio(Wishart, Wishart, Boolean)

Sets the parameters to represent the ratio of two Wisharts.

Declaration

public void SetToRatio(Wishart numerator, Wishart denominator, bool forceProper = false)

Parameters

Type	Name	Description
Wishart	numerator	The numerator Wishart. Can be `this`
Wishart	denominator	The denominator Wishart
Boolean	forceProper	If true, the result shape >= (dimension+1)/2 and rate is non-negative definite

SetToSum(Double, Wishart, Double, Wishart)

Weighted mixture distribution for two Wisharts

Declaration

public void SetToSum(double weight1, Wishart dist1, double weight2, Wishart dist2)

Parameters

Type	Name	Description
Double	weight1	First weight
Wishart	dist1	First Wishart
Double	weight2	Second weight
Wishart	dist2	Second Wishart

SetToUniform()

Sets this instance to have uniform distribution

Declaration

public void SetToUniform()

ToString()

ToString override

Declaration

public override string ToString()

Returns

Type	Description
String	String representation of the instance

Overrides

Object.ToString()

Uniform(Int32)

Constructs a uniform Wishart distribution of the given dimension

Declaration

[Construction(new string[]{"Dimension"}, UseWhen = "IsUniform")]
public static Wishart Uniform(int dimension)

Parameters

Type	Name	Description
Int32	dimension	The dimension

Returns

Type	Description
Wishart

WeightedSum<T>(T, Int32, Double, T, Double, T)

Creates a weighted mixture distribution for distributions whose mean and variance are both of type PositiveDefiniteMatrix. The distribution type must implement CanGetMeanAndVariance<MeanType, VarType> and CanSetMeanAndVariance<MeanType, VarType>

Declaration

public static T WeightedSum<T>(T result, int dimension, double weight1, T dist1, double weight2, T dist2)
    where T : CanGetMeanAndVariance<PositiveDefiniteMatrix, PositiveDefiniteMatrix>, CanSetMeanAndVariance<PositiveDefiniteMatrix, PositiveDefiniteMatrix>, SettableToUniform, SettableTo<T>

Parameters

Type	Name	Description
T	result	Resulting distribution
Int32	dimension	The dimension of the domain
Double	weight1	The first weight
T	dist1	The first distribution
Double	weight2	The second weight
T	dist2	The second distribution

Returns

Type	Description
T

Type Parameters

Name	Description
T	Distribution type for the mixture

Operators

Division(Wishart, Wishart)

Creates a new Wishart which is the ratio of two other Wishart

Declaration

public static Wishart operator /(Wishart numerator, Wishart denominator)

Parameters

Type	Name	Description
Wishart	numerator	numerator Wishart
Wishart	denominator	denominator Wishart

Returns

Type	Description
Wishart	Result

ExclusiveOr(Wishart, Double)

Raises a distribution to a power.

Declaration

public static Wishart operator ^(Wishart dist, double exponent)

Parameters

Type	Name	Description
Wishart	dist	The distribution.
Double	exponent	The power to raise to.

Returns

Type	Description
Wishart	`dist` raised to power `exponent`.

Multiply(Wishart, Wishart)

Creates a new Wishart which the product of two other Wisharts

Declaration

public static Wishart operator *(Wishart a, Wishart b)

Parameters

Type	Name	Description
Wishart	a	First Wishart
Wishart	b	Second Wishart

Returns

Type	Description
Wishart	Result

Implements

IDistribution<T>

IDistribution

System.ICloneable

HasPoint<T>

CanGetLogProb<T>

SettableTo<T>

SettableToProduct<T>

SettableToProduct<T, U>

Diffable

SettableToUniform

Sampleable<T>

SettableToRatio<T>

SettableToRatio<T, U>

SettableToPower<T>

CanGetMean<MeanType>

CanGetVariance<VarType>

CanGetMeanAndVariance<MeanType, VarType>

CanSetMeanAndVariance<MeanType, VarType>

CanGetLogAverageOf<T>

CanGetLogAverageOfPower<T>

SettableToWeightedSum<T>

CanGetAverageLog<T>

CanGetLogNormalizer

CanGetMode<ModeType>