com.cra.bnet.engine
Class BayesianNetwork

java.lang.Object
  |
  +--com.cra.bnet.engine.BayesianNetwork

public class BayesianNetwork
extends Object

A Bayesian network (also known as a belief network or Bayesian belief network).

A Bayesian network consists of nodes, edges, and conditional probability distributions. The nodes and edges form a directed, acyclic graph. Nodes represent random variables and edges represent causal relationships between those variables. Each node has a conditional probability distribution that quantifies the probabilistic effects of its parents on it.

Note: This version of BNet.EngineKit supports only discrete random variables and conditional probability tables.

A Bayesian network represents the joint probability distribution of all of its nodes. The primary use of a Bayesian network is to calculate beliefs. A belief is the probability that a node is in a particular state, given evidence that other nodes are in particular states. A belief is represented mathematically as P(X=x|e). This class uses an external inference engine to calculate beliefs.

This class can be used in two different ways:

The interactive way of using this class is really an extension of the programmatic way, in that you create and edit the network in the same way, but also receive events and update beliefs automatically. Information and instructions for both uses of this class are provided in the BNet.EngineKit Developer's Guide.

Important: Do not modify the Bayesian network in any of the event listener methods. These methods are meant for functions such as record-keeping, repaint requesting, or modifying other objects. For example, if you get an invalid belief event in a belief listener method, do not call DiscreteNode.getBelief(s)! Instead, configure the belief updater to automatically update beliefs, or some other client should call getBelief(s) or BeliefUpdater.updateAllBeliefs AFTER the listener method returns.

The following code shows how to build a very simple Bayesian network, with a parent node, Temperature (with three states), connected to a child node, WearCoat (with true and false states):

 BayesianNetwork network = new BayesianNetwork();
 List states = Arrays.asList(new String[] {"high", "medium", "low"});
 DiscreteNode temperature = network.addDiscreteNode("Temperature", states);
 DiscreteNode wearCoat = network.addDiscreteNode("WearCoat");
 network.addEdge(temperature, wearCoat);
 


Nested Class Summary
 class BayesianNetwork.AddEdgeEdit
          Undoable edit for adding an edge.
 class BayesianNetwork.AddNodeEdit
          Undoable edit for adding a node.
 class BayesianNetwork.AddStateEdit
          Undoable edit for adding a state.
 class BayesianNetwork.ChangeCptEntryEdit
          Undoable edit for changing a cpt entry.
 class BayesianNetwork.ChangeLocationEdit
          Undoable edit for changing a node's location.
 class BayesianNetwork.ChangeNodeDescriptionEdit
          Undoable edit for changing a node's description.
 class BayesianNetwork.ClearEvidenceEdit
          Undoable edit for removing all evidence.
 class BayesianNetwork.CompoundChangeCptEntryEdit
          Undoable edit for changing multiple cpt entries.
 class BayesianNetwork.CompoundChangeLocationEdit
          Undoable edit for grouping multiple moves together.
 class BayesianNetwork.CompoundPostEvidenceEdit
          Undoable edit for posting multiple pieces of evidence.
 class BayesianNetwork.PostEvidenceEdit
          Undoable edit for posting evidence.
 class BayesianNetwork.RemoveEdgeEdit
          Undoable edit for removing an edge.
 class BayesianNetwork.RemoveEvidenceEdit
          Undoable edit for removing evidence.
 class BayesianNetwork.RemoveNodeEdit
          Undoable edit for removing a node.
 class BayesianNetwork.RemoveStateEdit
          Undoable edit for removing a state.
 class BayesianNetwork.RenameNetworkEdit
          Undoable edit for renaming the network.
 class BayesianNetwork.RenameNodeEdit
          Undoable edit for renaming a node.
 class BayesianNetwork.RenameStateEdit
          Undoable edit for renaming a state.
 class BayesianNetwork.ReorderParentEdit
          Undoable edit for reordering a parent.
 class BayesianNetwork.ReorderStateEdit
          Undoable edit for reordering a state.
 
Field Summary
static String DESCRIPTION_PROPERTY
          The Bayesian network description property.
