Class Distribution

Static class which implements useful functions on distributions.

Inheritance

Object

Distribution

Inherited Members

Object.Equals(Object)

Object.Equals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Object.ReferenceEquals(Object, Object)

Object.ToString()

Namespace: Microsoft.ML.Probabilistic.Distributions

Assembly: Microsoft.ML.Probabilistic.dll

Syntax

public static class Distribution

Methods

ChangeType<TReturn>(Object)

Convert a distribution from one type to another

Declaration

public static TReturn ChangeType<TReturn>(object distribution)

Parameters

Type	Name	Description
Object	distribution	The object to convert

Returns

Type	Description
TReturn	The converted distribution

Type Parameters

Name	Description
TReturn	The desired distribution type

CreatePartialUniform<TDistribution>(TDistribution)

Creates a distribution which is uniform over the support of a specified distribution.

Declaration

public static TDistribution CreatePartialUniform<TDistribution>(TDistribution distribution)
    where TDistribution : SettableToPartialUniform<TDistribution>, new()

Parameters

Type	Name	Description
TDistribution	distribution	The distribution, which support will be used to create the result distribution.

Returns

Type	Description
TDistribution	The created distribution.

Type Parameters

Name	Description
TDistribution	The distribution type.

CreateUniform<TDistribution>()

Creates a uniform distribution of a specified type.

Declaration

public static TDistribution CreateUniform<TDistribution>()
    where TDistribution : SettableToUniform, new()

Returns

Type	Description
TDistribution	The created uniform distribution.

Type Parameters

Name	Description
TDistribution	The distribution type.

FromArray(Object)

Convert an array of element distributions to a distribution over an array variable.

Declaration

public static object FromArray(object arrayOfDistributions)

Parameters

Type	Name	Description
Object	arrayOfDistributions	Array of distributions

Returns

Type	Description
Object	Distribution over an array variable

GetAverageLog<T, TValue>(T[], TValue[])

The expected logarithm of that distribution under this distribution.

Declaration

public static double GetAverageLog<T, TValue>(T[] thisDist, TValue[] that)
    where T : CanGetAverageLog<TValue>

Parameters

Type	Name	Description
T[]	thisDist	This distribution
TValue[]	that	The distribution to take the logarithm of.

Returns

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

Type Parameters

Name	Description
T	Type of this distribution
TValue	Type of the distribution to take the logarithm of

Remarks

This is also known as the cross entropy. For an array, this specializes to: sum_i sum_x this[i].Evaluate(x)*Math.Log(that[i].Evaluate(x)) = sum_i this[i].GetAverageLog(that[i])

GetAverageLogLazy<T1, T2>(T1[], T2[])

The expected logarithm of that distribution under this distribution.

Declaration

public static double GetAverageLogLazy<T1, T2>(T1[] thisDist, T2[] that)

Parameters

Type	Name	Description
T1[]	thisDist	This distribution array
T2[]	that	The distribution to take the logarithm of.

Returns

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

Type Parameters

Name	Description
T1	Element type of this distribution array
T2	Element type of thatd istribution array

Remarks

This is also known as the cross entropy. For an array, this specializes to: sum_i sum_x this[i].Evaluate(x)*Math.Log(that[i].Evaluate(x)) = sum_i this[i].GetAverageLog(that[i])

GetDomainType(Type)

Gets the domain type of a distribution type, e.g. the domain type of 'Gaussian' is 'double'.

Declaration

public static Type GetDomainType(Type distributionType)

Parameters

Type	Name	Description
Type	distributionType

Returns

Type	Description
Type

GetLogAverageOf<T1, T2>(T1[], T2[])

The log-probability that two distributions would draw the same sample.

Declaration

public static double GetLogAverageOf<T1, T2>(T1[] thisDist, T2[] that)
    where T1 : CanGetLogAverageOf<T2>

Parameters

Type	Name	Description
T1[]	thisDist	This distribution array
T2[]	that	The distribution to take the logarithm of.

Returns

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

Type Parameters

Name	Description
T1	Element type of this distribution array
T2	Element type of that distribution array

Remarks

This can be considered a type of inner product between distributions. Another name might be "LogAverage" to go with "GetAverageLog". For an array, this specializes to: sum_i Math.Log(sum_x this[i].Evaluate(x)*that[i].Evaluate(x)) = sum_i this[i].GetLogAverageOf(that[i])

GetLogAverageOf<T, TDistribution>(TDistribution, TDistribution, out TDistribution)

