aima.core.probability

Interface CategoricalDistribution

All Superinterfaces:

ProbabilityDistribution, ProbabilityMass

All Known Implementing Classes:

ProbabilityTable

public interface CategoricalDistribution
extends ProbabilityMass

Artificial Intelligence A Modern Approach (3rd Edition): page 487.

A probability distribution for discrete random variables with a finite set of values.
Note: This definition corresponds to that given in AIMA3e pg. 487, for a Probability Distribution.

Author:

Ciaran O'Reilly

See Also:

Probability Distribution

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	CategoricalDistribution.Iterator Interface to be implemented by an object/algorithm that wishes to iterate over the possible assignments for the random variables comprising this categorical distribution.

Method Summary

Modifier and Type	Method and Description
CategoricalDistribution	divideBy(CategoricalDistribution divisor) Divide the dividend (this) CategoricalDistribution by the divisor to create a new CategoricalDistribution representing the quotient.
int	getIndex(java.lang.Object... values) Retrieve the index into the CategoricalDistribution for the provided set of values for the random variables comprising the Distribution.
double	getSum()
double[]	getValues() Note: Do not modify the double[] returned by this method directly.
void	iterateOver(CategoricalDistribution.Iterator cdi) Iterate over all the possible value assignments for the Random Variables comprising this CategoricalDistribution.
void	iterateOver(CategoricalDistribution.Iterator cdi, AssignmentProposition... fixedValues) Iterate over all possible values assignments for the Random Variables comprising this CategoricalDistribution that are not in the fixed set of values.
CategoricalDistribution	marginal(RandomVariable... vars) Get the marginal probability for the provided variables from this Distribution creating a new Distribution of the remaining variables with their values updated with the summed out random variables. see: AIMA3e page 492.
CategoricalDistribution	multiplyBy(CategoricalDistribution multiplier) Multiplication of this Distribution by a given multiplier, creating a new Distribution representing the product of the two.
CategoricalDistribution	multiplyByPOS(CategoricalDistribution multiplier, RandomVariable... prodVarOrder) Multiplication - Product Order Specified (POS).
CategoricalDistribution	normalize() Normalize the values comprising this distribution.
void	setValue(int idx, double value) Set the value at a specified index within the distribution.

Methods inherited from interface aima.core.probability.ProbabilityDistribution

contains, getFor, getValue, getValue

Method Detail

getValues

double[] getValues()

Note: Do not modify the double[] returned by this method directly. Instead use setValue() as this method is intended to be for read only purposes.

Returns:

the double[] used to represent the CategoricalDistribution.

See Also:

setValue(int, double)

setValue

void setValue(int idx,
              double value)

Set the value at a specified index within the distribution.

Parameters:

idx -

value -

getSum

double getSum()

Returns:

the summation of all of the elements within the Distribution.

normalize

CategoricalDistribution normalize()

Normalize the values comprising this distribution.

Returns:

this instance with its values normalized.

getIndex

int getIndex(java.lang.Object... values)

Retrieve the index into the CategoricalDistribution for the provided set of values for the random variables comprising the Distribution.

Parameters:

values - an ordered set of values for the random variables comprising the Distribution (Note: the order must match the order of the random variables describing the distribution)

Returns:

the index within the Distribution for the values specified.

See Also:

getValues(), ProbabilityDistribution.getFor()

marginal

CategoricalDistribution marginal(RandomVariable... vars)

Get the marginal probability for the provided variables from this Distribution creating a new Distribution of the remaining variables with their values updated with the summed out random variables.

see: AIMA3e page 492.

Parameters:

vars - the random variables to marginalize/sum out.

Returns:

a new Distribution containing any remaining random variables not summed out and a new set of values updated with the summed out values.

divideBy

CategoricalDistribution divideBy(CategoricalDistribution divisor)

Divide the dividend (this) CategoricalDistribution by the divisor to create a new CategoricalDistribution representing the quotient. The variables comprising the divisor distribution must be a subset of the dividend. However, ordering of variables does not matter as the quotient contains the same variables as the dividend and the internal implementation logic should handle iterating through the two distributions correctly, irrespective of the order of their variables.

Parameters:

divisor -

Returns:

a new Distribution representing the quotient of the dividend (this) divided by the divisor.

Throws:

java.lang.IllegalArgumentException - if the variables of the divisor distribution are not a subset of the dividend.

multiplyBy

CategoricalDistribution multiplyBy(CategoricalDistribution multiplier)

Multiplication of this Distribution by a given multiplier, creating a new Distribution representing the product of the two. Note: Is equivalent to pointwise product calculation on factors.

see: AIMA3e Figure 14.10 page 527.

Note: Default Distribution multiplication is not commutative. The reason is because the order of the variables comprising a Distribution dictate the ordering of the values for that distribution. For example (the General case of Baye's rule, AIMA3e pg. 496), using this API method:

P(Y | X) = (P(X | Y)P(Y))/P(X)

is NOT true, due to multiplication of distributions not being commutative. However:

P(Y | X) = (P(Y)P(X | Y))/P(X)

is true, using this API.

The default order of the variable of the Distribution returned is the order of the variables as they are seen, as read from the left to right term, for e.g.:

P(Y)P(X | Y)

would give a Distribution of the following form:
Y, X

i.e. an ordered union of the variables from the two distributions.
To override the default order of the product use multiplyByPOS().

Parameters:

multiplier -

Returns:

a new Distribution representing the product of this and the passed in multiplier. The order of the variables comprising the product distribution is the ordered union of the left term (this) and the right term (multiplier).

See Also:

multiplyByPOS(CategoricalDistribution, RandomVariable...)

multiplyByPOS

CategoricalDistribution multiplyByPOS(CategoricalDistribution multiplier,
                                      RandomVariable... prodVarOrder)

Multiplication - Product Order Specified (POS). Note: Is equivalent to pointwise product calculation.

see: AIMA3e Figure 14.10 page 527.

Multiplication of this Distribution by a given multiplier, creating a new Distribution representing the product of the two. The order of the variables comprising the product will match those specified. For example (the General case of Baye's rule, AIMA3e pg. 496), using this API method:

P(Y | X) = (P(X | Y)P(Y), [Y, X])/P(X)

is true when the correct product order is specified.

Parameters:

multiplier -

prodVarOrder - the order the variables comprising the product are to be in.

Returns:

a new Distribution representing the product of this and the passed in multiplier. The order of the variables comprising the product distribution is the order specified.

See Also:

multiplyBy(CategoricalDistribution)

iterateOver

void iterateOver(CategoricalDistribution.Iterator cdi)

Iterate over all the possible value assignments for the Random Variables comprising this CategoricalDistribution.

Parameters:

cdi - the CategoricalDistribution Iterator to iterate.

iterateOver

void iterateOver(CategoricalDistribution.Iterator cdi,
                 AssignmentProposition... fixedValues)

Iterate over all possible values assignments for the Random Variables comprising this CategoricalDistribution that are not in the fixed set of values. This allows you to iterate over a subset of possible combinations.

Parameters:

cdi - the CategoricalDistribution Iterator to iterate

fixedValues - Fixed values for a subset of the Random Variables comprising this CategoricalDistribution.