Struct GammaPower

The distribution of a Gamma variable raised to a power. The Weibull distribution is a special case.

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

The Gamma-power distribution is defined as the distribution of a Gamma(a,b) variable raised to the power c. Thus it has three parameters (a,b,c) and probability density function p(x) = x^(a/c-1)*exp(-b*x^(1/c))*b^a/Gamma(a)/abs(c). In this implementation, the a parameter is called the "Shape", the b parameter is called the "Rate", and the c parameter is called the "Power". The power can be any real number, positive or negative. The distribution is sometimes also parameterized by (shape,scale,power) where scale = 1/rate.

Special cases: When the power is 1 it reduces to a Gamma distribution. When the shape is 1 it reduces to a Weibull distribution. When the shape equals the power 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 the power is zero, the distribution is a point mass at one. When a <= 0 or b <= 0 the b^a/Gamma(a)/abs(c) term is dropped.

Constructors

GammaPower(GammaPower)

Copy constructor.

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

GammaPower(Double, Double, Double)

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

Declaration
public GammaPower(double shape, double scale, double power)
Parameters
Type Name Description
Double shape
Double scale

scale = 1/rate
Double power
Remarks

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

Fields

Power

Power parameter for the distribution

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

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

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

FromGamma(Gamma, Double)

Constructs a GammaPower distribution from a Gamma distribution.

Declaration
public static GammaPower FromGamma(Gamma gamma, double power)
Parameters
Type Name Description
Gamma gamma
Double power
Returns
Type Description
GammaPower

FromLogMeanMinusMeanLog(Double, Double, Double)

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

Declaration
public static GammaPower FromLogMeanMinusMeanLog(double mean, double logMeanMinusMeanLog, double power)
Parameters
Type Name Description
Double mean

Desired expected value.
Double logMeanMinusMeanLog

Logarithm of desired expected value minus desired expected logarithm.
Double power

Desired power.
Returns
Type Description
GammaPower

A new GammaPower 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, Double)

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

Declaration
public static GammaPower FromMeanAndMeanLog(double mean, double meanLog, double power)
Parameters
Type Name Description
Double mean

Desired expected value.
Double meanLog

Desired expected logarithm.
Double power

Desired power.
Returns
Type Description
GammaPower

A new GammaPower 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.

FromMeanAndVariance(Double, Double, Double)

Creates a new Gamma distribution from mean and variance

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

Mean
Double variance

Variance
Double power
Returns
Type Description
GammaPower

A new Gamma instance

FromShapeAndRate(Double, Double, Double)

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

Declaration
[Construction(new string[]{"Shape", "Rate", "Power"})]
public static GammaPower FromShapeAndRate(double shape, double rate, double power)
Parameters
Type Name Description
Double shape

shape
Double rate

rate = 1/scale
Double power
Returns
Type Description
GammaPower

A new Gamma distribution.

FromShapeAndScale(Double, Double, Double)

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

Declaration
public static GammaPower FromShapeAndScale(double shape, double scale, double power)
Parameters
Type Name Description
Double shape

shape
Double scale

scale
Double power
Returns
Type Description
GammaPower

A new Gamma distribution.

GetAverageLog(GammaPower)

The expected logarithm of that distribution under this distribution.

Declaration
public double GetAverageLog(GammaPower that)
Parameters
Type Name Description
GammaPower 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

GetLogAverageOf(GammaPower)

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

Declaration
public double GetLogAverageOf(GammaPower that)
Parameters
Type Name Description
GammaPower that

That Gamma
Returns
Type Description
Double

The log inner product

GetLogAverageOfPower(GammaPower, Double)

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

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

GetLogMeanPower(Double)

Computes log(E[x^power])

Declaration
public double GetLogMeanPower(double power)
Parameters
Type Name Description
Double power
Returns
Type Description
Double

GetLogNormalizer()

Gets log normalizer

Declaration
public double GetLogNormalizer()
Returns
Type Description
Double

GetLogProb(Double)

Logarithm of the 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,power))

GetLogProb(Double, Double, Double, Double)

Logarithm of the density function.

Declaration
public static double GetLogProb(double x, double shape, double rate, double power)
Parameters
Type Name Description
Double x

Where to evaluate the density
Double shape

Shape parameter
Double rate

Rate parameter
Double power

Power parameter
Returns
Type Description
Double

log(GammaPower(x;shape,rate,power))
Remarks

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

GetMean()

Get the expected value E(x)

Declaration
public double GetMean()
Returns
Type Description
Double

E(x)

GetMeanAndVariance(out Double, out Double)

Get 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

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

Returns x where GetLogProb(x) is highest.

Declaration
public double GetMode()
Returns
Type Description
Double

GetMode(Double, Double, Double)

Returns x where GetLogProb(x, shape, rate, power) is highest.

Declaration
public static double GetMode(double shape, double rate, double power)
Parameters
Type Name Description
Double shape

Shape parameter
Double rate

Rate parameter
Double power

Power parameter
Returns
Type Description
Double

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 gamma distribution at x

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

GetVariance()

Get the variance

Declaration
public double GetVariance()
Returns
Type Description
Double

Variance

