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

Remarks

The most common way to use the distribution is to get and set its ProbTrue property.

The distribution is represented by a single number, the log odds: log p(x=true)/p(x=false). If this is 0, then the distribution is uniform. If this is infinity, then the distribution is a point mass on x=true. If this is -infinity, then the distribution is a point mass on x=false. In terms of the log odds, p(x=true) = 1/(1+exp(-logOdds)).

Constructors

Bernoulli(Bernoulli)

Copy constructor.

Declaration

public Bernoulli(Bernoulli that)

Parameters

Type	Name	Description
Bernoulli	that

Bernoulli(Double)

Creates a Bernoulli distribution with given probability of being true.

Declaration

public Bernoulli(double probTrue)

Parameters

Type	Name	Description
Double	probTrue	p(true)

Fields

LogOdds

Log odds parameter

Declaration

[DataMember]
public double LogOdds

Field Value

Type	Description
Double

Properties

IsPointMass

Whether the distribution is a point mass (true with probability 1 or false with probability 1)

Declaration

[IgnoreDataMember]
public readonly bool IsPointMass { get; }

Property Value

Type	Description
Boolean

Point

Gets/sets the distribution as a point

Declaration

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

Property Value

Type	Description
Boolean

Methods

Clone()

Clones this Bernoulli.

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 Bernoulli 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

ValueType.Equals(Object)

FromLogOdds(Double)

Instantiates a Bernoulli distribution from a log-odds value

Declaration

[Construction(new string[]{"LogOdds"})]
public static Bernoulli FromLogOdds(double logOdds)

Parameters

Type	Name	Description
Double	logOdds	The log-odds

Returns

Type	Description
Bernoulli	A new Bernoulli distribution at the specified log-odds

Gate(Double, Double)

Computes the Bernoulli gating function in the log-odds domain.

Declaration

public static double Gate(double x, double gate)

Parameters

Type	Name	Description
Double	x
Double	gate

Returns

Type	Description
Double

Remarks

The Bernoulli gating function is x if gate = -infinity and 0 if gate = infinity. It is one of the messages sent by a logical OR factor. In the log-odds domain, this is: log (1 + exp(-gate))/(1 + exp(-gate-x))

GetAverageLog(Bernoulli)

The expected logarithm of that distribution under this distribution.

Declaration

public double GetAverageLog(Bernoulli that)

Parameters

Type	Name	Description
Bernoulli	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

ValueType.GetHashCode()

GetLogAverageOf(Bernoulli)

Log of the probability that a draw from this distribution is equal to a draw from that distribution.

Declaration

public double GetLogAverageOf(Bernoulli that)

Parameters

Type	Name	Description
Bernoulli	that	That distribution

Returns

Type	Description
Double	The resulting log probability

GetLogAverageOfPower(Bernoulli, Double)

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

Declaration

public double GetLogAverageOfPower(Bernoulli that, double power)

Parameters

Type	Name	Description
Bernoulli	that
Double	power

Returns

Type	Description
Double

GetLogNormalizer()

Gets the log normalizer of the distribution

Declaration

public double GetLogNormalizer()

Returns

Type	Description
Double	This equals -log(1-p)

GetLogProb(Boolean)

Evaluates the logarithm of the density function

Declaration

public double GetLogProb(bool x)

Parameters

Type	Name	Description
Boolean	x	true or false

Returns

Type	Description
Double	Log of the probability density for the given event

GetLogProbFalse()

Gets the log probability of the binary variable being false

Declaration

public double GetLogProbFalse()

Returns

Type	Description
Double	log(p(x=false))

GetLogProbTrue()

Gets the log probability of the binary variable being true

Declaration

public double GetLogProbTrue()

Returns

Type	Description
Double	log(p(x=true))

GetMean()

Gets the mean of this Bernoulli distribution

Declaration

public double GetMean()

Returns

Type	Description
Double	The mean

GetMode()

The most probable value.

Declaration

public bool GetMode()

Returns

Type	Description
Boolean

GetProbFalse()

Gets the probability of the binary variable being false

Declaration

public double GetProbFalse()

Returns

Type	Description
Double	p(x=false)

GetProbTrue()

Gets the probability of the binary variable being true

Declaration