static String NAME_PROPERTY
          The Bayesian network name property.
 
Constructor Summary
BayesianNetwork()
          Creates a new, empty BayesianNetwork.
BayesianNetwork(BayesianNetwork network)
          Creates a new BayesianNetwork that is a copy of the specified Bayesian network.
 
Method Summary
 void addBeliefListener(BeliefListener listener)
          Registers the specified listener to receive belief events when beliefs of any node in this Bayesian network change.
 void addCptListener(CptListener listener)
          Registers the specified listener to receive cpt events when the cpt of any node in this Bayesian network changes.
 DiscreteNode addDiscreteNode(String name)
          Adds a new discrete node to this Bayesian network that has the specified name and two states: true and false.
 DiscreteNode addDiscreteNode(String name, List states)
          Adds a new discrete node to this Bayesian network that has the specified name and states.
 Edge addEdge(Node parent, Node child)
          Adds an edge from the specified parent to the specified child to this Bayesian network.
 void addEvidenceListener(EvidenceListener listener)
          Registers the specified listener to receive evidence events when evidence is posted to or retracted from any node in this Bayesian network.
 void addNodeListener(NodeListener listener)
          Registers the specified listener to receive node events when aspects of any node in this Bayesian network change.
 void addNodePropertyChangeListener(PropertyChangeListener listener)
          Registers the specified property change listener to receive events when the user properties of any node in this Bayesian network change.
 void addPropertyChangeListener(PropertyChangeListener listener)
          Registers the specified property change listener to receive events when the user properties of this Bayesian network change.
 void addStateListener(StateListener listener)
          Registers the specified listener to receive state events when states of any node in this Bayesian network change.
 void addTopologyListener(TopologyListener listener)
          Registers the specified topology listener to receive topology events from this Bayesian network.
 void addUndoableEditListener(UndoableEditListener listener)
          Registers the specified listener to receive undoable edit events from this Bayesian network.
 void clearEvidence()
          Retracts evidence from all nodes in this Bayesian network.
 Set discreteNodeSet()
          Returns a set view of the discrete nodes contained in this Bayesian network.
protected  void fireAllEvidenceRetracted()
          Notifies evidence listeners and the belief updater that all evidence was retracted from this Bayesian network.
protected  void fireEdgeAdded(Edge edge)
          Notifies topology listeners and the belief updater that an edge was added to this Bayesian network.
protected  void fireEdgeRemoved(Edge edge)
          Notifies topology listeners and the belief updater that an edge was removed from this Bayesian network.
protected  void fireInvalidBeliefs()
          Notifies belief listeners that all nodes have invalid beliefs.
protected  void fireNodeAdded(Node node)
          Notifies topology listeners and the belief updater that a node was added to this Bayesian network.
protected  void fireNodeRemoved(Node node)
          Notifies topology listeners and the belief updater that a node was removed from this Bayesian network.
 BeliefUpdater getBeliefUpdater()
          Returns this Bayesian network's belief updater.
 String getDescription()
          Returns this Bayesian network's description.
 DiscreteNode getDiscreteNode(String name)
          Returns the discrete node in this Bayesian network that has the specified name.
 InferenceEngine getInferenceEngine()
          Returns the inference engine being used by this Bayesian network.
 String getName()
          Returns this Bayesian network's name.
 Node getNode(String name)
          Returns the node in this Bayesian network that has the specified name.
 Map getProperties()
          Returns this Bayesian network's user properties.
 Graph getTopology()
          Returns the topology of this Bayesian network.
 UndoableEditSupport getUndoableEditSupport()
          Returns this Bayesian network's undoable edit support.
 Set nodeSet()
          Returns a set view of the nodes contained in this Bayesian network.
 void removeBeliefListener(BeliefListener listener)
          Unregisters the specified listener so it will no longer receive belief events from this Bayesian network.
 void removeCptListener(CptListener listener)
          Unregisters the specified listener so it will no longer receive cpt events from this Bayesian network.
 boolean removeEdge(Node parent, Node child)
          Removes the edge from the specified parent to the specified child from this Bayesian network.
 void removeEvidenceListener(EvidenceListener listener)
          Unregisters the specified listener so it will no longer receive evidence events from this Bayesian network.
 boolean removeNode(Node node)
          Removes the specified node and all connected edges from this Bayesian network.
 void removeNodeListener(NodeListener listener)
          Unregisters the specified listener so it will no longer receive node events from this Bayesian network.
 void removeNodePropertyChangeListener(PropertyChangeListener listener)
          Unregisters the specified property change listener so it will no longer receive events when the user properties of nodes change.
 void removePropertyChangeListener(PropertyChangeListener listener)
          Unregisters the specified property change listener so that it will not receive property change events from this Bayesian network.
 void removeStateListener(StateListener listener)
          Unregisters the specified listener so it will no longer receive state events from this Bayesian network.
 void removeTopologyListener(TopologyListener listener)
          Unregisters the specified topology listener so that it will not receive topology events from this Bayesian network.
 void removeUndoableEditListener(UndoableEditListener listener)
          Unregisters the specified listener so it will no longer receive undoable edit events from this Bayesian network.
 void setDescription(String description)
          Sets this Bayesian network's description to the specified description.
 void setInferenceEngine(InferenceEngine engine)
          Sets this Bayesian network's inference engine to the specified inference engine.
 boolean setName(String name)
          Sets the name of this Bayesian network to the specified name.
 String toString()
          Returns a string representation of this Bayesian network.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