Computes the log-probability that two distributions would draw the same sample.

Declaration

public static double GetLogAverageOf<T, TDistribution>(TDistribution distribution1, TDistribution distribution2, out TDistribution product)
    where TDistribution : IDistribution<T>, SettableToProduct<TDistribution>, CanGetLogAverageOf<TDistribution>, new()

Parameters

Type	Name	Description
TDistribution	distribution1	The first distribution.
TDistribution	distribution2	The second distribution.
TDistribution	product	The product of the distributions will be returned in this argument. If the product is zero, the value is undefined.

Returns

Type	Description
Double	The log-probability that two distributions would draw the same sample.

Type Parameters

Name	Description
T	The distribution domain.
TDistribution	The type of a distribution.

GetLogAverageOfLazy<T1, T2>(T1[], T2[])

The log-probability that two distributions would draw the same sample.

Declaration

public static double GetLogAverageOfLazy<T1, T2>(T1[] thisDist, T2[] that)

Parameters

Type	Name	Description
T1[]	thisDist	This distribution array
T2[]	that	The distribution to take the logarithm of.

Returns

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

Type Parameters

Name	Description
T1	Element type of this distribution array
T2	Element type of that distribution array

Remarks

This can be considered a type of inner product between distributions. Another name might be "LogAverage" to go with "GetAverageLog". For an array, this specializes to: sum_i Math.Log(sum_x this[i].Evaluate(x)*that[i].Evaluate(x)) = sum_i this[i].GetLogAverageOf(that[i])

GetLogAverageOfPower<T1, T2>(T1[], T2[], Double)

Declaration

public static double GetLogAverageOfPower<T1, T2>(T1[] thisDist, T2[] that, double exponent)
    where T1 : CanGetLogAverageOfPower<T2>

Parameters

Type	Name	Description
T1[]	thisDist
T2[]	that
Double	exponent

Returns

Type	Description
Double

Type Parameters

Name	Description
T1
T2

GetLogAverageOfPowerLazy<T1, T2>(T1[], T2[], Double)

Declaration

public static double GetLogAverageOfPowerLazy<T1, T2>(T1[] thisDist, T2[] that, double exponent)

Parameters

Type	Name	Description
T1[]	thisDist
T2[]	that
Double	exponent

Returns

Type	Description
Double

Type Parameters

Name	Description
T1
T2

GetQualityBand(Type)

Returns the quality band for the distribution type

Declaration

public static QualityBand GetQualityBand(Type type)

Parameters

Type	Name	Description
Type	type	The distribution type

Returns

Type	Description
QualityBand

Remarks

This will throw an exception if there is no distribution associated with this type. Call HasDistributionType(Type) to check.

HasDistributionType(Type)

Determines whether the type, or any element, or any generic type parameter specification, etc is a distribution type

Declaration

public static bool HasDistributionType(Type type)

Parameters

Type	Name	Description
Type	type

Returns

Type	Description
Boolean

IsDistributionType(Type)

Determinines if this type is a distribution type

Declaration

public static bool IsDistributionType(Type type)

Parameters

Type	Name	Description
Type	type

Returns

Type	Description
Boolean

IsSettableTo(Type, Type)

Declaration

public static bool IsSettableTo(Type type, Type source)

Parameters

Type	Name	Description
Type	type
Type	source

Returns

Type	Description
Boolean

LogInnerProduct<T>(IList<T>)

Log-probability that all distributions in the list would produce the same value.

Declaration

public static double LogInnerProduct<T>(IList<T> dists)
    where T : CanGetLogAverageOf<T>, SettableToProduct<T>, ICloneable

Parameters

Type	Name	Description
IList<T>	dists

Returns

Type	Description
Double	sum_x prod_i dists[i]​(x)

Type Parameters

Name	Description
T

MakeDistributionArrayType(Type, Int32)

Makes a distribution array of a specified type and size

Declaration

public static Type MakeDistributionArrayType(Type elementType, int rank)

Parameters

Type	Name	Description
Type	elementType	Distribution type
Int32	rank	Number of dimensions

Returns

Type	Description
Type

MakeDistributionFileArrayType(Type, Int32)

Declaration

public static Type MakeDistributionFileArrayType(Type elementType, int rank)

Parameters

Type	Name	Description
Type	elementType
Int32	rank

Returns

Type	Description
Type

MaxDiff<T, U>(T[], U[])

