Chance Node

Implements the ChanceNode class

Part of: PyNFG - a Python package for modeling and solving Network Form Games

Created on Mon Feb 18 10:35:19 2013

Copyright (C) 2013 James Bono

GNU Affero General Public License

class pynfg.classes.chancenode.ChanceNode(name, CPTip=None, distip=None, description='no description', time=None, basename=None, verbose=False)

Implements a chance node of the semi-NFG formalism created by D. Wolpert

The classes.ChanceNode can be initialized with either a conditional probability distribution (CPT) or a distribution object from scipy.stats.distributions (discrete and continuous types are both supported).

Parameters:

• name (str) – the name of the ChanceNode, usually descriptive, e.g. C5 for the fifth chance node, or C21 for the second chance node in the first time step, etc.
• CPTip (tuple) – The input parameters for a chance node based on a CPT. It is a tuple with the following three elements: * CPTip[0]: np.array giving CPT - in order given by parent spaces * CPTip[1]: list of parents - in order of dims of CPT * CPTip[2]: list of space - in order of last dim of CPT
• distip (tuple) –

  The input parameters for a chance node based on a distribution from the scipy.stats.distributions module. It is a tuple with the following three elements:

  * distip[0]: :py:mod:`scipy.stats.distributions` distribution object
  * distip[1]: list of distribution params - order given by
     distribution args.
  * distip[2]: (None if distribution object is continuous) list of space
     if distribution object is discrete.

• description (str) – a description of the chance node, usually including a summary description of the distribution, space, parents and children.
• time (int) – the timestep to which the node belongs. This is generally only used when the node is in a seminfg.iterSemiNFG.
• basename (str) – This is only used when the node is in a seminfg.iterSemiNFG. It references a theoretical node in the base or kernel.

Note

For a classes.ChanceNode based on a CPT, the parents must be discrete valued nodes. The dimensions of the CPT must correspond to the order of the parents. The order of the CPT in each dimension must correspond to the order of the parent space for that dimension.

Formally, a chance node has the following properties:

• belongs to the nature player
• has a space of possible values
• has a conditional probability distribution from the values of its parents - given by classes.DecisionNode.prob() or classes.ChanceNode.prob().

Example:

import pynfg
import scipy.stats.distributions as randvars

D1 = DecisionNode('D1', '1', [-1, 0, 1], parents=[],
                  description='This is a child node of C1')

dist1 = randvars.norm
params1 = [D1, 2]
distip1 = (dist1, params1)
C1 = ChanceNode('C1', distip=distip1,
                description='CN norm rv with scale=2 and loc=D1')

or:

import pynfg
import scipy.stats.distributions as randvars

dist1 = randvars.randint
params1 = [5, 10]
distip1 = (dist1, params1)
C1 = ChanceNode('C1', distip=distip1,
                description='root CN randint from 5 to 10')

dist2 = randvars.hypergeom
params2 = [C1, 3, 3]
space2 = [0, 1, 2, 3]
distip2 = (dist2, params2, space2)
C2 = ChanceNode('C2', distip=distip1,
                description='CN hypergeom M=C1, n=3, N=3')

Upon initialization, the following private method is called: classes.ChanceNode._set_parent_dict()

Some useful methods are:

• classes.ChanceNode.draw_value()
• classes.ChanceNode.prob()
• classes.ChanceNode.logprob()

draw_value(parentinput=None, setvalue=True)

Draw a value from the classes.ChanceNode object

Parameters:

• parentinput (dict) – Optional. Specify values of the parents at which to draw values from the conditional probability distribution. Keys are parent names. Values are parent values. To specify values for only a subset of the parents, only enter those parents in the dictionary. If no parent values are specified, then the current values of the parents are used.
• setvalue (bool) – (Optional) determines if the random draw replaces classes.ChanceNode.value. True by default.

Returns:

an element of classes.ChanceNode.space if the ChanceNode object is discrete. For continuous ChanceNode objects, it returns a value at which the pdf is nonzero.

Note

If parent values are specified in parentinput, those values must be legitimate values of the parent. For discrete parents, the values must correspond to an item in the parent’s space attribute.

logprob(parentinput=None, valueinput=None)

Compute the conditional logprob of the current or specified value

Parameters:

• parentinput (dict) – Optional. Specify values of the parents at which to compute the conditional logprob. Keys are parent names. Values are parent values. To specify values for only a subset of the parents, only enter those parents in the dictionary. If no parent values are specified, then the current values of the parents are used.
• valueinput – Optional. A legitimate value of the chance node object. If no valueinput is specified, then the current value of the node is used.

Returns:

the log conditional probability of valueinput or the current value conditioned on parentinput or the current values of the parents.

Note

If parent values are specified in parentinput, those values must be legitimate values of the parent. For discrete parents, the values must correspond to an item in the parent’s space attribute.

This is equivalent to np.log(ChanceNode.prob())

prob(parentinput=None, valueinput=None)

Compute the conditional probability of the current or specified value

Parameters:

• parentinput (dict) – Optional. Specify values of the parents at which to compute the conditional probability. Keys are parent names. Values are parent values. To specify values for only a subset of the parents, only enter those parents in the dictionary. If no parent values are specified, then the current values of the parents are used.
• valueinput – Optional. A legitimate value of the chance node object. If no valueinput is specified, then the current value of the node is used.

Returns:

the conditional probability of valueinput or the current value conditioned on parentinput or the current values of the parents.

Note

If parent values are specified in parentinput, those values must be legitimate values of the parent. For discrete parents, the values must correspond to an item in the parent’s space attribute.