com.cra.bnet.engine
Class Cpt

java.lang.Object
  |
  +--com.cra.bnet.engine.Potential
        |
        +--com.cra.bnet.engine.Cpt
All Implemented Interfaces:
Cpd

public class Cpt
extends Potential
implements Cpd

A conditional probability table (CPT) for a discrete node in a Bayesian network.

The CPT of a root node specifies the probability that the node will be in a particular state based on prior information. The CPT of a child node specifies the probability based on the state of each of its parents.

The CPT for a root node specifies the probability of each state of the node. For example, the CPT for a boolean node Rain with no parents specifies two probabilities:

 P(Rain=true)
 P(Rain=false)
 
The CPT for a boolean child node WetGrass with boolean parents Rain and Sprinklers specifies eight probabilities, one for each possible combination of states:
 P(WetGrass=true  | Rain=true,  Sprinklers=true)
 P(WetGrass=false | Rain=true,  Sprinklers=true)
 P(WetGrass=true  | Rain=true,  Sprinklers=false)
 P(WetGrass=false | Rain=true,  Sprinklers=false)
 P(WetGrass=true  | Rain=false, Sprinklers=true)
 P(WetGrass=false | Rain=false, Sprinklers=true)
 P(WetGrass=true  | Rain=false, Sprinklers=false)
 P(WetGrass=false | Rain=false, Sprinklers=false)
 

There are three ways to provide this class an index to a specific CPT entry:

  1. int nodeIndex, int[] parentIndices (preferred)
  2. int[] index
  3. int index

The first indexing method is preferred; the other two are inherited from Potential. The indices are used to obtain a CPT entry from the get method and set a CPT entry using the set method.

The int nodeIndex specifies the integer index of the discrete node's state and the int[] parentIndices specifies the integer index of each parent's state.

Important: The parents in this int[] must be in the same order as returned by the Node.getParents method. For example, each entry in the CPT for node WetGrass above would be accessed as follows:

 DiscreteNode wetGrass = ...;
 Cpt cpt = wetGrass.getCpt();
 cpt.get(0, new int[] {0, 0});
 cpt.get(1, new int[] {0, 0});
 cpt.get(0, new int[] {0, 1});
 cpt.get(1, new int[] {0, 1});
 cpt.get(0, new int[] {1, 0});
 cpt.get(1, new int[] {1, 0});
 cpt.get(0, new int[] {1, 1});
 cpt.get(1, new int[] {1, 1});
 

For a root node, the EMPTY_PARENT_INDICES field should be used. For example, the entries in the CPT for the Rain node above would be accessed as follows:

 DiscreteNode rain = ...;
 Cpt cpt = rain.getCpt();
 cpt.get(0, Cpt.EMPTY_PARENT_INDICES);
 cpt.get(1, Cpt.EMPTY_PARENT_INDICES);
 

The ParentIndices class can also be useful for populating the int[] for CPT indexing. See ParentIndices for more details.

The getParentIndices() method returns an iterator over all possible parent configurations that can also be very useful for accessing CPT entries.

For more information and instructions on getting and setting CPTs, please see the BNet.EngineKit Developer's Guide.


Field Summary
static int[] EMPTY_PARENT_INDICES
          A zero-length array for use when getting or setting the CPT entries of a root node.
 
Fields inherited from class com.cra.bnet.engine.Potential
nodes, table, vbn
 
Method Summary
 int convertToIndex(int nodeIndex, int[] parentIndices)
          Converts the specific node index and parent indices into a single index that can be used with the get(int) and set(int, double) methods.
 int convertToNodeAndParentIndices(int index, int[] parentIndices)
          Converts the specified single CPT array index into the corresponding node index and parent indices.
 double get(int nodeIndex, int[] parentIndices)
          Returns the conditional probability that this cpt's node being is the specified state, given that its parents are in the specified states.
 DiscreteNode getNode()
          Returns this cpt's node.
 Iterator getParentIndices()
          Returns an iterator over all possible configurations of this cpt's node's parents.
 boolean isNormalized(int significantDigits)
          Returns true if all rows in this CPT are normalized using the specified number of significant digits.
 boolean isNormalized(int[] parentIndices, int significantDigits)
          Returns true if the row specified by the parent indices is normalized using the specified number of significant digits.
 void normalize(int[] parentIndices)
          Normalizes the row specified by the parent indices so it will sum to one.
 void normalize(int[] parentIndices, int significantDigits)
          Normalizes the row specified by the parent indices so it will sum to one using the specified number of significant digits.
 void normalizeAll()
          Normalizes each row in the entire conditional probability table so that each row will sum to one.
 void normalizeAll(int significantDigits)
          Normalizes each row in the entire conditional probability table so each row will sum to one using the specified number of significant digits.
 void normalizeAllHelper()
          Helper method that actually normalizes the entire conditional probability table without posting an undoable edit.
 void randomizeAll()
          Sets each row in this CPT to normalized, random values that sum to one.
 void reorderParent(DiscreteNode parent, int index)
          Called by BN.Node.reorderParent to notify its cpt that a parent has been reordered.
 boolean set(int nodeIndex, int[] parentIndices, double value)
          Sets the conditional probability that this cpt's node is in the specified state (given that its parents are in the specified states) to the specified value.
 int size()
          Returns the size of this conditional probability table.
 String toString()
          Returns a String representation of this conditional probability table.
 void uniform(int[] parentIndices)
          Sets the row specified by the parent indices to a uniform probability distribution.
 void uniformAll()
          Sets each row in the entire conditional probability table to uniform distributions.
 
