Influence Diagram

an influence diagram

An influence diagram is a compact graphical and mathematical representation of a decision situation. It is a generalization of a Bayesian network, in which not only probabilistic inference problems but also decision making problems (following the maximum expected utility criterion) can be modeled and solved. It includes 3 types of nodes : action, decision and utility nodes (from wikipedia).

PyAgrum’s so-called influence diagram represents both influence diagrams and LIMIDs. The way to enforce that such a model represent an influence diagram and not a LIMID belongs to the inference engine.

Tutorial

Reference

Model

class pyAgrum.InfluenceDiagram(*args)

InfluenceDiagram represents an Influence Diagram.

InfluenceDiagram() -> InfluenceDiagram

default constructor

InfluenceDiagram(source) -> InfluenceDiagram
Parameters:
  • source (pyAgrum.InfluenceDiagram) – the InfluenceDiagram to copy

add(variable, id=0)

Add a chance variable, it’s associate node and it’s CPT.

The id of the new variable is automatically generated.

Parameters
  • variable (pyAgrum.DiscreteVariable) – The variable added by copy.

  • id (int) – The chosen id. If 0, the NodeGraphPart will choose.

Warning

give an id (not 0) should be reserved for rare and specific situations !!!

Returns

the id of the added variable.

Return type

int

Raises

pyAgrum.DuplicateElement – If id(<>0) is already used

addArc(*args)

Add an arc in the ID, and update diagram’s potential nodes cpt if necessary.

Parameters
  • tail (int) – the id of the tail node

  • head (int) – the id of the head node

Raises
Return type

None

addChanceNode(*args)

Add a chance variable, it’s associate node and it’s CPT.

The id of the new variable is automatically generated.

Parameters
  • variable (pyAgrum.DiscreteVariable) – the variable added by copy.

  • id (int) – the chosen id. If 0, the NodeGraphPart will choose.

Warning

give an id (not 0) should be reserved for rare and specific situations !!!

Returns

the id of the added variable.

Return type

int

Raises

pyAgrum.DuplicateElement – If id(<>0) is already used

addDecisionNode(variable, id=0)

Add a decision variable.

The id of the new variable is automatically generated.

Parameters
  • variable (pyAgrum.DiscreteVariable) – the variable added by copy.

  • id (int) – the chosen id. If 0, the NodeGraphPart will choose.

Warning

give an id (not 0) should be reserved for rare and specific situations !!!

Returns

the id of the added variable.

Return type

int

Raises

pyAgrum.DuplicateElement – If id(<>0) is already used

addUtilityNode(*args)

Add a utility variable, it’s associate node and it’s UT.

The id of the new variable is automatically generated.

Parameters
  • variable (pyAgrum.DiscreteVariable) – the variable added by copy

  • id (int) – the chosen id. If 0, the NodeGraphPart will choose

Warning

give an id (not 0) should be reserved for rare and specific situations !!!

Returns

the id of the added variable.

Return type

int

Raises
ancestors(norid)
Parameters

norid (object) –

Return type

object

arcs()
Returns

the list of all the arcs in the Influence Diagram.

Return type

list

chanceNodeSize()
Returns

the number of chance nodes.

Return type

int

changeVariableName(*args)
Parameters
  • id (int) – the node Id

  • new_name (str) – the name of the variable

Raises
Return type

None

children(norid)
Parameters
  • id (int) – the id of the parent

  • norid (object) –

Returns

the set of all the children

Return type

Set

clear()
Return type

None

completeInstantiation()
Return type

pyAgrum.Instantiation

connectedComponents()

connected components from a graph/BN

Compute the connected components of a pyAgrum’s graph or Bayesian Network (more generally an object that has nodes, children/parents or neighbours methods)

The firstly visited node for each component is called a ‘root’ and is used as a key for the component. This root has been arbitrarily chosen during the algorithm.

Returns

dict of connected components (as set of nodeIds (int)) with a nodeId (root) of each component as key.

Return type

dict(int,Set[int])

cpt(*args)

Returns the CPT of a variable.

Parameters

VarId (int) – A variable’s id in the pyAgrum.BayesNet.

Returns

The variable’s CPT.

Return type

pyAgrum.Potential

Raises

pyAgrum.NotFound – If no variable’s id matches varId.

dag()
Returns

a constant reference to the dag of this BayesNet.

Return type

pyAgrum.DAG

decisionNodeSize()
Returns

the number of decision nodes

Return type

int

decisionOrder()
Return type

pyAgrum.YetUnWrapped

decisionOrderExists()
Returns

True if a directed path exist with all decision node

Return type

bool

descendants(norid)
Parameters

norid (object) –

Return type

object

empty()
Return type

bool

erase(*args)

Erase a Variable from the network and remove the variable from all his childs.

