[Serializable]
[DataContract]
[Quality(QualityBand.Mature)]
public struct Beta : IDistribution<double>, IDistribution, ICloneable, HasPoint<double>, CanGetLogProb<double>, SettableTo<Beta>, SettableToProduct<Beta>, SettableToProduct<Beta, Beta>, Diffable, SettableToUniform, SettableToRatio<Beta>, SettableToRatio<Beta, Beta>, SettableToPower<Beta>, SettableToWeightedSum<Beta>, CanGetLogAverageOf<Beta>, CanGetLogAverageOfPower<Beta>, CanGetAverageLog<Beta>, CanGetLogNormalizer, Sampleable<double>, CanGetMean<double>, CanGetVariance<double>, CanGetMeanAndVarianceOut<double, double>, CanSetMeanAndVariance<double, double>, CanGetMode<double>, CanGetProbLessThan<double>

Remarks

The Beta is often used as a distribution on probability values. The formula for the distribution is p(x) = (Gamma(trueCount+falseCount)/Gamma(trueCount)/Gamma(falseCount)) x^{trueCount-1} (1-x)^(falseCount-1) subject to the constraint 0 <= x <= 1.

If trueCount = falseCount = 1, the distribution is uniform. If falseCount = infinity, the distribution is redefined to be a point mass on trueCount. When trueCount <= 0 or falseCount <= 0, the distribution is improper. In this case, the density is redefined to not include the Gamma terms, i.e. there is no normalizer.

Constructors

Beta(Beta)

Copy constructor.

Declaration

public Beta(Beta that)

Parameters

Type	Name	Description
Beta	that

Beta(Double, Double)

Creates a Beta distribution with the given parameters.

Declaration

[Construction(new string[]{"TrueCount", "FalseCount"})]
public Beta(double trueCount, double falseCount)

Parameters

Type	Name	Description
Double	trueCount
Double	falseCount

Remarks

The formula for the distribution is p(x) = (Gamma(trueCount+falseCount)/Gamma(trueCount)/Gamma(falseCount)) x^{trueCount-1} (1-x)^(falseCount-1).

Fields

AllowImproperSum

Property to allow an improper sum

Declaration

public static bool AllowImproperSum

Field Value

Type	Description
Boolean

FalseCount

False count

Declaration

[DataMember]
public double FalseCount

Field Value

Type	Description
Double

TrueCount

True count

Declaration

[DataMember]
public double TrueCount

Field Value

Type	Description
Double

Properties

IsPointMass

Whether the instance is a point mass beta distribution

Declaration

[IgnoreDataMember]
public readonly bool IsPointMass { get; }

Property Value

Type	Description
Boolean

Point

Gets/sets the instance as a point mass

Declaration

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

Property Value

Type	Description
Double

TotalCount

The sum of TrueCount and FalseCount.

Declaration

[IgnoreDataMember]
public readonly double TotalCount { get; }

Property Value

Type	Description
Double

Methods

BetaLn(Double, Double)

Computes the log Beta function: GammaLn(trueCount)+GammaLn(falseCount)-GammaLn(trueCount+falseCount).

Declaration

public static double BetaLn(double trueCount, double falseCount)

Parameters

Type	Name	Description
Double	trueCount	Any real number.
Double	falseCount	Any real number.

Returns

Type	Description
Double	`GammaLn(trueCount)+GammaLn(falseCount)-GammaLn(trueCount+falseCount)`

Remarks

If trueCount <= 0 or falseCount <= 0, the result is defined to be 0.

Clone()

Clones this Beta.

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 Beta type

Equals(Object)

Override of the Equals method

Declaration

public override bool Equals(object that)

Parameters

Type	Name	Description
Object	that	The instance to compare to

Returns

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

Overrides

ValueType.Equals(Object)

FromDerivatives(Double, Double, Double, Boolean)

Construct a Beta distribution whose pdf has the given derivatives at a point.

Declaration

public static Beta FromDerivatives(double x, double dLogP, double ddLogP, bool forceProper)

Parameters

Type	Name	Description
Double	x	A real number in [0,1]
Double	dLogP	Desired derivative of log-density at x
Double	ddLogP	Desired second derivative of log-density at x
Boolean	forceProper	If true and both derivatives cannot be matched by a distribution with counts at least 1, match only the first.

Returns

Type	Description
Beta

FromMeanAndVariance(Double, Double)

Creates a new Beta distribution from a specified mean and variance

Declaration

public static Beta FromMeanAndVariance(double mean, double variance)

Parameters

Type	Name	Description
Double	mean	mean
Double	variance	variance

Returns

Type	Description
Beta	The new Beta distribution

FromMeanLogs(Double, Double)

Constructs a Beta distribution with the given E[log(p)] and E[log(1-p)].

Declaration

public static Beta FromMeanLogs(double eLogP, double eLogOneMinusP)

Parameters

Type	Name	Description
Double	eLogP	Desired expectation E[log(p)].
Double	eLogOneMinusP	Desired expectation E[log(1-p)].

Returns

Type	Description
Beta	A new Beta distribution.

Remarks

