Struct Gaussian

Represents a one-dimensional Gaussian distribution.

Inherited Members
Namespace: Microsoft.ML.Probabilistic.Distributions
Assembly: Microsoft.ML.Probabilistic.dll
Syntax
[Serializable]
[DataContract]
[Quality(QualityBand.Mature)]
public struct Gaussian : IDistribution<double>, IDistribution, ICloneable, HasPoint<double>, CanGetLogProb<double>, SettableTo<Gaussian>, SettableToProduct<Gaussian>, SettableToProduct<Gaussian, Gaussian>, Diffable, SettableToUniform, SettableToRatio<Gaussian>, SettableToRatio<Gaussian, Gaussian>, SettableToPower<Gaussian>, SettableToWeightedSum<Gaussian>, Sampleable<double>, CanGetMean<double>, CanGetVariance<double>, CanGetMeanAndVarianceOut<double, double>, CanSetMeanAndVariance<double, double>, CanGetLogAverageOf<Gaussian>, CanGetLogAverageOfPower<Gaussian>, CanGetAverageLog<Gaussian>, CanGetLogNormalizer, CanGetMode<double>, ITruncatableDistribution<double>, CanGetProbLessThan<double>, CanGetQuantile<double>
Remarks

The distribution is represented by two parameters: MeanTimesPrecision and Precision. Precision is the inverse of the variance, so a Gaussian with mean m and variance v is represented as Precision = 1/v, MeanTimesPrecision = m/v.

Some special cases: If the Precision is zero, then the distribution is uniform. If the Precision is infinite, then the distribution is a point mass. The Point property gives the location of the point mass.

The formula for the distribution is: N(x;m,v) = 1/sqrt(2*pi*v) * exp(-(x-m)^2/(2v)). When v=0, this reduces to delta(x-m). When v=infinity, the density is redefined to be 1. When v < 0, the density is redefined to be exp(-0.5*x^2*(1/v) + x*(m/v)), i.e. we drop the terms exp(-m^2/(2v))/sqrt(2*pi*v).

Constructors

Gaussian(Gaussian)

Copy constructor.

Declaration
public Gaussian(Gaussian that)
Parameters
Type Name Description
Gaussian that

Gaussian(Double, Double)

Creates a Gaussian distribution with specified mean and variance.

Declaration
public Gaussian(double mean, double variance)
Parameters
Type Name Description
Double mean

Mean
Double variance

Variance

Fields

MeanTimesPrecision

Mean times precision

Declaration
[DataMember]
public double MeanTimesPrecision
Field Value
Type Description
Double

Precision

Precision

Declaration
[DataMember]
public double Precision
Field Value
Type Description
Double

Properties

IsPointMass

Asks whether the instance is a point mass

Declaration
[IgnoreDataMember]
public readonly bool IsPointMass { get; }
Property Value
Type Description
Boolean

Point

Sets/gets the instance as a point mass

Declaration
[IgnoreDataMember]
public double Point { get; set; }
Property Value
Type Description
Double

Methods

Clone()

Clones this Gaussian.

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

FromDerivatives(Double, Double, Double, Boolean)

Construct a Gaussian distribution whose log-pdf has the given derivatives at a point.

Declaration
public static Gaussian FromDerivatives(double x, double dlogp, double ddlogp, bool forceProper)
Parameters
Type Name Description
Double x
Double dlogp
Double ddlogp
Boolean forceProper

If true and both derivatives cannot be matched, match only the first.
Returns
Type Description
Gaussian

FromMeanAndPrecision(Double, Double)

Creates a Gaussian distribution with given mean and precision.

Declaration
public static Gaussian FromMeanAndPrecision(double mean, double precision)
Parameters
Type Name Description
Double mean

The desired mean.
Double precision

precision = 1/variance.
Returns
Type Description
Gaussian

A new Gaussian distribution.

FromMeanAndVariance(Double, Double)

Creates a Gaussian distribution with given mean and variance.

Declaration
public static Gaussian FromMeanAndVariance(double mean, double variance)
Parameters
Type Name Description
Double mean

The desired mean.
Double variance

The desired variance.
Returns
Type Description
Gaussian

A new Gaussian distribution.

FromNatural(Double, Double)

Creates a new Gaussian distribution from its natural parameters (Mean times precision, and Precision)

Declaration
[Construction(new string[]{"MeanTimesPrecision", "Precision"})]
public static Gaussian FromNatural(double meanTimesPrecision, double precision)
Parameters
Type Name Description
Double meanTimesPrecision

Mean time precision
Double precision

Precision
Returns
Type Description
Gaussian

A new Gaussian distribution.

GetAverageLog(Gaussian)

Gets the expected logarithm of that distribution under this distribution.

Declaration
public double GetAverageLog(Gaussian that)
Parameters
Type Name Description
Gaussian 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(Gaussian, Double, out Double, out Double)

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

Declaration
public static void GetDerivatives(Gaussian dist, double x, out double dlogp, out double ddlogp)
Parameters
Type Name Description
Gaussian 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

GetLogAverageOf(Gaussian)

Gets the integral of the product of two Gaussians.

