Decision Node

Implements the DecisionNode class

Created on Mon Feb 18 10:31:17 2013

Copyright (C) 2013 James Bono

GNU Affero General Public License

class pynfg.classes.decisionnode.DecisionNode(name, player, space, parents=None, description='no description', time=None, basename=None, verbose=False)

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

The classes.DecisionNode 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 DecisionNode, usually descriptive, e.g. D5, for player 5’s decision node, or D51 for player 5’s 1st decision node, or D512 for player 5’s 1st decision node in the 2nd time step, etc.
• player (str) – the name of the player to which this DecisionNode belongs.
• space (list) – the list of the possible values for the DecisionNode. The order determines the order of the CPT when generated.
• parents (list) – the list of the parents of the decision node. All entries must be a classes.DecisionNode or a discrete classes.ChanceNode or nodes.DeterNode. The order of the parents in the list determinesthe rder of the CPT when generated.
• description (str) – a description of the decision node, usually including a summary description of the space, parents and children.
• time (int) – the timestep to which the node belongs. This is generally only used for seminfg.iterSemiNFG objects.
• basename (str) – Reference to a theoretical node in the base or kernel.

Formally, a decision node has the following properties:

• belongs to a human player

• has a space of possible values.

• the conditional probability distribution from the values of its

  parents - given by classes.DecisionNode.prob() or classes.ChanceNode.prob(), is not specified in the game. That distribution is given by the solution concept applied to the semi-NFG. This lack of CPDs at decision nodes is the reason the semi-NFG is said to be based on a semi-Bayes net.

Note

For a classes.DecisionNode, the parents nodes must be discrete.

Example:

import scipy.stats.distributions as randvars

dist1 = randvars.randint
params1 = [1, 4]
space1 = [1, 2, 3]
distip1 = (dist1, params1, space1)
C1 = ChanceNode('C1', distip=distip1, description='root CN given by randint 1 to 4')

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

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

Some useful methods are:

• classes.DecisionNode.draw_value()
• classes.DecisionNode.prob()
• classes.DecisionNode.logprob()
• classes.DecisionNode.randomCPT()
• classes.DecisionNode.perturbCPT()

draw_value(parentinput=None, setvalue=True, mode=False)

Draw a value from the classes.DecisionNode object

Parameters:

• parentinput (dict) – Optional. Specify values of the parents at which to draw values using the CPT. 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.DecisionNode.value. True by default.
• mode (bool) – draws the modal action

Returns:

an element of classes.DecisionNode.space.

Note

The values specified in parentinput must correspond to an item in the parent’s space attribute.

Warning

The CPT is an np.zero array upon initialization. Therefore, one must set the CPT wih classes.DecisionNode.randomCPT() or manually before calling this method.

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 only a subset of parent values are specified, then the current values are used for the remaining parents.
• valueinput – Optional. A legitimate value of the decision node object. If no valueinput is specified, then the current value of the node is used.

Returns:

the conditional logprob 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 correspond to items in the space attributes of the parents.

Warning

The CPT is an np.zero array upon initialization. Therefore, one must set the CPT wih classes.DecisionNode.randomCPT() or manually before calling this method.

makeCPTpure(setCPT=True)

Convert mixed CPT to pure CPT,

Parameters:setCPT (bool) – if True (default), then the CPT attribute is converted to a pure CPT. Otherwise, the output is a pure CPT.

Note

whenever there are multiple argmax’s, each gets equal probability in the resuling “pure” CPT.

perturbCPT(noise, mixed=True, setCPT=True, returnweight=False)

Create a perturbation of the CPT attribute.

Parameters:

• noise (float) – The noise determines the mixture between the current CPT and a random CPT, e.g. new = self.CPT*(1-noise) + randCPT*noise. Noise must be a number between 0 and 1.
• mixed (bool) – Optional. Determines if the perturbation is pure or mixed. If pure, then the perturbed CPT is a pure CPT with some of the pure weights shifted to other values. If mixed, then the perturbed CPT is a mixed CPT with positive weight on all values.

Note

If setCPT is True, then there is no CPT output. If setCPT is True, and returnweight is False, then there is no output. If setCPT is True, and returnweight is True, then the weight is the only output. If setCPT is False, and returnweight is False, then the only output is the CPT output. Finally, if setCPT is False, and returnweight is True, then there is both CPT and weight output, and the weight is first in the list.

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 only a subset of parent values are specified, then the current values are used for the remaining parents.
• valueinput – Optional. A legitimate value of the decision 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 correspond to items in the space attributes of the parents.

Warning

The CPT is an np.zero array upon initialization. Therefore, one must set the CPT wih classes.DecisionNode.randomCPT() or manually before calling this method.

randomCPT(mixed=False, setCPT=True)

Create a random CPT for the classes.DecisionNode object

Parameters:

• mixed (bool) – Optional. Determines whether a mixed CPT, i.e. a CPT that assigns nonzero weight to every value in classes.DecisionNode.space, or a pure CPT, i.e. a CPT that assigns probability 1 to a single value in classes.DecisionNode.space for each of the parent values.
• setCPT (bool) – Optional. Default is True. Determines whether the classes.DecisionNode.CPT attribut is set by the function

Returns:

a mixed or pure CPT.

uniformCPT(setCPT=True)

Create a uniform CPT for the classes.DecisionNode object

Parameters:setCPT (bool) – Optional. Default is True. Determines whether the classes.DecisionNode.CPT attribute is set by the function Returns:a uniform mixed CPT.