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

Remarks

The distribution is p(x) = x^(a-1)*exp(-x*b)*b^a/Gamma(a). In this code, the a parameter is called the "Shape" and the b parameter is called the "Rate". The distribution is sometimes also parameterized by (shape,scale) where scale = 1/rate. The mean of the distribution is shape/rate and the variance is shape/rate^2.

Special cases: When the shape is 1 and rate is 0, the distribution is uniform. When the shape is infinity, the distribution is a point mass and the density is delta(x-Point) where the Point property gives the mean. When a <= 0 or b <= 0 the b^a/Gamma(a) term is dropped.

Constructors

Gamma(Gamma)

Copy constructor.

Declaration

public Gamma(Gamma that)

Parameters

Type	Name	Description
Gamma	that

Gamma(Double, Double)

Creates a Gamma distribution with given shape and scale parameters (scale = 1/rate)

Declaration

public Gamma(double shape, double scale)

Parameters

Type	Name	Description
Double	shape
Double	scale	scale = 1/rate

Remarks

The distribution is p(x) = x^(shape-1)*exp(-x/scale)/(scale^shape * Gamma(shape)).

Fields

Rate

Rate parameter for the distribution

Declaration

[DataMember]
public double Rate

Field Value

Type	Description
Double

Shape

Shape parameter for the distribution

Declaration

[DataMember]
public double Shape

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 Gamma.

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 Gamma 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)

FromDerivatives(Double, Double, Double, Boolean)

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

Declaration

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

Parameters

Type	Name	Description
Double	x	Cannot be negative
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 proper distribution, match only the first.

Returns

Type	Description
Gamma

FromLogMeanMinusMeanLog(Double, Double)

Constructs a Gamma distribution with the given mean and mean logarithm.

Declaration

public static Gamma FromLogMeanMinusMeanLog(double mean, double logMeanMinusMeanLog)

Parameters

Type	Name	Description
Double	mean	Desired expected value.
Double	logMeanMinusMeanLog	Logarithm of desired expected value minus desired expected logarithm.

Returns

Type	Description
Gamma	A new Gamma distribution.

Remarks

This function is equivalent to maximum-likelihood estimation of a Gamma 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.

FromMeanAndMeanLog(Double, Double)

Constructs a Gamma distribution with the given mean and mean logarithm.

Declaration

public static Gamma FromMeanAndMeanLog(double mean, double meanLog)

Parameters

Type	Name	Description
Double	mean	Desired expected value.
Double	meanLog	Desired expected logarithm.

Returns

Type	Description
Gamma	A new Gamma distribution.

Remarks

FromMeanAndVariance(Double, Double)

Creates a new Gamma distribution from mean and variance

Declaration

public static Gamma FromMeanAndVariance(double mean, double variance)

Parameters

Type	Name	Description
Double	mean	Mean
Double	variance	Variance

Returns

Type	Description
Gamma	A new Gamma instance

FromNatural(Double, Double)

Constructs a Gamma distribution from its natural parameters.

Declaration

public static Gamma FromNatural(double shapeMinus1, double rate)

Parameters

Type	Name	Description
Double	shapeMinus1	shape - 1
Double	rate	rate = 1/scale

Returns

Type	Description
Gamma	A new Gamma distribution

FromShapeAndRate(Double, Double)

Constructs a Gamma distribution with the given shape and rate parameters.

Declaration

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

Parameters

Type	Name	Description
Double	shape	shape
Double	rate	rate = 1/scale

Returns

Type	Description
Gamma	A new Gamma distribution.

FromShapeAndScale(Double, Double)

Constructs a Gamma distribution with the given shape and scale parameters.

Declaration

public static Gamma FromShapeAndScale(double shape, double scale)

Parameters

Type	Name	Description
Double	shape	shape
Double	scale	scale

Returns

Type	Description
Gamma	A new Gamma distribution.

GetAverageLog(Gamma)

The expected logarithm of that distribution under this distribution.

Declaration

public double GetAverageLog(Gamma that)

Parameters