If no variable matches the id, then nothing is done.

Parameters
  • id (int) – The id of the variable to erase.

  • var (pyAgrum.DiscreteVariable) – The reference on the variable to remove.

Return type

None

eraseArc(*args)

Removes an arc in the ID, and update diagram’s potential nodes cpt if necessary.

If (tail, head) doesn’t exist, the nothing happens.

Parameters
  • arc (pyAgrum.Arc) – The arc to be removed.

  • tail (int) – the id of the tail node

  • head (int) – the id of the head node

Return type

None

exists(node)
Parameters

node (int) –

Return type

bool

existsArc(*args)
Return type

bool

existsPathBetween(*args)
Returns

true if a path exists between two nodes.

Return type

bool

family(norid)
Parameters

norid (object) –

Return type

object

static fastPrototype(dotlike, domainSize=2)
Create an Influence Diagram with a dot-like syntax which specifies:
  • the structure ‘a->b<-c;b->d;c<-e;’.

  • a prefix for the type of node (chance/decision/utiliy nodes):

    • a : a chance node named ‘a’ (by default)

    • $a : a utility node named ‘a’

    • *a : a decision node named ‘a’

  • the type of the variables with different syntax as postfix:

    • by default, a variable is a pyAgrum.RangeVariable using the default domain size (second argument)

    • with ‘a[10]’, the variable is a pyAgrum.RangeVariable using 10 as domain size (from 0 to 9)

    • with ‘a[3,7]’, the variable is a pyAgrum.RangeVariable using a domainSize from 3 to 7

    • with ‘a[1,3.14,5,6.2]’, the variable is a pyAgrum.DiscretizedVariable using the given ticks (at least 3 values)

    • with ‘a{top|middle|bottom}’, the variable is a pyAgrum.LabelizedVariable using the given labels.

    • with ‘a{-1|5|0|3}’, the variable is a pyAgrum.IntegerVariable using the sorted given values.

Note

  • If the dot-like string contains such a specification more than once for a variable, the first specification will be used.

  • the potentials (probabilities, utilities) are randomly generated.

  • see also pyAgrum.fastID.

Examples

>>> import pyAgrum as gum
>>> bn=pyAgrum.fastID('A->B[1,3]<-*C{yes|No}->$D<-E[1,2.5,3.9]',6)
Parameters
  • dotlike (str) – the string containing the specification

  • domainSize (int) – the default domain size for variables

Returns

the resulting Influence Diagram

Return type

pyAgrum.InfluenceDiagram

getDecisionGraph()
Returns

the temporal Graph.

Return type

pyAgrum.DAG

hasSameStructure(other)
Parameters
  • pyAgrum.DAGmodel – a direct acyclic model

  • other (pyAgrum.DAGmodel) –

Returns

True if all the named node are the same and all the named arcs are the same

Return type

bool

idFromName(name)

Returns a variable’s id given its name.

Parameters

name (str) – the variable’s name from which the id is returned.

Returns

the variable’s node id.

Return type

int

Raises

pyAgrum.NotFound – If no such name exists in the graph.

ids(names)
Parameters

names (Vector_string) –

Return type

pyAgrum.YetUnWrapped

isChanceNode(*args)
Parameters

varId (int) – the tested node id.

Returns

true if node is a chance node

Return type

bool

isDecisionNode(*args)
Parameters

varId (int) – the tested node id.

Returns

true if node is a decision node

Return type

bool

isIndependent(*args)
Return type

bool

isUtilityNode(*args)
Parameters

varId (int) – the tested node id.

Returns

true if node is an utility node

Return type

bool

loadBIFXML(*args)

Load a BIFXML file.

Parameters

name (str) – the name’s file

Raises
Return type

bool

log10DomainSize()
Return type

float

moralGraph(clear=True)

Returns the moral graph of the BayesNet, formed by adding edges between all pairs of nodes that have a common child, and then making all edges in the graph undirected.

Returns

The moral graph

Return type

pyAgrum.UndiGraph

Parameters

clear (bool) –

moralizedAncestralGraph(nodes)
Parameters

nodes (object) –

Return type

pyAgrum.UndiGraph

names()
Returns

The names of the InfluenceDiagram variables

Return type

list

nodeId(var)
Parameters

var (pyAgrum.DiscreteVariable) – a variable

Returns

the id of the variable

Return type

int

Raises

pyAgrum.IndexError – If the InfluenceDiagram does not contain the variable

nodes()
Returns

the set of ids

Return type

set

nodeset(names)
Parameters

names (Vector_string) –

Return type

List[int]

parents(norid)
Parameters
  • id – The id of the child node

  • norid (object) –

Returns

the set of the parents ids.

Return type

set

saveBIFXML(name)

Save the BayesNet in a BIFXML file.

Parameters

