com.cra.bnet.engine
Class DiscreteNode

java.lang.Object
  |
  +--com.cra.bnet.engine.Node
        |
        +--com.cra.bnet.engine.DiscreteNode

public class DiscreteNode
extends Node

A discrete node in a Bayesian network.

A discrete node models a discrete variable in a Bayesian network. Each discrete node has states and a conditional probability table that represents the probability that the node is in a particular state given the states of its parent nodes.

States: Since a discrete node represents a discrete random variable, it has a finite number of states. The getStates method returns a list of the states in their correct order. The returned list is fully modifiable; clients can add, remove, rename, and reorder states using the returned list. All elements of the returned list must be of type String.

Conditional probabilities:The discrete node's CPT is available from the getCpt method. In this version of BNet.EngineKit, the conditional probability distribution for a discrete node is available only as a CPT. See the Cpt class for details on using a CPT.

At run-time, evidence can be posted and retracted, and beliefs calculated for the node.

Evidence:At run-time, evidence can be posted to indicate the actual state of the node. Use the setEvidence method to associate new evidence with a node, the retractEvidence method to remove evidence from a node, and the getEvidence method to return a node's current evidence.

Beliefs:A belief is the probability that a node is in a particular state when evidence is posted to other nodes in the Bayesian network. Use the getBelief method to return the belief that the node is in a specific state or the getBeliefs method to return beliefs for a the node's states.

Note that calling either of these methods to get beliefs may perform inferencing if beliefs need to be updated. For example, if evidence changed or the Bayesian network was modified since the last time beliefs were updated, calling either method will update the beliefs. You can also configure a Bayesian network's BeliefUpdater to automatically update beliefs. See BayesianNetwork.getBeliefUpdater() and BeliefUpdater for more details.

New instances of this class can only be obtained from the BayesianNetwork.addDiscreteNode(String) and BayesianNetwork.addDiscreteNode(String, List) methods. Use the BayesianNetwork.getDiscreteNode(String) or BayesianNetwork.discreteNodeSet() methods to get discrete node instances from a Bayesian network.


Method Summary
 void addStateListener(StateListener listener)
          Registers the specified state listener to receive events when this discrete node's states change.
 void fireAllEntriesChanged(CptEvent event)
          Notifies cpt listeners and the belief updater that this node's entire cpt changed.
protected  void fireBeliefEvent(double[] newBeliefs, boolean valid)
          Notifies belief listeners that this node's beliefs changed.
protected  void fireEntryChanged(CptEvent event)
          Notifies cpt listeners that this node's cpt changed.
protected  void fireEvidencePosted(double[] evidence)
          Notifies evidence listeners and the belief updater that evidence was posted to this node.
protected  void fireEvidenceRetracted(double[] evidence)
          Notifies evidence listeners and the belief updater that evidence was retracted from this node.
protected  void fireInconsistentEvidenceRetracted(double[] evidence)
          Notifies evidence listeners that inconsistent evidence was retracted from this node.
protected  void fireStateAdded(String stateName, int index)
          Notifies node listeners and the belief updater that a new state was added to this node.
protected  void fireStateNameChanged(String oldName, String newName, int index)
          Notifies node listeners and the belief updater that the name of one of this node's states was changed.
protected  void fireStateRemoved(String stateName, int index)
          Notifies node listeners and the belief updater that a state was removed from this node.
protected  void fireStateReordered(String stateName, int index)
          Notifies node listeners that one of this node's states was reordered.
 double getBelief(String stateName)
          Returns the belief that this discrete node is in the specified state.
 double[] getBeliefs()
          Returns all of this discrete node's updated beliefs.
 Cpt getCpt()
          Returns this node's conditional probability table.
 double[] getEvidence()
          Returns the evidence posted to this discrete node.
 double getEvidence(String state)
          Returns the evidence posted to the specified state of this discrete node.
 double getLastBelief(String state)
          Returns this discrete node's last belief for the specified state - the one most recently sent to all belief listeners registered with this node.
 double[] getLastBeliefs()
          Returns this discrete node's last beliefs, those that were most recently sent to all belief listeners registered with this node.
 StateList getStates()
          Returns a fully modifiable list of this discrete node's states.
 void removeEvidence()
          Retracts all the evidence posted to this discrete node.
 void removeStateListener(StateListener listener)
          Unregisters the specified state listener so it will no longer receive events when this discrete node's states change.
 void setEvidence(double[] evidence)
          Posts the specified evidence to this discrete node.
 void setEvidence(String state, double evidence)
          Posts the specified evidence to the specified state.
 String toString()
          Returns a String representation of this discrete node.
 