Methods inherited from class com.cra.bnet.engine.Potential
add, divideBy, dump, equals, get, get, getMappings, getNodes, hashCode, marginalize, multiply, normalize, set, set, setMappings, toArray
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

EMPTY_PARENT_INDICES

public static final int[] EMPTY_PARENT_INDICES
A zero-length array for use when getting or setting the CPT entries of a root node.

Method Detail

convertToIndex

public int convertToIndex(int nodeIndex,
                          int[] parentIndices)
Converts the specific node index and parent indices into a single index that can be used with the get(int) and set(int, double) methods. The specified parent indices array must not be null; for a root, it should be EMPTY_PARENT_INDICES.

Parameters:
nodeIndex - node index.
parentIndices - parent indices.
Returns:
the single integer index of the CPT array from the specified node index and parent indices.
Throws:
IllegalArgumentException - if the nodeIndex is invalid.
NullPointerException - if parentIndices is null.

convertToNodeAndParentIndices

public int convertToNodeAndParentIndices(int index,
                                         int[] parentIndices)
Converts the specified single CPT array index into the corresponding node index and parent indices.

The node index is returned while the parent indices are copied into the specified array. The specified parent indices array must be of length equal to the number of parents of this cpt's node.

Parameters:
index - single integer index to convert.
parentIndices - array of parent indices that will be filled.
Returns:
node index.\
Throws:
IllegalArgumentException - if the index is invalid, the length of the parentIndices array is not the same as the number of parents the node has.
NullPointerException - if parentIndices is null.

get

public double get(int nodeIndex,
                  int[] parentIndices)
Returns the conditional probability that this cpt's node being is the specified state, given that its parents are in the specified states. If this cpt's node is a root node, the specified array should be EMPTY_PARENT_INDICES.

Parameters:
nodeIndex - index of the node's state.
parentIndices - indices of states of the parent nodes.
Returns:
the conditional probability that this cpt's node is in the specified state given that its parents are in the specified states.

set

public boolean set(int nodeIndex,
                   int[] parentIndices,
                   double value)
Sets the conditional probability that this cpt's node is in the specified state (given that its parents are in the specified states) to the specified value. If this cpt's node is a root node, the specified array should be EMPTY_PARENT_INDICES.

Returns false if the value is a negative number or if the attempt to set the value to zero causes that row of the CPT to contain all zero values. In this case, this method also sends a BnetError object to the ErrorNotifier.

Parameters:
nodeIndex - index of the node's state.
parentIndices - index of parent states.
value - new conditional probability value.
Returns:
true if the conditional probability was set, and false if it was not.

size

public int size()
Returns the size of this conditional probability table. The size is the number of rows, or possible parent configurations.

Returns:
the size of this conditional probability table.

getNode

public DiscreteNode getNode()
Returns this cpt's node.

Returns:
this cpt's node.

getParentIndices

public Iterator getParentIndices()
Returns an iterator over all possible configurations of this cpt's node's parents. Elements returned by the iterator are guaranteed to be of type int[]. The parent indices are returned in the order determined by Node.getParents.

Note that the same instance of int[] is returned by each call to Iterator.next, so its elements are only valid for one call to Iterator.next.

Returns:
an iterator over all possible configurations of this cpt's node's parents.

normalize

public void normalize(int[] parentIndices)
Normalizes the row specified by the parent indices so it will sum to one.

Parameters:
parentIndices - parent indices.

normalize

public void normalize(int[] parentIndices,
                      int significantDigits)
Normalizes the row specified by the parent indices so it will sum to one using the specified number of significant digits.

Parameters:
parentIndices - parent indices.
significantDigits - number of significant digits.

normalizeAll

public void normalizeAll()
Normalizes each row in the entire conditional probability table so that each row will sum to one.


normalizeAllHelper

public void normalizeAllHelper()
Helper method that actually normalizes the entire conditional probability table without posting an undoable edit.


normalizeAll

public void normalizeAll(int significantDigits)
Normalizes each row in the entire conditional probability table so each row will sum to one using the specified number of significant digits.

Parameters:
significantDigits - number of significant digits.

isNormalized

public boolean isNormalized(int significantDigits)
Returns true if all rows in this CPT are normalized using the specified number of significant digits.

Parameters:
significantDigits - number of significant digits.
Returns:
true if this CPT is normalized using the specified number of significant digits, and false if not.

isNormalized

public boolean isNormalized(int[] parentIndices,
                            int significantDigits)
Returns true if the row specified by the parent indices is normalized using the specified number of significant digits.

Parameters:
parentIndices - parent indices.
significantDigits - number of significant digits.
Returns:
true if the row specified by the parent indices is normalized using the specified number of significant digits, and false if not.

uniform

public void uniform(int[] parentIndices)
Sets the row specified by the parent indices to a uniform probability distribution.

Parameters:
parentIndices - parent indices.

uniformAll

public void uniformAll()
Sets each row in the entire conditional probability table to uniform distributions.


randomizeAll

public void randomizeAll()
Sets each row in this CPT to normalized, random values that sum to one.


toString

public String toString()
Returns a String representation of this conditional probability table.

Overrides:
toString in class Object
Returns:
a String representation of this conditional probability table.

reorderParent

public void reorderParent(DiscreteNode parent,
                          int index)
Called by BN.Node.reorderParent to notify its cpt that a parent has been reordered. Clients should never call this method.

Specified by:
reorderParent in interface Cpd
Parameters:
parent - parent that was reordered.
index - new index of parent.