This function is equivalent to maximum-likelihood estimation of a Beta distribution from data given by sufficient statistics. So we want to maximize (a-1)eLogP + (b-1)eLogOneMinusP + Gamma(a+b) - Gamma(a) - Gamma(b) with respect to a, b where a=trueCount, b=falseCount. This function is significantly slower than the other constructors since it involves nonlinear optimization.

GetAverageLog(Beta)

The expected logarithm of that distribution under this distribution.

Declaration

public double GetAverageLog(Beta that)

Parameters

Type	Name	Description
Beta	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.

GetDerivatives(Beta, Double, out Double, out Double)

Get the derivatives of the log-pdf at a point.

Declaration

public static void GetDerivatives(Beta dist, double x, out double dlogp, out double ddlogp)

Parameters

Type	Name	Description
Beta	dist
Double	x
Double	dlogp	On exit, the first derivative.
Double	ddlogp	On exit, the second derivative.

GetDerivatives(Double, out Double, out Double)

Get the derivatives of the log-pdf at a point.

Declaration

public void GetDerivatives(double x, out double dlogp, out double ddlogp)

Parameters

Type	Name	Description
Double	x
Double	dlogp	On exit, the first derivative.
Double	ddlogp	On exit, the second derivative.

GetHashCode()

Override of GetHashCode method

Declaration

public override int GetHashCode()

Returns

Type	Description
Int32	The hash code for this instance

Overrides

ValueType.GetHashCode()

GetLogAverageOf(Beta)

The log of the integral of the product of this Beta and that Beta

Declaration

public double GetLogAverageOf(Beta that)

Parameters

Type	Name	Description
Beta	that	That beta

Returns

Type	Description
Double	The log inner product

GetLogAverageOfPower(Beta, Double)

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

Declaration

public double GetLogAverageOfPower(Beta that, double power)

Parameters

Type	Name	Description
Beta	that
Double	power

Returns

Type	Description
Double

GetLogNormalizer()

Gets the log normalizer for the distribution

Declaration

public double GetLogNormalizer()

Returns

Type	Description
Double

GetLogProb(Double)

Evaluates the logarithm of the density function

Declaration

public double GetLogProb(double value)

Parameters

Type	Name	Description
Double	value	Domain value

Returns

Type	Description
Double	Log of the probability density for the given domain value

GetMean()

The expected value E[p].

Declaration

public double GetMean()

Returns

Type	Description
Double	`TrueCount/TotalCount`

Remarks

The result must be between 0 and 1.

GetMeanAndVariance(out Double, out Double)

Gets the mean and variance for this instance

Declaration

public void GetMeanAndVariance(out double mean, out double variance)

Parameters

Type	Name	Description
Double	mean	Mean value - output
Double	variance	Variance - output

GetMeanCube()

The expected cube E[p^3].

Declaration

public double GetMeanCube()

Returns

Type	Description
Double

GetMeanLog()

The expected logarithm E[log(p)].

Declaration

public double GetMeanLog()

Returns

Type	Description
Double

GetMeanLogs(out Double, out Double)

The expected logarithms E[log(p)] and E[log(1-p)].

Declaration

public void GetMeanLogs(out double eLogP, out double eLogOneMinusP)

Parameters

Type	Name	Description
Double	eLogP
Double	eLogOneMinusP

GetMeanSquare()

The expected square E[p^2].

Declaration

public double GetMeanSquare()

Returns

Type	Description
Double

GetMode()

The most probable value.

Declaration

public double GetMode()

Returns

Type	Description
Double

GetProbBetween(Double, Double)

Returns the probability mass in an interval.

Declaration

public double GetProbBetween(double lowerBound, double upperBound)

Parameters

Type	Name	Description
Double	lowerBound
Double	upperBound

Returns

Type	Description
Double	A number between 0 and 1, inclusive.

GetProbLessThan(Double)

Compute the probability that a sample from this distribution is less than x.

Declaration

public double GetProbLessThan(double x)

Parameters

Type	Name	Description
Double	x	Any real number.

Returns

Type	Description
Double	The cumulative beta distribution at `x`

GetVariance()

The variance var(p).

Declaration

public double GetVariance()

Returns

Type	Description
Double

IsProper()

Whether the distribution is proper or not. It is improper when trueCount <= 0 or falseCount <= 0 in which case it cannot be normalised

Declaration

public bool IsProper()

Returns

Type	Description
Boolean	true if proper, false otherwise

IsUniform()

Whether the distribution is uniform

Declaration

public bool IsUniform()

Returns

Type	Description
Boolean	True if uniform

MaxDiff(Object)

The maximum 'difference' between the parameters of this instance and of that instance.

Declaration

public double MaxDiff(object thatd)

Parameters

Type	Name	Description
Object	thatd	That distribution

Returns

Type	Description
Double	The resulting maximum difference

Remarks

a.MaxDiff(b) == b.MaxDiff(a)

PointMass(Double)

Instantiates a point-mass Beta distribution

Declaration

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

Parameters

Type	Name	Description
Double	mean	The domain value where the point mass occurs

Returns

Type	Description
Beta	A new point-mass Beta distribution at the specified location

Sample()

Sample from this Beta distribution

