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

Remarks

The Poisson is often used as a distribution on counts. The formula for the distribution is p(x) = rate^x exp(-rate) / x! where rate is the rate parameter. This implementation uses a generalization called the Conway-Maxwell Poisson or "Com-Poisson", which has an extra precision parameter nu. The formula for the distribution is p(x) =propto rate^x / x!^nu. The Com-Poisson can represent a uniform distribution via (rate=1,nu=0) and a point mass via rate=0 or nu=infinity. This family is closed under multiplication, while the standard Poisson is not.

Constructors

Poisson(Poisson)

Copy constructor.

Declaration

public Poisson(Poisson that)

Parameters

Type	Name	Description
Poisson	that

Poisson(Double)

Creates a Poisson distribution with the given mean.

Declaration

public Poisson(double mean)

Parameters

Type	Name	Description
Double	mean

Poisson(Double, Double)

Create a Com-Poisson distribution with the given rate and precision.

Declaration

[Construction(new string[]{"Rate", "Precision"})]
public Poisson(double rate, double precision)

Parameters

Type	Name	Description
Double	rate
Double	precision

Fields

Precision

The precision parameter of the COM-Poisson distribution

Declaration

[DataMember]
public double Precision

Field Value

Type	Description
Double

Rate

The rate parameter of the COM-Poisson distribution, always >= 0.

Declaration

[DataMember]
public double Rate

Field Value

Type	Description
Double

Remarks

The natural parameter of the distribution is log(rate).
However, since rate remains >= 0 under multiplication, there is no harm in using rate as the parameter.

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 int Point { get; set; }

Property Value

Type	Description
Int32

Methods

Clone()

Clones this COM-Poisson.

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

FromMeanAndMeanLogFactorial(Double, Double)

Create a COM-Poisson distribution with the given sufficient statistics.

Declaration

public static Poisson FromMeanAndMeanLogFactorial(double mean, double meanLogFactorial)

Parameters

Type	Name	Description
Double	mean	E[x]
Double	meanLogFactorial	E[log(x!)]

Returns

Type	Description
Poisson	A new COM-Poisson distribution

Remarks

This routine implements maximum-likelihood estimation of a COM-Poisson distribution, as described by Thomas P. Minka, Galit Shmueli, Joseph B. Kadane, Sharad Borle, and Peter Boatwright, "Computing with the COM-Poisson distribution", CMU Tech Report 776. http://www.stat.cmu.edu/tr/tr776/tr776.html

GetAverageLog(Poisson)

Gets the expected logarithm of a COM-Poisson under this COM-Poisson.

Declaration

public double GetAverageLog(Poisson that)

Parameters

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

Gets the log of the integral of the product of this COM-Poisson with another COM-Poisson.

Declaration

public double GetLogAverageOf(Poisson that)

Parameters

Type	Name	Description
Poisson	that	The other COM-Poisson

Returns

Type	Description
Double

GetLogAverageOfPower(Poisson, Double)

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

Declaration

public double GetLogAverageOfPower(Poisson that, double power)

Parameters

Type	Name	Description
Poisson	that
Double	power

Returns

Type	Description
Double

GetLogNormalizer()

Gets the log normalizer of the distribution

Declaration

public double GetLogNormalizer()

Returns

Type	Description
Double

GetLogNormalizer(Double, Double)

Computes log(sum_{x=0..infinity} lambda^x / x!^nu)

Declaration

public static double GetLogNormalizer(double lambda, double nu)

Parameters

Type	Name	Description
Double	lambda	Rate.
Double	nu	Precision.

Returns

Type	Description
Double

GetLogPowerSum(Double, Double, Double)

Computes log(sum_{x=0..infinity} x^p lambda^x / x!^nu)

Declaration

public static double GetLogPowerSum(double lambda, double nu, double p)

Parameters

Type	Name	Description
Double	lambda	Rate.
Double	nu	Precision.
Double	p	Exponent.

Returns

Type	Description
Double

GetLogProb(Int32)

Evaluates the log of of the density function of this COM-Poisson at the given value

Declaration

public double GetLogProb(int value)

Parameters

Type	Name	Description
Int32	value	The value at which to calculate the density

Returns

Type	Description
Double	log p(x=value)

Remarks

The formula for the distribution is p(x) = rate^x exp(-rate) / x! when nu=1. In the general case, it is p(x) =propto rate^x / x!^nu. If the distribution is improper, the normalizer is omitted.

GetMean()

Gets the expected value E(x)

Declaration

public double GetMean()

Returns

Type	Description
Double	E(x)

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

GetMeanLogFactorial()

Computes (sum_{x=0..infinity} log(x!) Rate^x / x!^Precision) / (sum_{x=0..infinity} Rate^x / x!^Precision )

Declaration

public double GetMeanLogFactorial()

Returns

Type	Description
Double

GetNormalizer(Double, Double)

Computes sum_{x=0..infinity} lambda^x / x!^nu

Declaration

public static double GetNormalizer(double lambda, double nu)

Parameters

Type	Name	Description
Double	lambda	Rate.
Double	nu	Precision.

Returns

Type	Description
Double

GetSumLogFactorial(Double, Double)

Computes sum_{x=0..infinity} log(x!) lambda^x / x!^nu

Declaration

public static double GetSumLogFactorial(double lambda, double nu)

Parameters

Type	Name	Description
Double	lambda	Rate. Must be non-negative.
Double	nu	Precision. Must be non-negative.

Returns

