Implements the SemiNFG class
Part of: PyNFG  a Python package for modeling and solving Network Form Games
Created on Wed Nov 21 09:49:05 2012
Copyright (C) 2013 James Bono
GNU Affero General Public License
Implements the semiNFG formalism created by D. Wolpert
For an example, see PyNFG/bin/stackelberg.py
Parameters: 

Formally, a semiNFG consists of the following elements:
 nodes  either nodes.ChanceNode or nodes.DecisionNode. For convenience, there is also a nodes.DeterNode class to implement deterministic nodes.
 edges  given by SemiNFG.edges.
 for each node, a conditional probability distribution from the values of its parents  given by nodes.DecisionNode.prob() or nodes.ChanceNode.prob().
 a partition splitting the set of nodes into a set of nature nodes and a set of nodes for each player in the game, given by seminfg.SemiNFG.partition.
 utility functions, one for each player in the game, given by seminfg.SemiNFG.u_functions.
Note
An object that consists of all of these elements except the utility functions is called a semiBayes net. When initialized with u_functions=None, the result is a semiBayes net.
Note
For a node in nodes, the parent attribute, e.g. nodes.ChanceNode.parents, must not have parents that are not in the set of nodes passed to seminfg.SemiNFG.
Some useful methods:
Upon initialization, the following private methods are called:
Retrieve the set of ancestors of a given node.
Parameters:  nodename (str) – the name of the descendent node for which ancestors are desired. 

Returns:  a set of nodes that are the ancestors of the input node in the SemiNFG object. 
Retrieve the set of children of a given node.
Parameters:  nodename (str) – the parent node for which children are desired. 

Returns:  a set of nodes that are the children of the input node in the SemiNFG object. 
This is equivalent to calling SemiNFG.edges[nodename]
Retrieve the set of descendants of a given node.
Parameters:  nodename (str) – the name of the ancestor node for which descendants are desired. 

Returns:  a set of nodes that are the descendants of the input node in the SemiNFG object. 
Draw the DAG representing the topology of the SemiNFG.
Parameters:  subgraph (set or list) – (Optional) node names of subset of nodes to include in drawing. Default is self.nodes. If not specified, all nodes are graphed. 

Note
This method uses the matplotlib.pyplot and networkx packages.
Retrieve the CPTs for decision nodes
Parameters:  mode (str) – optional string. If None, then keys are names of decision nodes, and values are CPTs of corresponding decision nodes. If ‘basename’ then the output will be a dictionary with basename keys. Values will be CPTs of the first instance (game chronology/topology) of the corresponding basename. 

Returns:  dict with nodenames or basenames as keys and current CPTs of corresponding decision nodes as output. 
Retrieve the leaves of the SemiNFG.
Returns:  set of leaf nodes, which are nodes.ChanceNode, nodes.DecisionNode, or nodes.DeterNode 

Retrieve the roots of the SemiNFG.
Returns:  set of root nodes, which are nodes.ChanceNode, nodes.DecisionNode, or nodes.DeterNode 

Retrieve the values of the nodes comprising the SemiNFG.
Parameters:  nodenames (set or list) – (Optional) The names of the nodes whose values should be returned. If no names are specified, all node values are returned. 

Returns:  dict where keys are node names and values are node values 
Compute the log likelihood of the net using the values in nodeinput.
Parameters:  nodeinput (dict) – Keys are node names. Values are node values. This optional argument can be any subset of nodes in the SemiNFG. For nodes not specified, the current value is used. 

Returns:  the log likelihood of the values given the net. 
Note
For discrete valued nodes, the value must be in the node’s space, or else an error will be be raised by that node’s prob() method, e.g. nodes.DecisionNode.prob().
Warning
When arbitrarily setting values, some children may have zero probability given their parents, and the log likelihood may be inf, which results in a divide by zero error.
Warning
The decision nodes must have CPTs before using this function.
Retrieve the set of parents of a given node.
Parameters:  nodename (str) – the name of the child node for which parents are desired. 

Returns:  a set of nodes that are the parents of the input node in the SemiNFG object. 
This is equivalent to calling set(node.parents.values())
Sample the net to obtain a draw from the joint distribution.
Parameters: 


Returns:  a dict keyed by node names in nodenames input. Values are values of nodes in node names. 
Warning
The decision nodes must have CPTs before using this function.
Set CPTs for nodes in the SemiNFG by node name
Parameters:  cptdict (dict) – dictionary with node names as keys and CPTs as values 

Set the values of a subset of the nodes comprising the SemiNFG.
Parameters:  value_dict (dict) – keys are node names, and values are node values. 

Note
For discrete valued nodes, the value must be in the node’s space, or else a ValueError will be raised by that node’s set_value method, e.g. nodes.DecisionNode.set_value().
Warning
When arbitrarily setting values, some children may have zero probability given their parents, and the log likelihood may be inf, which results in a divide by zero error for the method seminfg.SemiNFG.loglike().
Evaluate the utility of the specified player
Parameters: 