Max difference between two arrays of distributions

Declaration

public static double MaxDiff<T, U>(T[] a, U[] b)
    where T : Diffable

Parameters

Type	Name	Description
T[]	a	First array of distributions
U[]	b	Second array of distributions

Returns

Type	Description
Double

Type Parameters

Name	Description
T	Domain type for fisrt array of distributions
U	Domain type for second array of distributions

PointMass<T>(T)

Creates a point mass at the specified location.

Declaration

public static object PointMass<T>(T point)

Parameters

Type	Name	Description
T	point	The point at which to place the point mass

Returns

Type	Description
Object	The PointMass object

Type Parameters

Name	Description
T

Product<T, TDistribution>(TDistribution, TDistribution)

Helper method that creates new distribution that is equal to product of 2 given distributions.

Declaration

public static TDistribution Product<T, TDistribution>(TDistribution distribution1, TDistribution distribution2)
    where TDistribution : IDistribution<T>, SettableToProduct<TDistribution>, new()

Parameters

Type	Name	Description
TDistribution	distribution1
TDistribution	distribution2

Returns

Type	Description
TDistribution

Type Parameters

Name	Description
T
TDistribution

SetPoint<TDist, T>(TDist, T)

Set a distribution to a point mass

Declaration

public static TDist SetPoint<TDist, T>(TDist result, T point)
    where TDist : HasPoint<T>

Parameters

Type	Name	Description
TDist	result	Where to put the result (for reference types)
T	point	The location of the point mass

Returns

Type	Description
TDist	A point mass distribution of the specified type and location

Type Parameters

Name	Description
TDist	The distribution type
T	The domain type

SetTo<T, TValue>(T, TValue)

Sets result to value and returns result.

Declaration

public static T SetTo<T, TValue>(T result, TValue value)
    where T : SettableTo<TValue>

Parameters

Type	Name	Description
T	result	The result
TValue	value	The value

Returns

Type	Description
T	result, or a newly allocated object.

Type Parameters

Name	Description
T	Type of the result
TValue	Type of the value

SetTo<T1, T2>(T1[], T2[])

Declaration

public static void SetTo<T1, T2>(T1[] result, T2[] values)
    where T1 : SettableTo<T2>

Parameters

Type	Name	Description
T1[]	result
T2[]	values

Type Parameters

Name	Description
T1
T2

SetTo<T, TValue, TDomain>(T, TValue)

Sets result to value and returns result.

Declaration

public static T SetTo<T, TValue, TDomain>(T result, TValue value)
    where T : class, IDistribution<TDomain>, SettableTo<IDistribution<TDomain>> where TValue : IDistribution<TDomain>

Parameters

Type	Name	Description
T	result	The result
TValue	value	The value

Returns

Type	Description
T	result, or a newly allocated object.

Type Parameters

Name	Description
T	Type of the result
TValue	Type of the value
TDomain	Domain

SetToPower<T1, T2>(T1[], T2[], Double)

Sets each element of the result to a power of the corresponding element in a source distribution array

Declaration

public static void SetToPower<T1, T2>(T1[] result, T2[] a, double exponent)
    where T1 : SettableToPower<T2>

Parameters

Type	Name	Description
T1[]	result	Result distribution array
T2[]	a	The source distribution array
Double	exponent	The exponent

Type Parameters

Name	Description
T1	Element type of the result distribution array
T2	Element type of the source distribution array

SetToPowerLazy<T1, T2>(T1[], T2[], Double)

Sets each element of the result to a power of the corresponding element in a source distribution array

Declaration

public static void SetToPowerLazy<T1, T2>(T1[] result, T2[] a, double exponent)

Parameters

Type	Name	Description
T1[]	result	Result distribution array
T2[]	a	The source distribution array
Double	exponent	The exponent

Type Parameters

Name	Description
T1	Element type of the result distribution array
T2	Element type of the source distribution array

SetToProduct<T1, T2>(T1[], T2[], T2[])

Sets each element of result to the product of the corresponding distributions in two given arrays

Declaration

public static void SetToProduct<T1, T2>(T1[] result, T2[] a, T2[] b)
    where T1 : SettableToProduct<T2>

Parameters

Type	Name	Description
T1[]	result	Result
T2[]	a	The first distribution array
T2[]	b	The second distribution array

Type Parameters

Name	Description
T1	Element type of the result distribution array
T2	Element type of the two distribution arrays