Declaration

public double Sample()

Returns

Type	Description
Double	The sample value

Sample(Double)

Declaration

public double Sample(double result)

Parameters

Type	Name	Description
Double	result

Returns

Type	Description
Double

Sample(Double, Double)

Static method to sample from a Beta distribution with the specified true and false counts

Declaration

public static double Sample(double trueCount, double falseCount)

Parameters

Type	Name	Description
Double	trueCount	True count
Double	falseCount	False count

Returns

Type	Description
Double	The sample value

SampleFromMeanAndVariance(Double, Double)

Static method to sample from a Beta distribution with the specified mean and variance

Declaration

[ParameterNames(new string[]{"sample", "mean", "variance"})]
public static double SampleFromMeanAndVariance(double mean, double variance)

Parameters

Type	Name	Description
Double	mean	The mean of the Beta distribution to sample from
Double	variance	The variance of the Beta distribution to sample from

Returns

Type	Description
Double	The sample value

SetMeanAndVariance(Double, Double)

Sets the mean and variance for this instance

Declaration

public void SetMeanAndVariance(double mean, double variance)

Parameters

Type	Name	Description
Double	mean	Mean
Double	variance	Variance

SetTo(Beta)

Sets the parameters of this instance to the parameters of that instance

Declaration

public void SetTo(Beta value)

Parameters

Type	Name	Description
Beta	value	that instance

SetToPower(Beta, Double)

Sets the parameters to represent the a Beta raised to some power.

Declaration

public void SetToPower(Beta dist, double exponent)

Parameters

Type	Name	Description
Beta	dist	The distribution
Double	exponent	The exponent

SetToProduct(Beta, Beta)

Sets the parameters to represent the product of two Betas.

Declaration

public void SetToProduct(Beta a, Beta b)

Parameters

Type	Name	Description
Beta	a	The first distribution
Beta	b	The second distribution

Remarks

The result may not be proper, i.e. its parameters may be negative. For example, if you multiply Beta(0.1,0.1) by itself you get Beta(-0.8, -0.8). No error is thrown in this case.

SetToRatio(Beta, Beta, Boolean)

Sets the parameters to represent the ratio of two Betas.

Declaration

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

Parameters

Type	Name	Description
Beta	numerator	The numerator distribution. Can be the same object as this.
Beta	denominator	The denominator distribution. Can be the same object as this.
Boolean	forceProper	If true, the counts of the result are made >= 1, under the constraint that denominator*result has the same mean as numerator.

SetToSum(Double, Beta, Double, Beta)

Set the parameters to match the moments of a mixture distribution.

Declaration

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

Parameters

Type	Name	Description
Double	weight1	The first weight
Beta	dist1	The first distribution
Double	weight2	The second weight
Beta	dist2	The second distribution

SetToUniform()

Sets this instance to be uniform

Declaration

public void SetToUniform()

ToString()

Override of the ToString method

Declaration

public override string ToString()

Returns

Type	Description
String

Overrides

ValueType.ToString()

Uniform()

Instantiates a uniform Beta distribution

Declaration

[Construction(UseWhen = "IsUniform")]
public static Beta Uniform()

Returns

Type	Description
Beta	A new uniform Beta distribution

Operators

Division(Beta, Beta)

Static ratio operator. Create a Beta distribution which is the ratio of two Beta distributions

Declaration

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

Parameters

Type	Name	Description
Beta	numerator	The numerator distribution
Beta	denominator	The denominator distribution

Returns

Type	Description
Beta	The resulting Beta distribution

Equality(Beta, Beta)

Equals operator

Declaration

public static bool operator ==(Beta a, Beta b)

Parameters

Type	Name	Description
Beta	a
Beta	b

Returns

Type	Description
Boolean

ExclusiveOr(Beta, Double)

Raises a distribution to a power.

Declaration

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

Parameters

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

Returns

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

Inequality(Beta, Beta)

Not Equals operator

Declaration

public static bool operator !=(Beta a, Beta b)

Parameters

Type	Name	Description
Beta	a
Beta	b

Returns

Type	Description
Boolean

Multiply(Beta, Beta)

Static product operator. Create a Beta distribution which is the product of two Beta distributions

Declaration

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

Parameters

Type	Name	Description
Beta	a	The first distribution
Beta	b	The second distribution

Returns

Type	Description
Beta	The resulting Beta distribution

Implements

IDistribution<T>

IDistribution

System.ICloneable

HasPoint<T>

CanGetLogProb<T>

SettableTo<T>

SettableToProduct<T>

SettableToProduct<T, U>

Diffable

SettableToUniform

SettableToRatio<T>

SettableToRatio<T, U>

SettableToPower<T>

SettableToWeightedSum<T>

CanGetLogAverageOf<T>

CanGetLogAverageOfPower<T>

CanGetAverageLog<T>

CanGetLogNormalizer

Sampleable<T>

CanGetMean<MeanType>

CanGetVariance<VarType>

CanGetMeanAndVarianceOut<MeanType, VarType>

CanSetMeanAndVariance<MeanType, VarType>

CanGetMode<ModeType>

CanGetProbLessThan<T>