NAME_PROPERTY

public static final String NAME_PROPERTY
The Bayesian network name property.

See Also:
Constant Field Values

DESCRIPTION_PROPERTY

public static final String DESCRIPTION_PROPERTY
The Bayesian network description property.

See Also:
Constant Field Values
Constructor Detail

BayesianNetwork

public BayesianNetwork()
Creates a new, empty BayesianNetwork.


BayesianNetwork

public BayesianNetwork(BayesianNetwork network)
Creates a new BayesianNetwork that is a copy of the specified Bayesian network. The new network will copy the name, description, nodes, node states, CPTs and evidence in the specified network. The specified Bayesian network is not modified in any way.

Parameters:
network - Bayesian network to copy.
Method Detail

setName

public final boolean setName(String name)
Sets the name of this Bayesian network to the specified name.

Parameters:
name - name of the Bayesian network.
Returns:
true if the name was set; false if the name was empty or null

getName

public final String getName()
Returns this Bayesian network's name.

Returns:
this Bayesian network's name.

getTopology

public Graph getTopology()
Returns the topology of this Bayesian network. You will only use this method when you want to write graph-theoretic algorithms on the network.

Returns:
the topology of this Bayesian network.

nodeSet

public Set nodeSet()
Returns a set view of the nodes contained in this Bayesian network. Elements of the returned set are guaranteed to be of type Node.

This method just returns getTopology().vertexSet().

Returns:
a set view of the nodes contained in this Bayesian network.

discreteNodeSet

public Set discreteNodeSet()
Returns a set view of the discrete nodes contained in this Bayesian network. Elements of this returned set are guaranteed to be of type DiscreteNode.

This method just returns the elements of getTopology().vertexSet() that are discrete nodes.

Returns:
a set view of the discrete nodes contained in this Bayesian network.

getDescription

public String getDescription()
Returns this Bayesian network's description.

Returns:
this Bayesian network's description.

setDescription

public void setDescription(String description)
Sets this Bayesian network's description to the specified description.

Parameters:
description - new description.

clearEvidence

public void clearEvidence()
Retracts evidence from all nodes in this Bayesian network. 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 Bayesian network.

Overrides:
toString in class Object
Returns:
a string representation of this Bayesian network.

addDiscreteNode

public DiscreteNode addDiscreteNode(String name)
Adds a new discrete node to this Bayesian network that has the specified name and two states: true and false. If the specified name is null, a unique name will be generated for the new node.