SetToProduct<T1, T2, T3, TDomain>(T1[], T2[], T3[])

Sets each element of the result to the product of the corresponding distributions in two given arrays.

Declaration

public static void SetToProduct<T1, T2, T3, TDomain>(T1[] result, T2[] a, T3[] b)
    where T1 : IDistribution<TDomain>, SettableToProduct<IDistribution<TDomain>, IDistribution<TDomain>> where T2 : IDistribution<TDomain> where T3 : IDistribution<TDomain>

Parameters

Type	Name	Description
T1[]	result	Result distribution array
T2[]	a	The first distribution array
T3[]	b	The second distribution array

Type Parameters

Name	Description
T1	Element type of the result distribution array
T2	Element type of the numerator distribution arrays
T3	Element type of the denominator distribution array
TDomain	Domian type

SetToProductOfAll<T, U>(T, U[])

Sets a distribution to the product of an array of ditributions

Declaration

public static T SetToProductOfAll<T, U>(T result, U[] dists)
    where T : SettableToProduct<U>, SettableTo<U>, U, SettableToUniform

Parameters

Type	Name	Description
T	result	The result distribution
U[]	dists	The array of distributions

Returns

Type	Description
T

Type Parameters

Name	Description
T	Domain type of the result distribution
U	Domain type of the array of distributions

SetToProductOfAll<T, U>(T, IReadOnlyList<U>)

Product of all distributions in an array.

Declaration

public static T SetToProductOfAll<T, U>(T result, IReadOnlyList<U> dists)
    where T : SettableToProduct<U>, SettableTo<U>, U, SettableToUniform

Parameters

Type	Name	Description
T	result
IReadOnlyList<U>	dists

Returns

Type	Description
T	result, unless it is not SettableTo<T> in which case an element of dists may be returned.

Type Parameters

Name	Description
T
U

SetToProductOfAllExcept<T, U>(T, IList<U>, Int32, Int32)

Product of distributions in an array.

Declaration

public static T SetToProductOfAllExcept<T, U>(T result, IList<U> dists, int count, int index)
    where T : SettableToProduct<U>, SettableTo<U>, SettableToUniform, U

Parameters

Type	Name	Description
T	result	A reference in which to place the results.
IList<U>	dists	An array of distributions.
Int32	count	The number of distributions in the array to multiply (starting from index 0).
Int32	index	An array index to omit in the multiplication. If index == count, no index is omitted and all distributions are multiplied.

Returns

Type	Description
T	result, unless it is not SettableTo<T> in which case an element of dists may be returned.

Type Parameters

Name	Description
T
U

SetToProductWithAll<T, U>(T, U[])

Multiplies result by all distributions in an array.

Declaration

public static T SetToProductWithAll<T, U>(T result, U[] dists)
    where T : SettableToProduct<T, U>

Parameters

Type	Name	Description
T	result
U[]	dists

Returns

Type	Description
T	result

Type Parameters

Name	Description
T
U

SetToProductWithAll<T, U>(T, IReadOnlyList<U>)

Multiplies result by all distributions in an array.

Declaration

public static T SetToProductWithAll<T, U>(T result, IReadOnlyList<U> dists)
    where T : SettableToProduct<T, U>

Parameters

Type	Name	Description
T	result
IReadOnlyList<U>	dists

Returns

Type	Description
T	result

Type Parameters

Name	Description
T
U

SetToProductWithAll<T, U, TDomain>(T, IList<U>)

Multiplies result by all distributions in an array.

Declaration

public static T SetToProductWithAll<T, U, TDomain>(T result, IList<U> dists)
    where T : IDistribution<TDomain>, SettableToProduct<IDistribution<TDomain>, IDistribution<TDomain>> where U : IDistribution<TDomain>

Parameters

Type	Name	Description
T	result
IList<U>	dists

Returns

Type	Description
T	result

Type Parameters

Name	Description
T
U
TDomain

SetToProductWithAllExcept<T, U>(T, U[], Int32)

Multiplies result by all distributions in an array, except for one index.

Declaration

public static T SetToProductWithAllExcept<T, U>(T result, U[] dists, int index)
    where T : SettableToProduct<T, U>

Parameters

Type	Name	Description
T	result
U[]	dists
Int32	index

Returns

Type	Description
T	result

Type Parameters

Name	Description
T
U

SetToProductWithAllExcept<T, U>(T, IReadOnlyList<U>, Int32)

Multiplies result by all distributions in an array, except for one index.

