Semi-NFG

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

class pynfg.classes.seminfg.SemiNFG(nodes, u_functions=None)

Implements the semi-NFG formalism created by D. Wolpert

For an example, see PyNFG/bin/stackelberg.py

Parameters:

• nodes (set) – members are nodes.ChanceNode, nodes.DecisionNode, or nodes.DeterNode.
• u_functions (dict) – One entry for each player. Keys are player names. Values are functions from to be continued

Formally, a semi-NFG 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 semi-Bayes net. When initialized with u_functions=None, the result is a semi-Bayes 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:

• seminfg.SemiNFG.ancestors()
• seminfg.SemiNFG.descendants()
• seminfg.SemiNFG.children()
• seminfg.SemiNFG.loglike()
• seminfg.SemiNFG.sample()
• seminfg.SemiNFG.draw_graph()

Upon initialization, the following private methods are called:

• seminfg.SemiNFG._set_node_dict()
• seminfg.SemiNFG._set_partition()
• seminfg.SemiNFG._set_edges()
• seminfg.SemiNFG._topological_sort()

ancestors(nodename)

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.

children(nodename)

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]

descendants(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_graph(subgraph=None)

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.

get_decisionCPTs(mode=None)

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.

get_leaves()

Retrieve the leaves of the SemiNFG.

Returns:set of leaf nodes, which are nodes.ChanceNode, nodes.DecisionNode, or nodes.DeterNode

get_roots()

Retrieve the roots of the SemiNFG.

Returns:set of root nodes, which are nodes.ChanceNode, nodes.DecisionNode, or nodes.DeterNode

get_values(nodenames=None)

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

loglike(nodeinput=None)

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.

parents(nodename)

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(start=None, nodenames=None, exclude=None)

Sample the net to obtain a draw from the joint distribution.

Parameters:

• start (list or set) – (Optional) if unspecified, the entire net will be sampled from the prior. Otherwise, start is a list of nodenodes that serve as the starting points for the sampling. That is, the sampling will commence from the nodes in start and continue until all of the descendants of the nodes in start have been sampled exactly once.
• nodenames (list or set) – a list of node names for which output is desired. By default, no output is provided.
• exclude (list or set) – a list of node names that are to be held constant at their current values, i.e. excluded from the sampling.

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(cptdict)

Set CPTs for nodes in the SemiNFG by node name

Parameters:cptdict (dict) – dictionary with node names as keys and CPTs as values

set_values(value_dict)

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().

utility(player, nodeinput=None)

Evaluate the utility of the specified player

Parameters:

• player (str.) – The name of a player with a utility function specified.
• nodeinput (dict) – Optional. Keys are node names. Values are node values. The values in nodeinput merely override the current node values, so nodeinput does not need to specify values for every argument to a player’s utility function.