This method just calls

 addDiscreteNode(name, Arrays.asList(new String[] {"true", "false"});
 

Parameters:
name - name of the new node.
Returns:
the newly added node, or null if another node in this Bayesian network already has the specified name. If another node has the specified name, this Bayesian network will not be modified.

addDiscreteNode

public DiscreteNode addDiscreteNode(String name,
                                    List states)
Adds a new discrete node to this Bayesian network that has the specified name and states. If the specified name is null a unique name will be generated for the new node. The list of states must contain only String elements, and must have at least two states.

This method sends an UnlimitedNodesError to the ErrorNotifier if it detects an evaluation key and there are already 5 nodes in the network. A commercial license is required to add more than 5 nodes to a network.

This method sends a DuplicateNodeError to the ErrorNotifier if another node has the specified name.

Parameters:
name - name of the new node.
states - states of the new node.
Returns:
the newly added node, or null if another node in this Bayesian network already has the specified name. If another node has the specified name, this Bayesian network will not be modified.
Throws:
NullPointerException - if states is null.
IllegalArgumentException - if states.size() < 2 or states contains an element that is not of type String.

removeNode

public boolean removeNode(Node node)
Removes the specified node and all connected edges from this Bayesian network.

Parameters:
node - node to remove.
Returns:
true if the node was removed, false if the specified node is not in the network.
Throws:
NullPointerException - if the specified node is null.

addEdge

public Edge addEdge(Node parent,
                    Node child)
Adds an edge from the specified parent to the specified child to this Bayesian network.

This method does not create a new edge and returns null if any of the following are true:

Parameters:
parent - the "from" node of the new edge.
child - the "to" node of the new edge.
Returns:
the newly created edge or null if one was not created.

removeEdge

public boolean removeEdge(Node parent,
                          Node child)
Removes the edge from the specified parent to the specified child from this Bayesian network.

Parameters:
parent - the "from" node of the edge to remove.
child - the "to" node of the edge to remove.
Returns:
true if the edge was removed.

getNode

public Node getNode(String name)
Returns the node in this Bayesian network that has the specified name. This method returns null if no node has the specified name.

Parameters:
name - name of node to be returned.
Returns:
the node with the specified name or null if a node with that name cannot be found.

getDiscreteNode

public DiscreteNode getDiscreteNode(String name)
Returns the discrete node in this Bayesian network that has the specified name. This method returns null if no discrete node has the specified name.

Parameters:
name - name of discrete node to be returned.
Returns:
the discrete node with the specified name or null if a node with that name cannot be found.

getProperties

public Map getProperties()
Returns this Bayesian network's user properties. User properties are custom properties added to the network.

The returned map is fully modifiable and expects entries of the form (String, Object). Changing the returned map will fire an event to all PropertyChangeListeners registered with this Bayesian network.

Returns:
this Bayesian network's user properties.

getInferenceEngine

public InferenceEngine getInferenceEngine()
Returns the inference engine being used by this Bayesian network. Subclasses can override this method to return a custom inference engine.

Returns:
the inference engine being used by this Bayesian network.

setInferenceEngine

public void setInferenceEngine(InferenceEngine engine)
Sets this Bayesian network's inference engine to the specified inference engine. This method removes the previous inference engine.

Parameters:
engine - new inference engine.
Throws:
NullPointerException - if engine is null.

getBeliefUpdater

public BeliefUpdater getBeliefUpdater()
Returns this Bayesian network's belief updater. The belief updater controls automatic belief updating.

Returns:
this Bayesian network's belief updater.

addTopologyListener

public void addTopologyListener(TopologyListener listener)
Registers the specified topology listener to receive topology events from this Bayesian network.

Parameters:
listener - topology listener to register with this Bayesian network.
Throws:
IllegalArgumentException - if listener is null.

removeTopologyListener

public void removeTopologyListener(TopologyListener listener)
Unregisters the specified topology listener so that it will not receive topology events from this Bayesian network.

Parameters:
listener - topology listener to remove from this Bayesian network.

addNodeListener

public void addNodeListener(NodeListener listener)
Registers the specified listener to receive node events when aspects of any node in this Bayesian network change.

Parameters:
listener - node listener to register with this network.
Throws:
IllegalArgumentException - if listener is null.

removeNodeListener

public void removeNodeListener(NodeListener listener)
Unregisters the specified listener so it will no longer receive node events from this Bayesian network.

Parameters:
listener - node listener to remove from this network.

addStateListener

public void addStateListener(StateListener listener)
Registers the specified listener to receive state events when states of any node in this Bayesian network change.

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

removeStateListener

public void removeStateListener(StateListener listener)
Unregisters the specified listener so it will no longer receive state events from this Bayesian network.

Parameters:
listener - state listener to remove from this network.

addCptListener

public void addCptListener(CptListener listener)
Registers the specified listener to receive cpt events when the cpt of any node in this Bayesian network changes.

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

removeCptListener

public void removeCptListener(CptListener listener)
Unregisters the specified listener so it will no longer receive cpt events from this Bayesian network.

Parameters:
listener - cpt listener to remove from this network.

addBeliefListener

public void addBeliefListener(BeliefListener listener)
Registers the specified listener to receive belief events when beliefs of any node in this Bayesian network change.

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

removeBeliefListener

public void removeBeliefListener(BeliefListener listener)
Unregisters the specified listener so it will no longer receive belief events from this Bayesian network.

Parameters:
listener - belief listener to remove from this network.

addEvidenceListener

public void addEvidenceListener(EvidenceListener listener)
Registers the specified listener to receive evidence events when evidence is posted to or retracted from any node in this Bayesian network.

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

removeEvidenceListener

public void removeEvidenceListener(EvidenceListener listener)
Unregisters the specified listener so it will no longer receive evidence events from this Bayesian network.

Parameters:
listener - evidence listener to remove from this network.

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)
Registers the specified property change listener to receive events when the user properties of this Bayesian network change.