Declaration
public double GetLogAverageOf(Gaussian that)
Parameters
Type Name Description
Gaussian that
Returns
Type Description
Double

log(N(m1;m2,v1+v2)).
Remarks

this = N(x;m1,v1). that = N(x;m2,v2). int_(-infinity)^(infinity) N(x;m1,v1) N(x;m2,v2) dx = N(m1; m2, v1+v2). When improper, the density is redefined to be exp(-0.5x^2(1/v) + x*(m/v)), i.e. we drop the terms exp(-m^2/(2v))/sqrt(2piv).

GetLogAverageOfPower(Gaussian, Double)

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

Declaration
public double GetLogAverageOfPower(Gaussian that, double power)
Parameters
Type Name Description
Gaussian that
Double power
Returns
Type Description
Double

GetLogNormalizer()

Gets the log of the normalizer for the Gaussian density function

Declaration
public double GetLogNormalizer()
Returns
Type Description
Double

GetLogProb(Double)

Evaluates the log of this one-dimensional Gaussian density.

Declaration
public double GetLogProb(double x)
Parameters
Type Name Description
Double x

Must be finite.
Returns
Type Description
Double

log(N(x;mean,variance))

GetLogProb(Double, Double, Double)

Evaluates the log of one-dimensional Gaussian density.

Declaration
public static double GetLogProb(double x, double mean, double variance)
Parameters
Type Name Description
Double x

Must be finite.
Double mean

Must be finite.
Double variance

Any real number. May be zero or negative.
Returns
Type Description
Double

log(N(x;mean,variance))
Remarks

N(x;m,v) = 1/sqrt(2piv) * exp(-(x-m)^2/(2v)). When v=0, this reduces to delta(x-m). When v=infinity, the density is redefined to be 1. When v < 0, the density is redefined to be exp(-0.5x^2(1/v) + x*(m/v)), i.e. we drop the terms exp(-m^2/(2v))/sqrt(2piv).

GetMean()

Gets the expected value E(x)

Declaration
public double GetMean()
Returns
Type Description
Double

E(x)

GetMeanAndPrecision(out Double, out Double)

Gets the mean and precision

Declaration
public void GetMeanAndPrecision(out double mean, out double precision)
Parameters
Type Name Description
Double mean

Where to put the mean
Double precision

Where to put the precision

GetMeanAndVariance(out Double, out Double)

Gets the mean and variance

Declaration
public void GetMeanAndVariance(out double mean, out double variance)
Parameters
Type Name Description
Double mean

Where to put the mean
Double variance

Where to put the variance

GetMode()

The most probable value

Declaration
public double GetMode()
Returns
Type Description
Double

GetNatural(out Double, out Double)

Gets the natural parameters of the distribution (mean time precision, and precision)

Declaration
public void GetNatural(out double meanTimesPrecision, out double precision)
Parameters
Type Name Description
Double meanTimesPrecision

Where to put the mean times precision
Double precision

Where to put the precision

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)

Returns the probability of drawing a sample less than x.

Declaration
public double GetProbLessThan(double x)
Parameters
Type Name Description
Double x
Returns
Type Description
Double

A real number in [0,1].

GetQuantile(Double)

Returns the largest value x such that GetProbLessThan(x) <= probability.

Declaration
public double GetQuantile(double probability)
Parameters
Type Name Description
Double probability

A real number in [0,1].
Returns
Type Description
Double

A number

GetVariance()

Gets the variance

Declaration
public double GetVariance()
Returns
Type Description
Double

Variance

IsProper()

Asks whether this Gaussian instance is proper or not. A Gaussian distribution is proper only if Precision > 0.

Declaration
public bool IsProper()
Returns
Type Description
Boolean

True if proper, false otherwise

IsUniform()

Asks whether this instance is uniform

Declaration
public bool IsUniform()
Returns
Type Description
Boolean

True if uniform, false otherwise

MaxDiff(Object)

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

Declaration
public double MaxDiff(object thatd)
Parameters
Type Name Description
Object thatd

That Gaussian
Returns
Type Description
Double

The maximum difference
Remarks

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

PointMass(Double)

Create a new point mass Gaussian distribution at a specified location

Declaration
[Construction(new string[]{"Point"}, UseWhen = "IsPointMass")]
public static Gaussian PointMass(double mean)
Parameters
Type Name Description
Double mean

The location for the point mass
Returns
Type Description
Gaussian

A new point mass Gaussian distribution.

Sample()

Samples from this Gaussian distribution

Declaration
public double Sample()
Returns
Type Description
Double

The sample value

Sample(Double)

Samples from this Gaussian distribution. This override is only present to support the Sampleable interface

Declaration
public double Sample(double result)
Parameters
Type Name Description
Double result

Ignored
Returns
Type Description
Double

The sample value

Sample(Double, Double)

Samples from a Gaussian distribution with the specified mean and precision

Declaration
public static double Sample(double mean, double precision)
Parameters
Type Name Description
Double mean
Double precision
Returns
Type Description
Double

The sample value

SetMeanAndPrecision(Double, Double)

Sets the mean and precision

