Influence Diagram and LIMIDS

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]

adjacencyMatrix()

adjacency matrix from a graph/graphical models

Compute the adjacency matrix of a pyAgrum’s graph or graphical models (more generally an object that has nodes, children/parents or neighbours methods)

Returns:

adjacency matrix (as numpy.ndarray) with nodeId as key.

Return type:

numpy.ndarray

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

beginTopologyTransformation()
Return type:

None

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/graphical models

Compute the connected components of a pyAgrum’s graph or graphical models (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

endTopologyTransformation()
Return type:

None

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

Check if a node with this name or id exists

Parameters:

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

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(*args)
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 or str) – the default domain size or the default domain 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

pyAgrum.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:

pyAgrum.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

properties()
Return type:

List[str]

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

Notes

A convenient shortcut for g.variableFromName(name) is g[name].

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)

Adds a new evidence on a node (might be soft or hard).

Parameters:

  • id (int) – a node Id

  • nodeName (int) – a node name

  • val – (int) a node value

  • val – (str) the label of the node value

  • vals (list) – a list of values

Raises:
Return type:

None

addNoForgettingAssumption(*args)
Return type:

None

chgEvidence(*args)

Change the value of an already existing evidence on a node (might be soft or hard).

Parameters:

  • id (int) – a node Id

  • nodeName (int) – a node name

  • val (intstr) – a node value or the label of the node value

  • vals (List[float]) – a list of values

Raises:
Return type:

None

clear()
Return type:

None

eraseAllEvidence()

Remove all evidence.

Return type:

None

eraseEvidence(*args)

Remove the evidence, if any, corresponding to the node Id or name.

Parameters:

  • id (int) – a node Id

  • nodeName (int) – a node name

Raises:

pyAgrum.IndexError – If the node does not belong to the Bayesian network

Return type:

None

hardEvidenceNodes()
Returns:

the set of nodes with hard evidence

Return type:

set

hasEvidence(*args)
Parameters:

  • id (int) – a node Id

  • nodeName (str) – a node name

Returns:

True if some node(s) (or the one in parameters) have received evidence

Return type:

bool

Raises:

pyAgrum.IndexError – If the node does not belong to the Bayesian network

hasHardEvidence(nodeName)
Parameters:

  • id (int) – a node Id

  • nodeName (str) – a node name

Returns:

True if node has received a hard evidence

Return type:

bool

Raises:

pyAgrum.IndexError – If the node does not belong to the Bayesian network

hasNoForgettingAssumption()
Return type:

bool

hasSoftEvidence(*args)
Parameters:

  • id (int) – a node Id

  • nodeName (str) – a node name

Returns:

True if node has received a soft evidence

Return type:

bool

Raises:

pyAgrum.IndexError – If the node does not belong to the Bayesian network

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

check wether the influence diagram is solvable or not

Returns:

True if the influence diagram is solvable

Return type:

bool

junctionTree()
Returns:

the current junction tree

Return type:

pyAgrum.CliqueGraph

makeInference()

Perform the heavy computations needed to compute the optimal decisions.

Return type:

None

meanVar(*args)
Parameters:

  • id (int) – a node Id

  • nodeName (str) – a node name

Returns:

a dictionary with the mean and variance of the node (after the inference)

Return type:

dict[str, float]

nbrEvidence()
Returns:

the number of evidence entered into the Bayesian network

Return type:

int

nbrHardEvidence()
Returns:

the number of hard evidence entered into the Bayesian network

Return type:

int

nbrSoftEvidence()
Returns:

the number of soft evidence entered into the Bayesian network

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

Return type:

Potential

pyAgrum.InvalidNode

If node given in parmaeter is not a decision node

posterior(*args)

Returns the posterior of a chance or a decision node (after optimisation).

Parameters:

  • var (int) – the node Id of the node for which we need a posterior probability

  • nodeName (str) – the node name of the node for which we need a posterior probability

Returns:

a const ref to the posterior probability of the node

Return type:

pyAgrum.Potential

posteriorUtility(*args)

Returns the posterior utiliyt of a utility node (after optimisation) depending on decision nodes, if any.

Parameters:

  • var (int) – the node Id of the node for which we need a posterior probability

  • nodeName (str) – the node name of the node for which we need a posterior probability

Returns:

a const ref to the posterior utility of the utility node

Return type:

pyAgrum.Potential

reducedGraph()

Returns the DAG build to solve the influence diagram.

Returns:

a copy of the reduced graph

Return type:

pyAgrum.DAG

reducedLIMID()

Returns the (reduced) LIMID build to solve the influence diagram.

Returns:

a copy of the reduced influence Diagram (LIMID)

Return type:

pyAgrum.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: