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 for Decision in PGM

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(*args)

Add a 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 that will be a chance node.

  • descr (str) – the descr of the variable following fast syntax extended for pyAgrum.fastID().

  • nbr_mod_or_id (int) – if the first argument is variable, this set an optional fixed id for the node. If the first argument is descr, this gives the default number of modalities for the variable. Note that if a utility node is described in descr, this value is overriden by 1.

Returns

the id of the added variable.

Return type

int

Raises

pyAgrum.DuplicateElement – If already used id or name.

addArc(*args)

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

Parameters

  • tail (Union[int,str]) – a variable’s id (int) or name

  • head (Union[int,str]) – a variable’s id (int) or name

Raises
Return type

None

addArcs(listArcs)

add a list of arcs in te model.

Parameters

listArcs (List[Tuple[int,int]]) – the list of arcs

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(*args)

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

addStructureListener(whenNodeAdded=None, whenNodeDeleted=None, whenArcAdded=None, whenArcDeleted=None)

Add the listeners in parameters to the list of existing ones.

Parameters

  • whenNodeAdded (lambda expression) – a function for when a node is added

  • whenNodeDeleted (lambda expression) – a function for when a node is removed

  • whenArcAdded (lambda expression) – a function for when an arc is added

  • whenArcDeleted (lambda expression) – a function for when an arc is removed

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
addVariables(listFastVariables, default_nbr_mod=2)

Add a list of variable in the form of ‘fast’ syntax.

Parameters

  • listFastVariables (List[str]) – the list of variables following fast syntax extended for pyAgrum.fastID().

  • default_nbr_mod (int) – the number of modalities for the variable if not specified in the fast description. Note that default_nbr_mod=1 is mandatory to create variables with only one modality (for utility for instance).

Returns

the list of created ids.

Return type

List[int]

ancestors(norid)

give the set of nodeid of ancestors of a node

Parameters

norid (str|int) – the name or the id of the node

Returns

the set of ids of the ancestors of node norid.

Return type

Set[int]

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

  • var (Union[int,str]) – a variable’s id (int) or name

  • new_name (str) – the name of the variable

Raises
Return type

None

children(norid)
Parameters

  • var (Union[int,str]) – a variable’s id (int) or name

  • norid (object) –

Returns

the set of all the children

Return type

Set

clear()
Return type

None

completeInstantiation()

Give an instantiation over all the variables of the model

Returns

a complete Instantiation for the model

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

var (Union[int,str]) – a variable’s id (int) or name

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

List[int]

decisionOrderExists()
Returns

True if a directed path exist with all decision node

Return type

bool

descendants(norid)

give the set of nodeid of descendants of a node

Parameters

norid (str|int) – the name or the id of the node

Returns

the set of ids of the descendants of node norid.

Return type

Set[int]

empty()

Check if there are some variables in the model.

Returns

True if there is no variable in the model.

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 (Union[int,str,pyAgrum.DiscreteVariable]) – a variable’s id (int) or name or th 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 whn calling eraseArc(arc)

  • tail (Union[int,str]) – a variable’s id (int) or name when calling eraseArc(tail,head)

  • head (Union[int,str]) – a variable’s id (int) or name when calling eraseArc(tail,head)

Return type

None

exists(node)

Check if a node with this name or id exists

Parameters

  • norid (str|int) – name or id of the searched node

  • node (int) –

Returns

True if there is a node with such a name or id

Return type

bool

existsArc(*args)

Check if an arc exists

Parameters

  • tail (str|int) – the name or id of the tail of the arc

  • head (str|int) – the name or the id of the head of the arc

Returns

True if tail->head is an arc.

Return type

bool

existsPathBetween(*args)
Returns

true if a path exists between two nodes.

Return type

bool

family(norid)

give the set of parents of a node and the node

Parameters

norid (str|int) – the node

Returns

the set of nodeId of the family of the node norid

Return type

Set[int]

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.

    • with ‘a{-0.5|5.01|0|3.1415}’, the variable is a pyAgrum.NumericalDiscreteVariable 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

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)

List of ids for a list of names of variables in the model

Parameters

  • lov (List[str]) – List of variable names

  • names (List[str]) –

Returns

The ids for the list of names of the graph variables

Return type

List[int]

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)

check if nodes X and nodes Y are independent given nodes Z

Parameters

  • X (str|intList[str|int]) – a list of of nodeIds or names

  • Y (str|intList[str|int]) – a list of of nodeIds or names

  • Z (str|intList[str|int]) – a list of of nodeIds or names

Raises

InvalidArgument – if X and Y share variables

Returns

True if X and Y are independent given Z in the model

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

returns the log10 of the domain size of the model defined as the product of the domain sizes of the variables in the model.

Returns

the log10 domain size.

Return type

float

moralGraph()

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

moralizedAncestralGraph(nodes)

build a UndiGraph by moralizing the Ancestral Graph of a list of nodes

Parameters

nodes (str|intList[str|int]) – the list of of nodeIds or names

Warning

gum.UndiGraph only knows NodeId. Hence the moralized ancestral graph does not include the names of the variables.graph

Returns

the moralized ancestral graph of the nodes

Return type

gum.UndiGraph

names()
Returns

The names of the InfluenceDiagram variables

Return type

List[str]

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)

Set of ids for a list of names of variables in the model

Parameters

  • lov (List[str]) – List of variable names

  • names (List[str]) –

Returns

The set of ids for the list of names of the graph variables

Return type

Set[int]

parents(norid)
Parameters

  • var (Union[int,str]) – a variable’s id (int) or name

  • 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()
Returns

the list of the nodes Ids in a topological order

Return type

List

Raises

pyAgrum.InvalidDirectedCycle – If this graph contains cycles

utility(*args)
Parameters

var (Union[int,str]) – a variable’s id (int) or name

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

Inference for Influence Diagram

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

pyAgrum.OperationNotAllowed – If no inference have yet been made

pyAgrum.InvalidNode

If node given in parmaeter is not a decision node

Return type

Potential

posterior(*args)
Return type

Potential

posteriorUtility(*args)
Return type

Potential

reducedGraph()
Return type

DAG

reducedLIMID()
Return type

InfluenceDiagram

reversePartialOrder()
setEvidence(evidces)

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

Parameters

evidces (dict) – a dict of evidences

Raises
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