Declaration
public void SetMeanAndPrecision(double mean, double precision)
Parameters
Type Name Description
Double mean

Mean
Double precision

Precision

SetMeanAndVariance(Double, Double)

Sets the mean and variance

Declaration
public void SetMeanAndVariance(double mean, double variance)
Parameters
Type Name Description
Double mean

Mean
Double variance

Variance

SetNatural(Double, Double)

Sets the natural parameters of the distribution (mean time precision, and precision)

Declaration
public void SetNatural(double meanTimesPrecision, double precision)
Parameters
Type Name Description
Double meanTimesPrecision

Mean times precision
Double precision

Precision

SetTo(Gaussian)

Sets this Gaussian instance to have the parameter values of that Gaussian instance

Declaration
public void SetTo(Gaussian that)
Parameters
Type Name Description
Gaussian that

That Gaussian

SetToPower(Gaussian, Double)

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

Declaration
public void SetToPower(Gaussian dist, double exponent)
Parameters
Type Name Description
Gaussian dist

The source Gaussian
Double exponent

The exponent

SetToProduct(Gaussian, Gaussian)

Sets the parameters to represent the product of two Gaussians.

Declaration
public void SetToProduct(Gaussian a, Gaussian b)
Parameters
Type Name Description
Gaussian a

The first Gaussian
Gaussian b

The second Gaussian
Remarks

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

SetToRatio(Gaussian, Gaussian, Boolean)

Sets the parameters to represent the ratio of two Gaussians, optionally forcing the precision to be non-negative.

Declaration
public void SetToRatio(Gaussian numerator, Gaussian denominator, bool forceProper = false)
Parameters
Type Name Description
Gaussian numerator

The numerator Gaussian. May be the same as this
Gaussian denominator

The denominator Gaussian
Boolean forceProper

If true, the result will have non-negative precision, under the constraint that result*denominator has the same mean as numerator

SetToSum(Double, Gaussian, Double, Gaussian)

Sets the mean and variance to match a Gaussian mixture.

Declaration
public void SetToSum(double weight1, Gaussian g1, double weight2, Gaussian g2)
Parameters
Type Name Description
Double weight1

First weight
Gaussian g1

First Gaussian
Double weight2

Second weight
Gaussian g2

Second Gaussian

SetToUniform()

Sets this Gaussian instance to be a uniform distribution

Declaration
public void SetToUniform()

ToString()

ToString override

Declaration
public override string ToString()
Returns
Type Description
String

String representation of the instance
Overrides

ToString(String)

Get a string representation of the distribution with a given number format

Declaration
public string ToString(string format)
Parameters
Type Name Description
String format

Format string to use for each number
Returns
Type Description
String

A string

Truncate(Double, Double)

Returns the distribution of values restricted to an interval.

Declaration
public ITruncatableDistribution<double> Truncate(double lowerBound, double upperBound)
Parameters
Type Name Description
Double lowerBound
Double upperBound
Returns
Type Description
ITruncatableDistribution<Double>

Uniform()

Creates a new uniform Gaussian distribution

Declaration
[Construction(UseWhen = "IsUniform")]
public static Gaussian Uniform()
Returns
Type Description
Gaussian

A new uniform Gaussian distribution.

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

Creates a distribution of the specified type which matches the mean and variance of a Gaussian mixture. The distribution type must implement CanGetMeanAndVarianceOut<MeanType, VarType>,

Declaration
public static T WeightedSum<T>(T result, double weight1, T dist1, double weight2, T dist2)
    where T : CanGetMeanAndVarianceOut<double, double>, CanSetMeanAndVariance<double, double>, SettableToUniform, SettableTo<T>
Parameters
Type Name Description
T result

Resulting distribution
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(Gaussian, Gaussian)

Creates a new Gaussian which is the ratio of two other Gaussians

Declaration
public static Gaussian operator /(Gaussian numerator, Gaussian denominator)
Parameters
Type Name Description
Gaussian numerator

numerator Gaussian
Gaussian denominator

denominator Gaussian
Returns
Type Description
Gaussian

Result

Equality(Gaussian, Gaussian)

Equals operator

Declaration
public static bool operator ==(Gaussian a, Gaussian b)
Parameters
Type Name Description
Gaussian a
Gaussian b
Returns
Type Description
Boolean

ExclusiveOr(Gaussian, Double)

Raises a distribution to a power.

Declaration
public static Gaussian operator ^(Gaussian dist, double exponent)
Parameters
Type Name Description
Gaussian dist

The distribution.
Double exponent

The power to raise to.
Returns
Type Description
Gaussian

dist raised to power exponent.

Inequality(Gaussian, Gaussian)

Not equals operator

Declaration
public static bool operator !=(Gaussian a, Gaussian b)
Parameters
Type Name Description
Gaussian a
Gaussian b
Returns
Type Description
Boolean

Multiply(Gaussian, Gaussian)

Creates a new Gaussian which is the product of two other Gaussians

Declaration
public static Gaussian operator *(Gaussian a, Gaussian b)
Parameters
Type Name Description
Gaussian a

First Gaussian
Gaussian b

Second Gaussian
Returns
Type Description
Gaussian

Result

Implements