public double GetProbTrue()

Returns

Type	Description
Double	p(x=true)

GetVariance()

Gets the variance of this Bernoulli distribution

Declaration

public double GetVariance()

Returns

Type	Description
Double	The variance

IsUniform()

Whether the distribution is uniform

Declaration

public bool IsUniform()

Returns

Type	Description
Boolean	True if uniform

LogitProbEqual(Double, Double)

Computes the logical AreEqual function in the log-odds domain.

Declaration

public static double LogitProbEqual(double x, double y)

Parameters

Type	Name	Description
Double	x	The log-odds of variable A, which can be any real number from -Inf to Inf.
Double	y	The log-odds of variable B, which can be any real number from -Inf to Inf.

Returns

Type	Description
Double	The log-odds that A == B.

Remarks

The logical LogitProbEqual function is defined as p1 EQ p2 = p1p2 + (1-p1)(1-p2). It is the same as the complement of XOR: !(p1 XOR p2). In the log-odds domain, this is: LogOdds(Logistic(x) EQ Logistic(y)) = log (1+exp(-x-y))/(exp(-x)+exp(-y)). To compute this reliably when x>0 and y>0, factor out min(x,y). For other cases, use the identity AE(-x,-y) = AE(x,y) and AE(-x,y) = AE(x,-y) = -AE(x,y). Note the result is 0 if x=0 or y=0.

LogProbEqual(Double, Double)

Computes the log-probability that A==B where p(A)=Logistic(x), p(B)=Logistic(y).

Declaration

public static double LogProbEqual(double x, double y)

Parameters

Type	Name	Description
Double	x	The log-odds of variable A, which can be any real number from -Inf to Inf.
Double	y	The log-odds of variable B, which can be any real number from -Inf to Inf.

Returns

Type	Description
Double	The log-probability that A==B.

Remarks

The result is Math.Log(0.5) if x=0 or y=0.

MaxDiff(Object)

The maximum 'difference' between this instance and that instance. This returns the absolute difference between the Log-odds

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)

Or(Double, Double)

Computes the logical OR function in the log-odds domain.

Declaration

public static double Or(double x, double y)

Parameters

Type	Name	Description
Double	x	Any real number, including infinity.
Double	y	Any real number, including infinity.

Returns

Type	Description
Double	The log odds of (p1 OR p2), where p1 = Logistic(x) and p2 = Logistic(y)

Remarks

The logical OR function is defined as p1 OR p2 = 1 - (1-p1)(1-p2) = p1 + p2 - p1p2. In the log-odds domain, this is: LogOdds(Logistic(x) OR Logistic(y)) = log(exp(x) + exp(y) + exp(x+y)).
To compute this reliably, factor out max(x,y,x+y).

PointMass(Boolean)

Instantiates a point-mass Bernoulli distribution

Declaration

public static Bernoulli PointMass(bool value)

Parameters

Type	Name	Description
Boolean	value	true of false

Returns

Type	Description
Bernoulli	A new point-mass Bernoulli distribution at the specified value

Sample()

Samples from a Bernoulli distribution

Declaration

public bool Sample()

Returns

Type	Description
Boolean	The sample value

Sample(Boolean)

Declaration

public bool Sample(bool x)

Parameters

Type	Name	Description
Boolean	x

Returns

Type	Description
Boolean

Sample(Double)

Samples from a Bernoulli distribution with a specified p(true)

Declaration

public static bool Sample(double probTrue)

Parameters

Type	Name	Description
Double	probTrue	p(true)

Returns

Type	Description
Boolean	The sample

SetLogProbFalse(Double)

Sets the log probability of the binary variable being false

Declaration

public void SetLogProbFalse(double logProbFalse)

Parameters

Type	Name	Description
Double	logProbFalse

SetLogProbTrue(Double)

Sets the log probability of the binary variable being true

Declaration

public void SetLogProbTrue(double logProbTrue)

Parameters

Type	Name	Description
Double	logProbTrue

SetMean(Double)

Sets the mean of this Bernoulli distribution

Declaration

public void SetMean(double mean)

Parameters

Type	Name	Description
Double	mean	The mean

SetProbFalse(Double)

Sets the probability of the binary variable being false

Declaration