name (str) – the file’s name

Return type

None

size()
Returns

the number of nodes in the graph

Return type

int

sizeArcs()
Returns

the number of arcs in the graph

Return type

int

property thisown

The membership flag

toDot()
Returns

a friendly display of the graph in DOT format

Return type

str

topologicalOrder(clear=True)
Returns

the list of the nodes Ids in a topological order

Return type

List

Raises

pyAgrum.InvalidDirectedCycle – If this graph contains cycles

Parameters

clear (bool) –

utility(*args)
Parameters

varId (int) – the tested node id.

Returns

the utility table of the node

Return type

pyAgrum.Potential

Raises

pyAgrum.IndexError – If the InfluenceDiagram does not contain the variable

utilityNodeSize()
Returns

the number of utility nodes

Return type

int

variable(*args)
Parameters

id (int) – the node id

Returns

a constant reference over a variabe given it’s node id

Return type

pyAgrum.DiscreteVariable

Raises

pyAgrum.NotFound – If no variable’s id matches the parameter

variableFromName(name)
Parameters

name (str) – a variable’s name

Returns

the variable

Return type

pyAgrum.DiscreteVariable

Raises

pyAgrum.IndexError – If the InfluenceDiagram does not contain the variable

variableNodeMap()
Return type

pyAgrum.VariableNodeMap

Inference

an inference in an influence diagram
class pyAgrum.ShaferShenoyLIMIDInference(infDiag)

This inference considers the provided model as a LIMID rather than an influence diagram. It is an optimized implementation of the LIMID resolution algorithm. However an inference on a classical influence diagram can be performed by adding a assumption of the existence of the sequence of decision nodes to be solved, which also implies that the decision choices can have an impact on the rest of the sequence (Non Forgetting Assumption, cf. pyAgrum.ShaferShenoyLIMIDInference.addNoForgettingAssumption).

Parameters

infDiag (InfluenceDiagram) –

MEU(*args)

Returns maximum expected utility obtained from inference.

Raises

pyAgrum.OperationNotAllowed – If no inference have yet been made

Return type

object

addEvidence(*args)
Return type

None

addNoForgettingAssumption(*args)
Return type

None

chgEvidence(*args)
Return type

None

clear()
Return type

None

eraseAllEvidence()

Removes all the evidence entered into the diagram.

Return type

None

eraseEvidence(*args)
Parameters

evidence (pyAgrum.Potential) – the evidence to remove

Raises

pyAgrum.IndexError – If the evidence does not belong to the influence diagram

Return type

None

hardEvidenceNodes()
Return type

object

hasEvidence(*args)
Return type

bool

hasHardEvidence(nodeName)
Parameters

nodeName (str) –

Return type

bool

hasNoForgettingAssumption()
Return type

bool

hasSoftEvidence(*args)
Return type

bool

influenceDiagram()

Returns a constant reference over the InfluenceDiagram on which this class work.

Returns

the InfluenceDiagram on which this class work

Return type

pyAgrum.InfluenceDiagram

isSolvable()
Return type

bool

junctionTree()
Return type

pyAgrum.JunctionTree

makeInference()

Makes the inference.

Return type

None

meanVar(*args)
Return type

object

nbrEvidence()
Return type

int

nbrHardEvidence()
Return type

int

nbrSoftEvidence()
Return type

int

optimalDecision(*args)

Returns best choice for decision variable given in parameter ( based upon MEU criteria )

Parameters

decisionId (int,str) – the id or name of the decision variable

Raises
Return type

pyAgrum.Potential

posterior(*args)
Return type

pyAgrum.Potential

posteriorUtility(*args)
Return type

pyAgrum.Potential

reducedGraph()
Return type

pyAgrum.DAG

reducedLIMID()
Return type

pyAgrum.InfluenceDiagram

reversePartialOrder()
Return type

pyAgrum.YetUnWrapped

setEvidence(evidces)

Erase all the evidences and apply addEvidence(key,value) for every pairs in evidces.

Parameters

evidces (dict) – a dict of evidences

Raises
  • gum.InvalidArgument – If one value is not a value for the node

  • gum.InvalidArgument – If the size of a value is different from the domain side of the node

  • gum.FatalError – If one value is a vector of 0s

  • gum.UndefinedElement – If one node does not belong to the influence diagram

softEvidenceNodes()
Return type

object

updateEvidence(evidces)

Apply chgEvidence(key,value) for every pairs in evidces (or addEvidence).

Parameters

evidces (dict) – a dict of evidences

Raises
  • gum.InvalidArgument – If one value is not a value for the node

  • gum.InvalidArgument – If the size of a value is different from the domain side of the node

  • gum.FatalError – If one value is a vector of 0s

  • gum.UndefinedElement – If one node does not belong to the Bayesian network