Declaration

public static T SetToProductWithAllExcept<T, U>(T result, IReadOnlyList<U> dists, int index)
    where T : SettableToProduct<T, U>

Parameters

Type	Name	Description
T	result
IReadOnlyList<U>	dists
Int32	index

Returns

Type	Description
T	result

Type Parameters

Name	Description
T
U

SetToProductWithAllExcept<T, U, TDomain>(T, IList<U>, Int32)

Multiplies result by all distributions in an array, except for one index.

Declaration

public static T SetToProductWithAllExcept<T, U, TDomain>(T result, IList<U> dists, int index)
    where T : IDistribution<TDomain>, SettableToProduct<IDistribution<TDomain>, IDistribution<TDomain>> where U : IDistribution<TDomain>

Parameters

Type	Name	Description
T	result
IList<U>	dists
Int32	index

Returns

Type	Description
T	result

Type Parameters

Name	Description
T
U
TDomain

SetToRatio<T1, T2>(T1[], T2[], T2[], Boolean)

Sets each element of the result to the ratio of the corresponding distributions in two given arrays.

Declaration

public static void SetToRatio<T1, T2>(T1[] result, T2[] numerator, T2[] denominator, bool forceProper)
    where T1 : SettableToRatio<T2>

Parameters

Type	Name	Description
T1[]	result	Result distribution array
T2[]	numerator	The numerator distribution array
T2[]	denominator	The denominator distribution array
Boolean	forceProper	Argument passed to T1.SetToRatio

Type Parameters

Name	Description
T1	Element type of the result distribution array
T2	Element type of the numerator and denominator distribution arrays

SetToRatio<T1, T2, T3, TDomain>(T1[], T2[], T3[])

Sets each element of the result to the ratio of the corresponding distributions in two given arrays.

Declaration

public static void SetToRatio<T1, T2, T3, TDomain>(T1[] result, T2[] numerator, T3[] denominator)
    where T1 : IDistribution<TDomain>, SettableToRatio<IDistribution<TDomain>, IDistribution<TDomain>> where T2 : IDistribution<TDomain> where T3 : IDistribution<TDomain>

Parameters

Type	Name	Description
T1[]	result	Result distribution array
T2[]	numerator	The numerator distribution array
T3[]	denominator	The denominator distribution array

Type Parameters

Name	Description
T1	Element type of the result distribution array
T2	Element type of the numerator distribution arrays
T3	Element type of the denominator distribution array
TDomain	Domian type

SetToSum<T1, T2>(T1[], Double, T2[], Double, T2[])

Sets each element of result to a weighted sum of the corresponding distributions in two given arrays.

Declaration

public static void SetToSum<T1, T2>(T1[] result, double weight1, T2[] a, double weight2, T2[] b)
    where T1 : SettableToWeightedSum<T2>

Parameters

Type	Name	Description
T1[]	result	Result distribution array
Double	weight1	The first weight
T2[]	a	The first distribution array
Double	weight2	The second weight
T2[]	b	The second distribution array

Type Parameters

Name	Description
T1	Element type of the result distribution array
T2	Element type of the two source distribution arrays

SetToSumLazy<T1, T2>(T1[], Double, T2[], Double, T2[])

Sets each element of result to a weighted sum of the corresponding distributions in two given arrays.

Declaration

public static void SetToSumLazy<T1, T2>(T1[] result, double weight1, T2[] a, double weight2, T2[] b)

Parameters

Type	Name	Description
T1[]	result	Result distribution array
Double	weight1	The first weight
T2[]	a	The first distribution array
Double	weight2	The second weight
T2[]	b	The second distribution array

Type Parameters

Name	Description
T1	Element type of the result distribution array
T2	Element type of the two source distribution arrays

ToArray<ArrayType>(Object)

Convert a distribution over an array variable to an array of element distributions.

Declaration

public static ArrayType ToArray<ArrayType>(object distributionArray)

Parameters

Type	Name	Description
Object	distributionArray	A distribution over an array domain, such as IDistribution<bool[]> or IDistribution<double[,][]>.

Returns

Type	Description
ArrayType	An array of element distributions.

Type Parameters

Name	Description
ArrayType	A .NET array type, such as Bernoulli[] or Gaussian[,][]. The array structure should match the domain of the distribution.

Remarks

ArrayType should match the array structure of the domain. For example, if the input is IDistribution<bool[,]> then ArrayType should be Bernoulli[,].