public void SetProbFalse(double probFalse)

Parameters

Type	Name	Description
Double	probFalse

SetProbTrue(Double)

Sets the probability of the binary variable being true

Declaration

public void SetProbTrue(double probTrue)

Parameters

Type	Name	Description
Double	probTrue

SetTo(Bernoulli)

Sets this instance to have the parameters of another instance

Declaration

public void SetTo(Bernoulli that)

Parameters

Type	Name	Description
Bernoulli	that	The source Bernoulli distribution

SetToPower(Bernoulli, Double)

Sets this instance to the power of a Bernoulli distributions

Declaration

public void SetToPower(Bernoulli dist, double exponent)

Parameters

Type	Name	Description
Bernoulli	dist	The distribution to raise to a power
Double	exponent	The exponent

SetToProduct(Bernoulli, Bernoulli)

Sets this instance to a product of two Bernoulli distributions

Declaration

public void SetToProduct(Bernoulli a, Bernoulli b)

Parameters

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

SetToRatio(Bernoulli, Bernoulli, Boolean)

Sets this instance to a ratio of two Bernoulli distributions

Declaration

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

Parameters

Type	Name	Description
Bernoulli	numerator	The numerator distribution
Bernoulli	denominator	The denominator distribution
Boolean	forceProper	Ignored

SetToSum(Double, Bernoulli, Double, Bernoulli)

Creates a Bernoulli distribution which is a weighted sum of two Bernoulli distribution

Declaration

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

Parameters

Type	Name	Description
Double	weight1	The weight for the first distribution
Bernoulli	dist1	The first distribution
Double	weight2	The weight for the second distribution
Bernoulli	dist2	The second distribution

SetToUniform()

Sets the distribution to uniform

Declaration

public void SetToUniform()

ToString()

Override of ToString method

Declaration

public override string ToString()

Returns

Type	Description
String	String representation of instance - shows distribution type and p(true)

Overrides

ValueType.ToString()

Uniform()

Instantiates a uniform Bernoulli distribution

Declaration

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

Returns

Type	Description
Bernoulli	A new uniform Bernoulli distribution

Operators

Division(Bernoulli, Bernoulli)

Creates a Bernoulli distribution which is the ratio of two Bernoulli distribution

Declaration

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

Parameters

Type	Name	Description
Bernoulli	numerator	The numerator distribution
Bernoulli	denominator	The denominator distribution

Returns

Type	Description
Bernoulli	The resulting Bernoulli distribution

Equality(Bernoulli, Bernoulli)

Equals operator

Declaration

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

Parameters

Type	Name	Description
Bernoulli	a
Bernoulli	b

Returns

Type	Description
Boolean

ExclusiveOr(Bernoulli, Double)

Raises this distribution to a power.

Declaration

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

Parameters

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

Returns

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

Inequality(Bernoulli, Bernoulli)

Not equals operator

Declaration

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

Parameters

Type	Name	Description
Bernoulli	a
Bernoulli	b

Returns

Type	Description
Boolean

LogicalNot(Bernoulli)

Creates the complementary distribution

Declaration

public static Bernoulli operator !(Bernoulli dist)

Parameters

Type	Name	Description
Bernoulli	dist	The original distribution

Returns

Type	Description
Bernoulli	The complementary distribution

Multiply(Bernoulli, Bernoulli)

Creates a Bernoulli distribution which is the product of two Bernoulli distribution

Declaration

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

Parameters

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

Returns

Type	Description
Bernoulli	The resulting Bernoulli distribution

Implements

IDistribution<T>

IDistribution

System.ICloneable

Diffable

HasPoint<T>

CanGetLogProb<T>

SettableTo<T>

SettableToProduct<T>

SettableToProduct<T, U>

SettableToUniform

SettableToRatio<T>

SettableToRatio<T, U>

SettableToPower<T>

SettableToWeightedSumExact<T>

SettableToWeightedSum<T>

Sampleable<T>

CanGetMean<MeanType>

CanSetMean<MeanType>

CanGetVariance<VarType>

CanGetLogAverageOf<T>

CanGetLogAverageOfPower<T>

CanGetAverageLog<T>

CanGetLogNormalizer

CanGetMode<ModeType>