Type	Name	Description
Gamma	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(Gamma, Double, out Double, out Double)

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

Declaration

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

Parameters

Type	Name	Description
Gamma	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(Gamma)

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

Declaration

public double GetLogAverageOf(Gamma that)

Parameters

Type	Name	Description
Gamma	that	That Gamma

Returns

Type	Description
Double	The log inner product

GetLogAverageOfPower(Gamma, Double)

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

Declaration

public double GetLogAverageOfPower(Gamma that, double power)

Parameters

Type	Name	Description
Gamma	that
Double	power

Returns

Type	Description
Double

GetLogMeanMinusMeanLog()

Gets the logarithm of the expected value minus the expected logarithm, more accurately than directly computing Math.Log(GetMean()) - GetMeanLog().

Declaration

public double GetLogMeanMinusMeanLog()

Returns

Type	Description
Double

GetLogNormalizer()

Gets log normalizer

Declaration

public double GetLogNormalizer()

Returns

Type	Description
Double

GetLogProb(Double)

Logarithm of this Gamma density function.

Declaration

public double GetLogProb(double x)

Parameters

Type	Name	Description
Double	x	Where to evaluate the density

Returns

Type	Description
Double	log(Gamma(x;shape,rate))

GetLogProb(Double, Double, Double)

Logarithm of the Gamma density function.

Declaration

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

Parameters

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

Returns

Type	Description
Double	log(Gamma(x;shape,rate))

Remarks

The distribution is p(x) = x^(a-1)exp(-xb)*b^a/Gamma(a). When a <= 0 or b <= 0 the b^a/Gamma(a) term is dropped. Thus if shape = 1 and rate = 0 the density is 1.

GetMean()

Gets the expected value E(x) - calculated as shape/rate

Declaration

public double GetMean()

Returns

Type	Description
Double	E(x)

GetMeanAndVariance(out Double, out Double)

Gets the mean (shape/rate) and variance (shape/rate^2)

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

GetMeanInverse()

Computes E[1/x]

Declaration

public double GetMeanInverse()

Returns

Type	Description
Double

GetMeanLog()

Computes E[log(x)]

Declaration

public double GetMeanLog()

Returns

Type	Description
Double

GetMeanPower(Double)

Computes E[x^power]

Declaration

public double GetMeanPower(double power)

Parameters

Type	Name	Description
Double	power

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)

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

GetScale()

Gets the scale (1/rate)

Declaration

public double GetScale()

Returns

Type	Description
Double

GetShapeAndScale(out Double, out Double)

Gets the shape and scale (1/rate)

Declaration

public void GetShapeAndScale(out double shape, out double scale)

Parameters

Type	Name	Description
Double	shape	Where to put the shape
Double	scale	Where to put the scale

GetVariance()

Gets the variance - calculated as shape/rate^2

Declaration

public double GetVariance()

Returns

Type	Description
Double	Variance

IsProper()

Asks whether this Gamma instance is proper or not. A Gamma distribution is proper only if Shape > 0 and Rate > 0.

Declaration

public bool IsProper()

Returns

Type	Description
Boolean	True if proper, false otherwise

IsProper(Double, Double)

Asks whether a Gamma distribution is proper or not. A Gamma distribution is proper only if Shape > 0 and Rate > 0.

Declaration

public static bool IsProper(double shape, double rate)

Parameters

Type	Name	Description
Double	shape	shape parameter for the Gamma
Double	rate	rate parameter for the Gamma

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 Gamma and that Gamma

Declaration

public double MaxDiff(object thatd)

Parameters

Type	Name	Description
Object	thatd	That Gamma

Returns

Type	Description
Double	The maximum difference

Remarks

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

PointMass(Double)

Creates a point mass Gamma distribution

Declaration

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

Parameters

Type	Name	Description
Double	mean	The location of the point mass

Returns

Type	Description
Gamma	A new point mass Gamma distribution

Sample()

Samples from this Gamma distribution

Declaration

public double Sample()

Returns

Type	Description
Double	The sample value

Sample(Double)

Samples from this Gamma distribution

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 Gamma distribution with given shape and scale