Type	Description
Double

GetSumLogFactorial2(Double, Double)

Computes sum_{x=0..infinity} log(x!)^2 lambda^x / x!^nu

Declaration

public static double GetSumLogFactorial2(double lambda, double nu)

Parameters

Type	Name	Description
Double	lambda	Rate.
Double	nu	Precision.

Returns

Type	Description
Double

GetSumXLogFactorial(Double, Double)

Computes sum_{x=0..infinity} x log(x!) lambda^x / x!^nu

Declaration

public static double GetSumXLogFactorial(double lambda, double nu)

Parameters

Type	Name	Description
Double	lambda	Rate.
Double	nu	Precision.

Returns

Type	Description
Double

GetVariance()

Gets the variance

Declaration

public double GetVariance()

Returns

Type	Description
Double	Variance

IsProper()

Asks whether this instance is proper or not. A COM-Poisson distribution is proper if Rate >= 0 and (Precision > 0 or (Precision == 0 and Rate < 1)).

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)

Returns the maximum difference between the parameters of this COM-Poisson and another COM-Poisson

Declaration

public double MaxDiff(object that)

Parameters

Type	Name	Description
Object	that	The other COM-Poisson

Returns

Type	Description
Double	The maximum difference

PointMass(Int32)

Creates a Com-Poisson distribution which only allows one value.

Declaration

[Construction(new string[]{"Point"}, UseWhen = "IsPointMass")]
public static Poisson PointMass(int value)

Parameters

Type	Name	Description
Int32	value

Returns

Type	Description
Poisson

Sample()

Samples from a Poisson distribution

Declaration

public int Sample()

Returns

Type	Description
Int32

Sample(Double)

Samples from a Poisson distribution with given mean

Declaration

public static int Sample(double mean)

Parameters

Type	Name	Description
Double	mean	Must be >= 0

Returns

Type	Description
Int32	An integer in [0,infinity)

Sample(Double, Double)

Samples from a COM-Poisson distribution

Declaration

public static int Sample(double rate, double precision)

Parameters

Type	Name	Description
Double	rate	Rate.
Double	precision	Precision.

Returns

Type	Description
Int32

Sample(Int32)

Sample from a Poisson - use Sample() instead

Declaration

public int Sample(int result)

Parameters

Type	Name	Description
Int32	result

Returns

Type	Description
Int32

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

SetTo(Poisson)

Sets this COM-Poisson instance to have the parameter values of another COM-Poisson instance

Declaration

public void SetTo(Poisson value)

Parameters

Type	Name	Description
Poisson	value	The other COM-Poisson

SetToPower(Poisson, Double)

Sets the parameters to represent the power of a COM-Poisson to some exponent.

Declaration

public void SetToPower(Poisson dist, double exponent)

Parameters

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

SetToProduct(Poisson, Poisson)

Sets the parameters to represent the product of two COM-Poissons.

Declaration

public void SetToProduct(Poisson a, Poisson b)

Parameters

Type	Name	Description
Poisson	a	The first COM-Poisson
Poisson	b	The second COM-Poisson

SetToRatio(Poisson, Poisson, Boolean)

Sets the parameters to represent the ratio of two COM-Poisson distributions

Declaration

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

Parameters

Type	Name	Description
Poisson	numerator	The numerator distribution
Poisson	denominator	The denominator distribution
Boolean	forceProper	If true, the result has precision >= 0 and rate <= 1

Remarks

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

SetToSum(Double, Poisson, Double, Poisson)

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

Declaration

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

Parameters

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

SetToUniform()

Sets this COM-Poisson 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()

Instantiates a uniform Com-Poisson distribution

Declaration

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

Returns

Type	Description
Poisson	A new uniform Com-Poisson distribution

Operators

Division(Poisson, Poisson)

Creates a new Poisson which is the ratio of two other COM-Poissons

Declaration

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

Parameters

Type	Name	Description
Poisson	numerator	The numerator distribution
Poisson	denominator	The denominator distribution

Returns

Type	Description
Poisson	Result

Equality(Poisson, Poisson)

Equals operator

Declaration

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

Parameters

Type	Name	Description
Poisson	a
Poisson	b

Returns

Type	Description
Boolean

ExclusiveOr(Poisson, Double)

Raises a COM-Poisson to a power.

Declaration

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

Parameters

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

Returns

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

Inequality(Poisson, Poisson)

Not equals operator

Declaration

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

Parameters

Type	Name	Description
Poisson	a
Poisson	b

Returns

Type	Description
Boolean

Multiply(Poisson, Poisson)

Creates a new COM-Poisson which is the product of two other COM-Poissons

Declaration

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

Parameters

Type	Name	Description
Poisson	a	The first COM-Poisson
Poisson	b	The second COM-Poisson

Returns

Type	Description
Poisson	Result

Implements

IDistribution<T>

IDistribution

System.ICloneable

Diffable

SettableToUniform

HasPoint<T>

CanGetLogProb<T>

SettableTo<T>

SettableToProduct<T>

SettableToProduct<T, U>

SettableToRatio<T>

SettableToRatio<T, U>

SettableToPower<T>

SettableToWeightedSum<T>

CanGetLogAverageOf<T>

CanGetLogAverageOfPower<T>

CanGetAverageLog<T>

Sampleable<T>

CanGetMean<MeanType>

CanGetVariance<VarType>

CanGetMeanAndVarianceOut<MeanType, VarType>

CanSetMeanAndVariance<MeanType, VarType>