IsProper()

Asks whether this GammaPower instance is proper or not. A GammaPower distribution is proper only if Shape > 0 and 0 < Rate < infinity and Power is not infinite.

Declaration
public bool IsProper()
Returns
Type Description
Boolean

True if proper, false otherwise

IsProper(Double, Double, Double)

Asks whether a GammaPower distribution is proper or not. A GammaPower distribution is proper only if Shape > 0 and 0 < Rate < infinity and Power is not infinite.

Declaration
public static bool IsProper(double shape, double rate, double power)
Parameters
Type Name Description
Double shape

shape parameter
Double rate

rate parameter
Double power

power parameter
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 distribution and that distribution

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

distribution to compare to
Returns
Type Description
Double

The maximum difference
Remarks

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

PointMass(Double, Double)

Creates a point mass Gamma distribution

Declaration
public static GammaPower PointMass(double mean, double power)
Parameters
Type Name Description
Double mean

The location of the point mass
Double power
Returns
Type Description
GammaPower

A new point mass Gamma distribution

Sample()

Draw a sample from the 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, Double)

Samples from a Gamma distribution with given shape and scale

Declaration
public static double Sample(double shape, double scale, double power)
Parameters
Type Name Description
Double shape

shape parameter
Double scale

scale parameter
Double power
Returns
Type Description
Double

The sample value

SampleFromMeanAndVariance(Double, Double, Double)

Samples from a Gamma distribution with given mean and variance

Declaration
[ParameterNames(new string[]{"sample", "mean", "variance", "power"})]
public static double SampleFromMeanAndVariance(double mean, double variance, double power)
Parameters
Type Name Description
Double mean

mean parameter
Double variance

variance parameter
Double power
Returns
Type Description
Double

The sample value

SetMeanAndVariance(Double, Double)

Set the mean and variance

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

Mean
Double variance

Variance

SetShapeAndRate(Double, Double, Double)

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

Declaration
public void SetShapeAndRate(double shape, double rate, double power)
Parameters
Type Name Description
Double shape
Double rate

rate = 1/scale
Double power

SetShapeAndScale(Double, Double, Double)

Sets the shape and scale for this instance

Declaration
public void SetShapeAndScale(double shape, double scale, double power)
Parameters
Type Name Description
Double shape

Shape
Double scale

Scale
Double power

SetTo(GammaPower)

Set this distribution to have the same parameter values as that

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

the source parameters

SetToPower(GammaPower, Double)

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

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

The source distribution
Double exponent

The exponent

SetToProduct(GammaPower, GammaPower)

Set the parameters so that the density function equals the product of two given GammaPower density functions

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

The first distribution
GammaPower b

The second distribution. Must have the same power parameter as a
Remarks

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

SetToRatio(GammaPower, GammaPower, Boolean)

Sets the parameters so that the density function equals the ratio of two given GammaPower density functions

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

The numerator distribution. Can be the same object as this.
GammaPower denominator

The denominator distribution. Must have the same power parameter as numerator
Boolean forceProper

If true, the result has shape >= power and rate >= 0

SetToSum(Double, GammaPower, Double, GammaPower)

Sets the mean and variance to match a mixture of two GammaPower distributions.

Declaration
public void SetToSum(double weight1, GammaPower dist1, double weight2, GammaPower dist2)
Parameters
Type Name Description
Double weight1

The first weight
GammaPower dist1

The first distribution
Double weight2

The second weight
GammaPower dist2

The second distribution

SetToUniform()

Set shape and rate to be a uniform distribution, without changing the power.

Declaration
public void SetToUniform()

ToString()

ToString override

Declaration
public override string ToString()
Returns
Type Description
String

String representation of the instance
Overrides

Uniform(Double)

Create a uniform GammaPower distribution.

Declaration
[Construction(new string[]{"Power"}, UseWhen = "IsUniform")]
public static GammaPower Uniform(double power)
Parameters
Type Name Description
Double power
Returns
Type Description
GammaPower

A new uniform GammaPower distribution

Operators

Division(GammaPower, GammaPower)

Creates a new GammaPower distribution whose density function equals the ratio of two other GammaPower density functions

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

The numerator distribution
GammaPower denominator

The denominator distribution. Must have the same power parameter as numerator
Returns
Type Description
GammaPower

Result. May not be proper.

Division(GammaPower, Double)

Creates a new GammaPower distribution corresponding to dividing every sample by a positive constant.

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

The numerator distribution
Double denominator

The denominator constant.
Returns
Type Description
GammaPower

Result. May not be proper.

Equality(GammaPower, GammaPower)

Equals operator

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

ExclusiveOr(GammaPower, Double)

Raises a distribution to a power.

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

The distribution.
Double exponent

The power to raise to.
Returns
Type Description
GammaPower

dist raised to power exponent.

Inequality(GammaPower, GammaPower)

Not equals operator

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

Multiply(GammaPower, GammaPower)

Creates a new GammaPower distribution whose density function equals the product of two other GammaPower density functions

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

The first distribution
GammaPower b

The second distribution. Must have the same power parameter as a
Returns
Type Description
GammaPower

Result. May not be proper.

Implements