Methods inherited from class com.cra.bnet.engine.Node
addBeliefListener, addCptListener, addEvidenceListener, addNodeListener, addPropertyChangeListener, equals, fireDescriptionChanged, fireLocationChanged, fireNameChanged, fireParentReordered, getBayesianNetwork, getCpd, getDescription, getLocation, getName, getParents, getProperties, hashCode, removeBeliefListener, removeCptListener, removeEvidenceListener, removeNodeListener, removePropertyChangeListener, reorderParent, setCpd, setDescription, setLocation, setLocationHelper, setName
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

getCpt

public Cpt getCpt()
Returns this node's conditional probability table.

Returns:
this node's conditional probability table.

getStates

public StateList getStates()
Returns a fully modifiable list of this discrete node's states. The list of states must contain only String elements, and must have at least two states.

Returns:
a fully modifiable list of this discrete node's states.

addStateListener

public void addStateListener(StateListener listener)
Registers the specified state listener to receive events when this discrete node's states change.

Parameters:
listener - state listener.
Throws:
IllegalArgumentException - if listener is null.

removeStateListener

public void removeStateListener(StateListener listener)
Unregisters the specified state listener so it will no longer receive events when this discrete node's states change.

Parameters:
listener - state listener to remove.

fireBeliefEvent

protected void fireBeliefEvent(double[] newBeliefs,
                               boolean valid)
Notifies belief listeners that this node's beliefs changed.

Parameters:
newBeliefs - new beliefs.
valid - true if new beliefs are valid and false if they are not.

fireEvidencePosted

protected void fireEvidencePosted(double[] evidence)
Notifies evidence listeners and the belief updater that evidence was posted to this node.

Parameters:
evidence - evidence posted to this node.

fireEvidenceRetracted

protected void fireEvidenceRetracted(double[] evidence)
Notifies evidence listeners and the belief updater that evidence was retracted from this node.

Parameters:
evidence - evidence retracted from the node.

fireInconsistentEvidenceRetracted

protected void fireInconsistentEvidenceRetracted(double[] evidence)
Notifies evidence listeners that inconsistent evidence was retracted from this node.

Inconsistent evidence is evidence that a node's CPT indicates makes impossible.

Parameters:
evidence - evidence retracted from this node.

fireStateAdded

protected void fireStateAdded(String stateName,
                              int index)
Notifies node listeners and the belief updater that a new state was added to this node.

Parameters:
stateName - name of the new state.
index - index of the new state.

fireStateRemoved

protected void fireStateRemoved(String stateName,
                                int index)
Notifies node listeners and the belief updater that a state was removed from this node.

Parameters:
stateName - name of the removed state.
index - index of the removed state.

fireStateNameChanged

protected void fireStateNameChanged(String oldName,
                                    String newName,
                                    int index)
Notifies node listeners and the belief updater that the name of one of this node's states was changed.

Parameters:
oldName - state's old name.
newName - state's new name.
index - index of the state.

fireStateReordered

protected void fireStateReordered(String stateName,
                                  int index)
Notifies node listeners that one of this node's states was reordered.

Parameters:
stateName - name of the reordered state.
index - old index of the state.

fireAllEntriesChanged

public void fireAllEntriesChanged(CptEvent event)
Notifies cpt listeners and the belief updater that this node's entire cpt changed.

Parameters:
event - cpt event.
Throws:
IllegalArgumentException - if event is null.

fireEntryChanged

protected void fireEntryChanged(CptEvent event)
Notifies cpt listeners that this node's cpt changed.

