blog.distrib
Class Categorical

java.lang.Object
  blog.AbstractCondProbDistrib
      blog.distrib.Categorical

All Implemented Interfaces:

CondProbDistrib

public class Categorical
extends AbstractCondProbDistrib

Distribution over a finite set of possible values numbered 0, ..., k-1, parameterized by a vector of probabilities pi₀, ..., pi_k-1 that sum to one. The possible values can be the user-defined guaranteed objects of some type, or a finite prefix of the natural numbers. The probability vector can be specified when the distribution is constructed, or as an argument to the getProb and sampleVal methods (in the form of a column vector).

Field Summary

static int	LOG Value that can be bitwise or'ed with a flag argument to indicate that the weights are given as (natural) logs.
static int	NO_FLAGS Value for constructor's flag argument indicating that all flags are false.
static int	NORMALIZED Value that can be bitwise or'ed with a flag argument to indicate that the given weights are normalized (sum to 1).
static int	SORTED Value that can be bitwise or'ed with a flag argument to indicate that the weights are sorted in non-increasing order (largest first).

Constructor Summary

Categorical(double[] probs)
Creates a new Categorical distribution with the given probability vector.

Categorical(double[] weights, int flags)
Creates a new Categorical distribution with the given probability weights.

Categorical(int numValues)
Creates a new Categorical distribution representing the uniform distribution over the given number of values.

Categorical(java.util.List params)
Creates a new Categorical distribution from the given parameter list.

Method Summary

double	getLogProb(int index) Returns the log probability of the value with the given index under this distribution.
int	getNumValues() Returns the number of values to which this distribution explicitly assigns a probability.
double	getProb(int index) Returns the probability of the value with the given index under this distribution.
double	getProb(java.util.List args, java.lang.Object childValue) Returns the probability of the given child value conditioned on the given argument values.
int	sampleVal() Returns an index sampled from this distribution.
java.lang.Object	sampleVal(java.util.List args, Type childType) Returns a value sampled from the given child type according to this distribution.

Methods inherited from class blog.AbstractCondProbDistrib

getLogProb, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

NO_FLAGS

public static final int NO_FLAGS

Value for constructor's flag argument indicating that all flags are false.

See Also:

Constant Field Values

NORMALIZED

public static final int NORMALIZED

Value that can be bitwise or'ed with a flag argument to indicate that the given weights are normalized (sum to 1).

See Also:

Constant Field Values

LOG

public static final int LOG

Value that can be bitwise or'ed with a flag argument to indicate that the weights are given as (natural) logs.

See Also:

Constant Field Values

SORTED

public static final int SORTED

Value that can be bitwise or'ed with a flag argument to indicate that the weights are sorted in non-increasing order (largest first). This allows log weights to be normalized slightly faster (the code divides each weight by the largest one before exponentiating, to avoid underflow).

See Also:

Constant Field Values

Constructor Detail

Categorical

public Categorical(int numValues)

Creates a new Categorical distribution representing the uniform distribution over the given number of values.

Categorical

public Categorical(double[] probs)

Creates a new Categorical distribution with the given probability vector. The number of values is the length of this vector.

Categorical

public Categorical(double[] weights,
                   int flags)

Creates a new Categorical distribution with the given probability weights. The flags argument is treated as a bit vector indicating what assumptions can be made about the given weights. The possible flags are public static fields of the Categorical class.

Categorical

public Categorical(java.util.List params)

Creates a new Categorical distribution from the given parameter list. If the parameter list is empty, then the probability vector must be passed as an argument to this CPD. Otherwise, the parameter list should contain the probability vector as a sequence of Number objects.

Method Detail

getNumValues

public int getNumValues()

Returns the number of values to which this distribution explicitly assigns a probability.

Throws:

java.lang.IllegalStateException - if the probability vector was not specified when this distribution was constructed

getProb

public double getProb(int index)

Returns the probability of the value with the given index under this distribution. If the given index is greater than the length of this distribution's probability vector, then the return value is zero.

Throws:

java.lang.IllegalStateException - if the probability vector was not specified when this distribution was constructed

java.lang.IllegalArgumentException - if index is negative

getLogProb

public double getLogProb(int index)

Returns the log probability of the value with the given index under this distribution. If the given index is greater than the length of this distribution's probability vector, then the return value is Double.NEGATIVE_INFINITY.

Throws:

java.lang.IllegalStateException - if the probability vector was not specified when this distribution was constructed

java.lang.IllegalArgumentException - if index is negative

getProb

public double getProb(java.util.List args,
                      java.lang.Object childValue)

Returns the probability of the given child value conditioned on the given argument values. If this distribution was constructed with a probability vector, then no arguments are expected. Otherwise, there should be one argument, namely a column vector of probabilities.

Returns:

the probability associated with childValue's index, or 0 if childValue does not have an index or its index is beyond the end of the probability vector

Throws:

java.lang.IllegalArgumentException - if the probability vector was specified at construction and args is non-empty, or if the probability vector was not specified and args is empty

sampleVal

public int sampleVal()

Returns an index sampled from this distribution.

Throws:

java.lang.IllegalStateException - if the probability vector was not specified when this distribution was constructed

sampleVal

public java.lang.Object sampleVal(java.util.List args,
                                  Type childType)

Returns a value sampled from the given child type according to this distribution. If this distribution was constructed with a probability vector, then no arguments are expected. Otherwise, there should be one argument, namely a column vector of probabilities.

Returns:

a guaranteed object of the given type whose index is sampled according to this distribution, or Model.NULL if the index sampled is beyond the end of the guaranteed object list for the given type

Throws:

java.lang.IllegalArgumentException - if the probability vector was specified at construction and args is non-empty, or if the probability vector was not specified and args is empty