Parameters:
listener - property change listener to register with this Bayesian network.
Throws:
IllegalArgumentException - if listener is null.

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)
Unregisters the specified property change listener so that it will not receive property change events from this Bayesian network.

Parameters:
listener - property change listener to remove from this Bayesian network.

addNodePropertyChangeListener

public void addNodePropertyChangeListener(PropertyChangeListener listener)
Registers the specified property change listener to receive events when the user properties of any node in this Bayesian network change.

Parameters:
listener - property change listener to register with this network.
Throws:
IllegalArgumentException - if listener is null.

removeNodePropertyChangeListener

public void removeNodePropertyChangeListener(PropertyChangeListener listener)
Unregisters the specified property change listener so it will no longer receive events when the user properties of nodes change.

Parameters:
listener - property change listener to remove from this network.

addUndoableEditListener

public void addUndoableEditListener(UndoableEditListener listener)
Registers the specified listener to receive undoable edit events from this Bayesian network.

Parameters:
listener - undoable edit listener to register with this network.
Throws:
IllegalArgumentException - if listener is null.

removeUndoableEditListener

public void removeUndoableEditListener(UndoableEditListener listener)
Unregisters the specified listener so it will no longer receive undoable edit events from this Bayesian network.

Parameters:
listener - undoable edit listener to remove from this network.

getUndoableEditSupport

public UndoableEditSupport getUndoableEditSupport()
Returns this Bayesian network's undoable edit support.

Returns:
this Bayesian network's undoable edit support.

fireNodeAdded

protected void fireNodeAdded(Node node)
Notifies topology listeners and the belief updater that a node was added to this Bayesian network.

Parameters:
node - node added to this Bayesian network.

fireNodeRemoved

protected void fireNodeRemoved(Node node)
Notifies topology listeners and the belief updater that a node was removed from this Bayesian network.

Parameters:
node - node removed from this Bayesian network.

fireEdgeAdded

protected void fireEdgeAdded(Edge edge)
Notifies topology listeners and the belief updater that an edge was added to this Bayesian network.

Parameters:
edge - edge added to this Bayesian network.

fireEdgeRemoved

protected void fireEdgeRemoved(Edge edge)
Notifies topology listeners and the belief updater that an edge was removed from this Bayesian network.

Parameters:
edge - edge removed from this Bayesian network.

fireAllEvidenceRetracted

protected void fireAllEvidenceRetracted()
Notifies evidence listeners and the belief updater that all evidence was retracted from this Bayesian network.


fireInvalidBeliefs

protected void fireInvalidBeliefs()
Notifies belief listeners that all nodes have invalid beliefs.