Parameters:
event - cpt event.
Throws:
IllegalArgumentException - if event is null.

getBelief

public double getBelief(String stateName)
Returns the belief that this discrete node is in the specified state.

This method returns updated beliefs. The first time that this method (or getBeliefs) is called on the network after a change occurred, the inference engine will update all beliefs. This ensures that all beliefs are valid.

If inconsistent evidence (that is, evidence that the node's CPT indicates is impossible) was posted to the network, this method will return a value of Double.NaN for that belief. This method will also return Double.NaN if any of the rows in this node's CPT contain all zero values.

Parameters:
stateName - state name.
Returns:
the belief of this discrete node being in the specified state.
Throws:
IllegalArgumentException - stateName is null or if this node does not contain the specifed state.

getBeliefs

public double[] getBeliefs()
Returns all of this discrete node's updated beliefs. The beliefs are in the same order as this discrete node's states. Clients should not modify the returned array.

The first time that this method (or getBelief) is called on the network after a change occurred, the inference engine will update all beliefs. This ensures that all beliefs are valid.

If inconsistent evidence (that is, evidence that the node's CPT indicates is impossible) was posted to the network, this method will return a value of Double.NaN for that belief. This method will also return Double.NaN if any of the rows in this node's CPT contain all zero values.

Returns:
this discrete node's beliefs.

getLastBeliefs

public double[] getLastBeliefs()
Returns this discrete node's last beliefs, those that were most recently sent to all belief listeners registered with this node.

In contrast to the getBeliefs method, this method never causes beliefs to be updated, and can safely be called by any client not wanting beliefs to be updated.

If beliefs do not need to be updated (that is, no modifications that affect beliefs have been made since beliefs were last updated), then this method returns the same beliefs as the getBeliefs method. If beliefs do need to be updated (that is, a modification that affects beliefs was made since beliefs were last udpated) then this method will return an array consisting of all Double.NaN values to represent invalid beliefs.

Returns:
this discrete node's most recent beliefs, valid or invalid.

getLastBelief

public double getLastBelief(String state)
Returns this discrete node's last belief for the specified state - the one most recently sent to all belief listeners registered with this node.

In contrast to the getBelief method, this method never causes beliefs to be updated, and can be safely called by any client not wanting beliefs to be updated.

If beliefs do not need to be updated (that is, no modifications that affect beliefs have been made since beliefs were last updated), then this method returns the same belief as the getBelief method. If beliefs do need to be updated (that is, a modification that affects beliefs was made since beliefs were last udpated) then this method will return Double.NaN to represent an invalid belief.

This method returns the same belief as was most recently sent to all belief listeners registered with this node.

Parameters:
state - state whose last belief is to be returned.
Returns:
this discrete node's last belief for the specified state.
Throws:
IllegalArgumentException - if the node does not have the specified state.

getEvidence

public double[] getEvidence()
Returns the evidence posted to this discrete node.

Returns:
the evidence posted to this discrete node.

getEvidence

public double getEvidence(String state)
Returns the evidence posted to the specified state of this discrete node.

Parameters:
state - state whose evidence is to be returned.
Returns:
the evidence posted to the specified state or -1.0 if this node does not contain the specified state.

setEvidence

public void setEvidence(double[] evidence)
Posts the specified evidence to this discrete node. If the specified array is null or contains all zeros, this method does nothing and returns immediately. If the specified evidence contains all ones, this method calls the retractEvidence method and then returns.

To post hard evidence, use BayesianNetworks.getHardEvidence method as the evidence parameter.

Parameters:
evidence - evidence to post.

setEvidence

public void setEvidence(String state,
                        double evidence)
Posts the specified evidence to the specified state.

This method posts the existing evidence to this node with the evidence for the specfied state set to the specified value.

Parameters:
state - state to get new evidence.
evidence - new evidence.

removeEvidence

public void removeEvidence()
Retracts all the evidence posted to this discrete node. When evidence is retracted from a node, the value for each state of the node is set to 1.0.


toString

public String toString()
Returns a String representation of this discrete node.

Overrides:
toString in class Node
Returns:
a String representation of this discrete node.