Declaration

public static double Sample(double shape, double scale)

Parameters

Type	Name	Description
Double	shape	shape parameter
Double	scale	scale parameter

Returns

Type	Description
Double	The sample value

SampleFromMeanAndVariance(Double, Double)

Samples from a Gamma distribution with given mean and variance

Declaration

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

Parameters

Type	Name	Description
Double	mean	mean parameter
Double	variance	variance parameter

Returns

Type	Description
Double	The sample value

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.

Declaration

public void SetNatural(double shapeMinus1, double rate)

Parameters

Type	Name	Description
Double	shapeMinus1	The shape parameter - 1.
Double	rate	rate = 1/scale

SetShapeAndRate(Double, Double)

Sets the shape and rate (rate = 1/scale) parameters of the distribution.

Declaration

public void SetShapeAndRate(double shape, double rate)

Parameters

Type	Name	Description
Double	shape
Double	rate	rate = 1/scale

SetShapeAndScale(Double, Double)

Sets the shape and scale for this instance

Declaration

public void SetShapeAndScale(double shape, double scale)

Parameters

Type	Name	Description
Double	shape	Shape
Double	scale	Scale

SetTo(Gamma)

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

Declaration

public void SetTo(Gamma that)

Parameters

Type	Name	Description
Gamma	that	That Gamma

SetToPower(Gamma, Double)

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

Declaration

public void SetToPower(Gamma dist, double exponent)

Parameters

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

SetToProduct(Gamma, Gamma)

Sets the parameters to represent the product of two Gammas.

Declaration

public void SetToProduct(Gamma a, Gamma b)

Parameters

Type	Name	Description
Gamma	a	The first Gamma
Gamma	b	The second Gamma

Remarks

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

SetToRatio(Gamma, Gamma, Boolean)

Sets the parameters to represent the ratio of two Gammas

Declaration

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

Parameters

Type	Name	Description
Gamma	numerator	The numerator Gamma. Can be the same object as this.
Gamma	denominator	The denominator Gamma. Can be the same object as this.
Boolean	forceProper	If true, the result has shape >= 1 and rate >= 0, under the constraint that result*denominator has the same mean as numerator

SetToSum(Double, Gamma, Double, Gamma)

Set the mean and variance to match the moments of a mixture of two Gammas.

Declaration

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

Parameters

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

SetToUniform()

Sets this Gamma 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

ValueType.ToString()

Uniform()

Create a uniform Gamma distribution.

Declaration

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

Returns

Type	Description
Gamma	A new uniform Gamma distribution

Operators

Division(Gamma, Gamma)

Creates a new Gamma which the ratio of two other Gammas

Declaration

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

Parameters

Type	Name	Description
Gamma	numerator	numerator Gamma
Gamma	denominator	denominator Gamma

Returns

Type	Description
Gamma	Result

Equality(Gamma, Gamma)

Equals operator

Declaration

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

Parameters

Type	Name	Description
Gamma	a
Gamma	b

Returns

Type	Description
Boolean

ExclusiveOr(Gamma, Double)

Raises a distribution to a power.

Declaration

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

Parameters

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

Returns

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

Inequality(Gamma, Gamma)

Not equals operator

Declaration

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

Parameters

Type	Name	Description
Gamma	a
Gamma	b

Returns

Type	Description
Boolean

Multiply(Gamma, Gamma)

Creates a new Gamma which the product of two other Gammas

Declaration

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

Parameters

Type	Name	Description
Gamma	a	First Gamma
Gamma	b	Second Gamma

Returns

Type	Description
Gamma	Result

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>

Sampleable<T>

CanGetMean<MeanType>

CanGetVariance<VarType>

CanGetMeanAndVarianceOut<MeanType, VarType>

CanSetMeanAndVariance<MeanType, VarType>

CanGetLogAverageOf<T>

CanGetLogAverageOfPower<T>

CanGetAverageLog<T>

CanGetLogNormalizer

CanGetMode<ModeType>

CanGetProbLessThan<T>

CanGetQuantile<T>